agenr 3.0.0 → 3.1.0

package/dist/adapters/skeln/index.js

@@ -1,12 +1,12 @@
 import {
   CLOSE_EVENT_HISTORY_LIMIT,
   EPISODE_SUMMARY_TIMEOUT_MS,
+  FETCH_TOOL_PARAMETERS,
   RECALL_TOOL_PARAMETERS,
   SESSION_LINEAGE_REASONS,
   STORE_TOOL_PARAMETERS,
   UPDATE_TOOL_PARAMETERS,
   WORKING_CANDIDATE_PROMOTION_STATUSES,
-  asRecord,
   buildRecallToolServices,
   composeHostPluginServices,
   createClaimExtractionFromAgenrConfig,
@@ -15,8 +15,6 @@ import {
   embedEpisodeSummaryWithinBudget,
   extractRecentTurnsFromMessages,
   formatAgenrSessionStartRecall,
-  formatErrorMessage,
-  formatTargetSelector,
   formatUnifiedRecallResults,
   isCloseManagedStatus,
   isModelVisibleOperationType,
@@ -28,6 +26,7 @@ import {
   normalizeOptionalString,
   normalizePluginInjectionMemoryPolicyConfig,
   normalizePromptText,
+  parseFetchToolParams,
   parseRecallToolParams,
   parseStoreToolParams,
   parseUpdateToolParams,
@@ -35,31 +34,36 @@ import {
   resolveSessionIdentityKey,
   resolveSessionStartPolicy,
   resolveWorkingContextGate,
+  runFetchMemoryTool,
   runRecallMemoryTool,
   runSessionStart,
   runStoreMemoryTool,
   runUpdateMemoryTool,
-  sanitizeUpdateToolParams,
   writeBoundedSingleTranscriptEpisode
-} from "../../chunk-MYZ2CWY6.js";
+} from "../../chunk-E2DHUFZK.js";
 import {
-  createSingleTranscriptDiscoveryPort
-} from "../../chunk-LAXNNWHM.js";
+  asRecord,
+  createSingleTranscriptDiscoveryPort,
+  formatErrorMessage,
+  formatTargetSelector,
+  sanitizeFetchToolParams,
+  sanitizeUpdateToolParams
+} from "../../chunk-EEEL53X4.js";
 import {
-  buildRecallToolDetails,
   formatAgenrBeforeTurnRecall,
   runBeforeTurn
-} from "../../chunk-575MUIW5.js";
+} from "../../chunk-V5CDMHRN.js";
 import {
   AGENR_FEATURE_FLAG_KEYS,
   DEFAULT_AGENR_FEATURE_FLAGS,
+  buildRecallToolDetails,
   createLlmClient,
   isRecord,
   readOptionalFiniteNumber,
   readOptionalTrimmedString,
   resolveLlmApiKey,
   resolveModel
-} from "../../chunk-ELR2HSVC.js";
+} from "../../chunk-NNO2V4GH.js";
 import "../../chunk-5LADPJ4C.js";
 
 // src/adapters/skeln/config.ts
@@ -426,6 +430,7 @@ function buildAgenrSkelnMemoryPromptSection() {
     "## Memory Recall",
     "Before answering anything about prior work, decisions, preferences, people, dates, unfinished work, or past sessions, call agenr_recall first. Session-start recall is automatic, and conservative before-turn recall may also appear as injected background context; use agenr_recall mid-session when you need context you do not already have.",
     "agenr_recall supports exact fact recall plus historical and episodic recall behind one tool: use mode=entries for exact facts, decisions, thresholds, and versions; use mode=auto for prior-state questions like what was the previous approach, what did we use before, or what changed from X to Y; use mode=episodes when you explicitly want session narrative recall.",
+    "agenr_recall returns truncated entry previews with ids, scores, and preview_truncated flags. Call agenr_fetch with id when preview_truncated=true or exact stored wording is required.",
     "When Agenr injects memory automatically, treat it as non-user background context and use it silently when relevant rather than forcing it into the reply.",
     "Use agenr_store for durable memory, not for logging. Store only the durable takeaway, standing rule, preference, risk, lesson, or relationship - not progress logs or data already canonical elsewhere.",
     "Use agenr_update to correct metadata on an existing entry. Use agenr_store with supersedes for substantive content replacement.",
@@ -1087,10 +1092,16 @@ function deriveSkelnSessionIdFromFilePath(filePath) {
 }
 
 // src/adapters/skeln/episode/bounded-session-episode.ts
+function resolveSkelnSessionEpisodeTarget(context) {
+  return {
+    sessionId: String(context.sessionManager.getSessionId()),
+    sessionFile: resolveSessionFile(context)
+  };
+}
 async function writeSkelnBoundedSessionEpisode(params) {
   const logger = params.logger ?? console;
-  const sessionFile = resolveSessionFile(params.context);
-  const sessionId = String(params.context.sessionManager.getSessionId());
+  const sessionFile = params.target.sessionFile;
+  const sessionId = params.target.sessionId;
   const summaryDeadlineMs = Date.now() + EPISODE_SUMMARY_TIMEOUT_MS;
   if (!sessionFile) {
     logger.info(`[agenr] ${params.actionLabel} skipped for ${params.skipDetails} reason=no_session_file`);
@@ -1153,20 +1164,58 @@ var SKELN_PHASE4_SHUTDOWN_EPISODE_ACTIVITY_THRESHOLD = {
   minDurationMs: 20 * 60 * 1e3
 };
 async function writeSkelnShutdownEpisode(params) {
-  const sessionId = String(params.context.sessionManager.getSessionId());
   await writeSkelnBoundedSessionEpisode({
-    context: params.context,
+    target: params.target,
     services: params.services,
     logger: params.logger,
     actionLabel: "skeln shutdown episode write",
     genVersion: SKELN_EPISODE_GENERATOR_VERSION,
     activityThreshold: SKELN_PHASE4_SHUTDOWN_EPISODE_ACTIVITY_THRESHOLD,
     buildSourceRef: (sessionFile) => sessionFile,
-    logContext: `session=${sessionId} key=skeln:${sessionId}`,
-    skipDetails: `session=${sessionId}`
+    logContext: `session=${params.target.sessionId} key=skeln:${params.target.sessionId}`,
+    skipDetails: `session=${params.target.sessionId}`
   });
 }
 
+// src/adapters/skeln/episode/shutdown-episode-write.ts
+function buildSkelnSessionShutdownEpisodeWork(params) {
+  const target = resolveSkelnSessionEpisodeTarget(params.context);
+  const shutdownWork = params.event.reason === "quit" ? writeScopedSkelnShutdownEpisode(params.servicesPromise, target, params.logger).finally(() => closeSkelnServicesAfterShutdown(params.servicesPromise)) : writeScopedSkelnShutdownEpisode(params.servicesPromise, target, params.logger);
+  return shutdownWork.catch((error) => {
+    logSkelnShutdownEpisodeFailure(error, params.logger);
+  });
+}
+function scheduleSkelnSessionShutdownEpisodeWrite(params) {
+  const work = buildSkelnSessionShutdownEpisodeWork(params);
+  if (params.event.reason === "quit" && params.event.deferWork) {
+    params.event.deferWork(work);
+    return Promise.resolve();
+  }
+  if (params.event.reason === "quit") {
+    return work;
+  }
+  void work;
+  return Promise.resolve();
+}
+function logSkelnShutdownEpisodeFailure(error, logger) {
+  const log = logger ?? console;
+  log.warn(`[agenr] skeln shutdown episode failed: ${formatErrorMessage(error)}`);
+}
+async function closeSkelnServicesAfterShutdown(servicesPromise) {
+  try {
+    const services = await servicesPromise;
+    await services.close();
+  } catch {
+  }
+}
+async function writeScopedSkelnShutdownEpisode(servicesPromise, target, logger) {
+  const services = await servicesPromise;
+  if (!services.capabilities.shutdownEpisodes) {
+    return;
+  }
+  await writeSkelnShutdownEpisode({ target, services, logger });
+}
+
 // src/app/features/resolve.ts
 function resolveAgenrFeatureFlags(features) {
   const resolved = { ...DEFAULT_AGENR_FEATURE_FLAGS };
@@ -2525,6 +2574,109 @@ function createSkelnSessionScopeTracker() {
   };
 }
 
+// src/adapters/shared/param-readers.ts
+function readStringParam(params, key, options = {}) {
+  const value = params[key];
+  if (value === void 0 || value === null) {
+    if (options.required) {
+      throw new Error(`${options.label ?? key} is required.`);
+    }
+    return void 0;
+  }
+  if (typeof value !== "string") {
+    throw new Error(`${options.label ?? key} must be a string.`);
+  }
+  const normalized = options.trim === false ? value : value.trim();
+  if (options.required && normalized.length === 0) {
+    throw new Error(`${options.label ?? key} is required.`);
+  }
+  return normalized.length > 0 || options.trim === false ? normalized : void 0;
+}
+function readNumberParam(params, key, options = {}) {
+  const value = params[key];
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`${key} must be a number.`);
+  }
+  if (options.integer && !Number.isInteger(value)) {
+    throw new Error(`${key} must be an integer.`);
+  }
+  if (options.strict && value < 0) {
+    throw new Error(`${key} must be non-negative.`);
+  }
+  return value;
+}
+function readStringArrayParam(params, key) {
+  const value = params[key];
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new Error(`${key} must be an array of strings.`);
+  }
+  return value;
+}
+
+// src/adapters/skeln/tools/shared.ts
+var SKELN_PARAM_READER = {
+  readString: readStringParam,
+  readNumber: readNumberParam,
+  readStringArray: readStringArrayParam
+};
+function toolSchema(value) {
+  return value;
+}
+function textToolResult(text, details) {
+  return {
+    content: [{ type: "text", text }],
+    details
+  };
+}
+function toSkelnToolResult(outcome) {
+  return textToolResult(outcome.text, outcome.details);
+}
+function toolFailureResult(error) {
+  return textToolResult(formatErrorMessage(error), {
+    status: "failed"
+  });
+}
+
+// src/adapters/skeln/tools/fetch.ts
+function registerAgenrSkelnFetchTool(skeln, servicesPromise, resolveScope) {
+  skeln.registerTool({
+    name: "agenr_fetch",
+    label: "Agenr Fetch",
+    description: "Fetch the full body and metadata for one durable memory entry by id or subject.",
+    promptSnippet: "Use agenr_fetch after agenr_recall when you need the full entry body for an id shown in recall results.",
+    promptGuidelines: [
+      "Provide exactly one target selector: id or subject.",
+      "Prefer id from agenr_recall when preview_truncated=true or when exact wording matters."
+    ],
+    parameters: toolSchema(FETCH_TOOL_PARAMETERS),
+    execute: async (_toolCallId, rawParams, _signal, _onUpdate, context) => {
+      try {
+        const params = parseFetchToolParams(rawParams, SKELN_PARAM_READER);
+        const [services, scope] = await Promise.all([servicesPromise, resolveScope(context)]);
+        const outcome = await runFetchMemoryTool(params, services, {
+          extraDetails: { sessionKey: scope.sessionKey }
+        });
+        return toSkelnToolResult({
+          ...outcome,
+          details: {
+            ...outcome.details,
+            target: formatTargetSelector(params.id, params.subject),
+            sanitized: sanitizeFetchToolParams(params)
+          }
+        });
+      } catch (error) {
+        return toolFailureResult(error);
+      }
+    }
+  });
+}
+
 // src/adapters/shared/goal-tool-presentations.ts
 var COMPLETION_BUDGET_REPORT = "Goal achieved. Report final usage from this tool result's structured goal fields. If `goal.tokenBudget` is present, include token usage from `goal.tokensUsed` and `goal.tokenBudget`. If `goal.timeUsedSeconds` is greater than 0, summarize elapsed time in a concise, human-friendly form appropriate to the response language.";
 function toGoalToolGoal(workingSet) {
@@ -2707,75 +2859,6 @@ function goalFailure(code, message, details) {
   };
 }
 
-// src/adapters/shared/param-readers.ts
-function readStringParam(params, key, options = {}) {
-  const value = params[key];
-  if (value === void 0 || value === null) {
-    if (options.required) {
-      throw new Error(`${options.label ?? key} is required.`);
-    }
-    return void 0;
-  }
-  if (typeof value !== "string") {
-    throw new Error(`${options.label ?? key} must be a string.`);
-  }
-  const normalized = options.trim === false ? value : value.trim();
-  if (options.required && normalized.length === 0) {
-    throw new Error(`${options.label ?? key} is required.`);
-  }
-  return normalized.length > 0 || options.trim === false ? normalized : void 0;
-}
-function readNumberParam(params, key, options = {}) {
-  const value = params[key];
-  if (value === void 0 || value === null) {
-    return void 0;
-  }
-  if (typeof value !== "number" || !Number.isFinite(value)) {
-    throw new Error(`${key} must be a number.`);
-  }
-  if (options.integer && !Number.isInteger(value)) {
-    throw new Error(`${key} must be an integer.`);
-  }
-  if (options.strict && value < 0) {
-    throw new Error(`${key} must be non-negative.`);
-  }
-  return value;
-}
-function readStringArrayParam(params, key) {
-  const value = params[key];
-  if (value === void 0 || value === null) {
-    return void 0;
-  }
-  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
-    throw new Error(`${key} must be an array of strings.`);
-  }
-  return value;
-}
-
-// src/adapters/skeln/tools/shared.ts
-var SKELN_PARAM_READER = {
-  readString: readStringParam,
-  readNumber: readNumberParam,
-  readStringArray: readStringArrayParam
-};
-function toolSchema(value) {
-  return value;
-}
-function textToolResult(text, details) {
-  return {
-    content: [{ type: "text", text }],
-    details
-  };
-}
-function toSkelnToolResult(outcome) {
-  return textToolResult(outcome.text, outcome.details);
-}
-function toolFailureResult(error) {
-  return textToolResult(formatErrorMessage(error), {
-    status: "failed"
-  });
-}
-
 // src/adapters/skeln/tools/goal.ts
 function registerAgenrSkelnGoalAliasTools(skeln, servicesPromise, resolveScope) {
   registerGoalAliasTool(skeln, servicesPromise, resolveScope, {
@@ -3614,6 +3697,7 @@ function registerAgenrSkelnWorkTool(skeln, servicesPromise, resolveScope) {
 function registerAgenrSkelnTools(skeln, servicesPromise, resolveScope) {
   registerAgenrSkelnStoreTool(skeln, servicesPromise, resolveScope);
   registerAgenrSkelnRecallTool(skeln, servicesPromise, resolveScope);
+  registerAgenrSkelnFetchTool(skeln, servicesPromise, resolveScope);
   registerAgenrSkelnUpdateTool(skeln, servicesPromise, resolveScope);
   registerAgenrSkelnWorkTool(skeln, servicesPromise, resolveScope);
   registerAgenrSkelnGoalAliasTools(skeln, servicesPromise, resolveScope);
@@ -3630,28 +3714,28 @@ function scheduleSkelnGoalCloseEpisodePromotion(params) {
   if (!pendingEpisodic) {
     return;
   }
+  const target = resolveSkelnSessionEpisodeTarget(params.context);
   void writeSkelnGoalCloseEpisode({
-    context: params.context,
+    target,
     services: params.services,
     workingSetId: params.closeResult.workingSet.id,
     logger: params.logger
   }).catch((error) => {
     const logger = params.logger ?? console;
-    logger.warn(`[agenr] skeln goal close episode promotion failed: ${error instanceof Error ? error.message : String(error)}`);
+    logger.warn(`[agenr] skeln goal close episode promotion failed: ${formatErrorMessage(error)}`);
   });
 }
 async function writeSkelnGoalCloseEpisode(params) {
-  const sessionId = String(params.context.sessionManager.getSessionId());
   await writeSkelnBoundedSessionEpisode({
-    context: params.context,
+    target: params.target,
     services: params.services,
     logger: params.logger,
     actionLabel: "skeln goal close episode promotion",
     genVersion: SKELN_GOAL_CLOSE_EPISODE_GENERATOR_VERSION,
     activityThreshold: SKELN_GOAL_CLOSE_EPISODE_ACTIVITY_THRESHOLD,
     buildSourceRef: (sessionFile) => `${sessionFile}#working_set:${params.workingSetId}`,
-    logContext: `session=${sessionId} workingSet=${params.workingSetId}`,
-    skipDetails: `session=${sessionId} workingSet=${params.workingSetId}`
+    logContext: `session=${params.target.sessionId} workingSet=${params.workingSetId}`,
+    skipDetails: `session=${params.target.sessionId} workingSet=${params.workingSetId}`
   });
 }
 
@@ -3805,16 +3889,8 @@ function registerAgenrSkelnSessionMemoryHooks(skeln, scopeTracker, servicesPromi
 }
 async function handleSkelnSessionShutdown(servicesPromise, scopeTracker, resolveScope, event, context) {
   await routeScopedSessionMemoryTrigger(servicesPromise, resolveScope, context, (scope) => buildSkelnSessionShutdownTriggerEvent(scope, event));
-  await writeScopedSkelnShutdownEpisode(servicesPromise, context);
   clearTrackedSkelnScope(scopeTracker, context);
-  if (event.reason !== "quit") {
-    return;
-  }
-  try {
-    const services = await servicesPromise;
-    await services.close();
-  } catch {
-  }
+  await scheduleSkelnSessionShutdownEpisodeWrite({ event, context, servicesPromise });
 }
 function registerAgenrSkelnSubagentFindingHooks(skeln, servicesPromise, resolveScope) {
   skeln.on("tool_result", async (event, context) => {
@@ -3831,17 +3907,6 @@ async function routeScopedSessionMemoryTrigger(servicesPromise, resolveScope, co
     console.warn(`[agenr] session-memory trigger failed: ${formatErrorMessage(error)}`);
   }
 }
-async function writeScopedSkelnShutdownEpisode(servicesPromise, context) {
-  try {
-    const services = await servicesPromise;
-    if (!services.capabilities.shutdownEpisodes) {
-      return;
-    }
-    await writeSkelnShutdownEpisode({ context, services });
-  } catch (error) {
-    console.warn(`[agenr] skeln shutdown episode failed: ${formatErrorMessage(error)}`);
-  }
-}
 async function resolveCurrentSkelnSessionScope(context, scopeTracker, options) {
   const sessionId = String(context.sessionManager.getSessionId());
   const tracked = scopeTracker.getSessionScope(sessionId);
@@ -3886,7 +3951,7 @@ function registerAgenrSkelnFailureBoundary(skeln) {
   });
 }
 function isAgenrToolName(toolName) {
-  return toolName === "agenr_store" || toolName === "agenr_recall" || toolName === "agenr_update" || toolName === "agenr_work" || toolName === "get_goal" || toolName === "create_goal" || toolName === "update_goal";
+  return toolName === "agenr_store" || toolName === "agenr_recall" || toolName === "agenr_fetch" || toolName === "agenr_update" || toolName === "agenr_work" || toolName === "get_goal" || toolName === "create_goal" || toolName === "update_goal";
 }
 function isFailedAgenrToolDetails(details) {
   return typeof details === "object" && details !== null && "status" in details && details.status === "failed";