@kindgi/agents 0.1.4 → 0.1.5-rc.0

package/src/handlers/dispatch-tools.ts

@@ -5,7 +5,7 @@ import type { ModelMessage, ModelToolCall } from '@kindgi/capabilities';
 import type { NodeContext, NodeHandler } from '@kindgi/handler';
 import { WaitpointCancelledError } from '@kindgi/handler';
 import { stricterToolHitlRule } from '@kindgi/policy-contract';
-import { invokeTool } from '@kindgi/tools';
+import { invokeTool, toolCallRecordKey } from '@kindgi/tools';
 import type { Tool, ToolContext } from '@kindgi/tools';
 
 import { emitTurnEvent } from '../streaming.js';
@@ -259,7 +259,7 @@ export function buildDispatchToolsHandler(ctx: TurnContext): NodeHandler {
               arguments: call.arguments,
               gated: gate !== undefined,
             });
-      if (replayed !== undefined && replayed.kind !== 'live') {
+      if (replayed !== undefined && replayed.kind !== 'live' && replayed.kind !== 'recomputed') {
         const replayStarted = Date.now();
         await emitTurnEvent(ctx.bindings.onEvent, {
           kind: 'tool.started',
@@ -386,7 +386,9 @@ export function buildDispatchToolsHandler(ctx: TurnContext): NodeHandler {
         continue;
       }
 
-      const dispatched = await dispatchOne(ctx, tool, call, kctx.runId as unknown as string);
+      // A replay's live call reads the env the past run's call saw.
+      const replayEnv = replayed?.kind === 'live' ? replayed.env : undefined;
+      const dispatched = await dispatchOne(ctx, tool, call, kctx, replayEnv);
       if (dispatched.kind === 'err') {
         await emitTurnEvent(ctx.bindings.onEvent, {
           kind: 'tool.failed',
@@ -421,7 +423,10 @@ export function buildDispatchToolsHandler(ctx: TurnContext): NodeHandler {
         invocationId: call.id,
         output: dispatched.value.persisted.content,
         durationMs: Date.now() - toolStarted,
-        ...(replayed !== undefined && { replay: replayed.kind }),
+        // A recomputed call ran, as a live one does.
+        ...(replayed !== undefined && {
+          replay: replayed.kind === 'recomputed' ? ('live' as const) : replayed.kind,
+        }),
       });
     }
 
@@ -575,7 +580,8 @@ async function dispatchOne(
   ctx: TurnContext,
   tool: Tool,
   call: ModelToolCall,
-  runId: string,
+  kctx: NodeContext,
+  replayEnv?: Readonly<Record<string, string>>,
 ): Promise<
   | {
       readonly kind: 'ok';
@@ -596,6 +602,8 @@ async function dispatchOne(
       };
     }
 > {
+  const runId = kctx.runId as unknown as string;
+  const toolId = tool.id as unknown as string;
   const toolCtx: ToolContext = {
     tenantId: ctx.input.tenantId,
     runId,
@@ -610,6 +618,12 @@ async function dispatchOne(
     ...(ctx.bindings.resolveSecret !== undefined && { resolveSecret: ctx.bindings.resolveSecret }),
     // The pinned settings blocks' values, by block id.
     ...(ctx.blocks !== undefined && { settings: ctx.blocks.settings }),
+    // The call's durable decisions (its resolved env): this step's own
+    // record, keyed by the call and the tool (`toolCallRecordKey`).
+    record: (key, decide) =>
+      kctx.record(toolCallRecordKey({ toolId, key, callId: call.id }), decide),
+    // A replay's live call: the past run's env values for the tool.
+    ...(replayEnv !== undefined && { env: replayEnv }),
   };
   const result = await invokeTool(tool, call.arguments, toolCtx);
   if (result.kind === 'err') {

package/src/handlers/errors.ts

@@ -27,7 +27,22 @@ export type InvokeAgentError =
   | UnresolvedGuardrailError
   | OutputSchemaViolationError
   | TenantPolicyUnavailableError
-  | RunSnapshotError;
+  | RunSnapshotError
+  | SemanticUnavailableError;
+
+/**
+ * A retrieval intent searches by meaning (`mode: 'semantic'`) and the
+ * runtime has no embeddings. The turn fails rather than retrieve nothing
+ * without a word; the operator turns embeddings on
+ * (`KINDGI_MEMORY_EMBEDDINGS`), or the agent asks for `both` (which runs
+ * its keyword half without them).
+ */
+export interface SemanticUnavailableError {
+  readonly code: 'semantic-unavailable';
+  readonly message: string;
+  /** The intent's position in the agent's `retrieval`. */
+  readonly intent: number;
+}
 
 /**
  * A turn being resumed can't be rebuilt from its snapshot:

package/src/handlers/evaluate-guardrails.ts

@@ -27,7 +27,12 @@ import { parseJsonAnswer } from './structured-output.js';
  * `halt` throws, so the run fails and the response never reaches the
  * conversation; failures with any other action are stashed on `ctx` for
  * `compose-result` to surface in `AgentTurnResult.violations`. Every
- * failure emits a `guardrail.violated` event. Also records the
+ * failure emits a `guardrail.violated` event. A guardrail whose check
+ * couldn't run (no such check, a bad configuration) emits
+ * `guardrail.error` and gets a provenance node of its own; a `halt`
+ * guardrail's error fails the turn too (it fails closed, as a
+ * `guardrail-violation` whose `evaluationErrors` say why), and the step's
+ * output lists every error, so the journal shows it. Also records the
  * response's `model-output` provenance node, which the guardrail checks
  * link to.
  */
@@ -100,7 +105,7 @@ export function buildEvaluateGuardrailsHandler(ctx: TurnContext): NodeHandler {
       judgeUsageSink(ctx, kctx),
     );
     throwIfJudgeCallsUnrecorded(outcomes);
-    const categorized = categorizeOutcomes(outcomes);
+    const categorized = categorizeOutcomes(outcomes, ctx.guardrails);
 
     const allViolations = [...categorized.blocking, ...categorized.warnings, ...categorized.other];
     for (const v of allViolations) {
@@ -132,8 +137,39 @@ export function buildEvaluateGuardrailsHandler(ctx: TurnContext): NodeHandler {
       }
     }
 
-    if (categorized.blocking.length > 0) {
-      const message = describeBlockingViolations(categorized.blocking);
+    for (const e of categorized.errors) {
+      await emitTurnEvent(ctx.bindings.onEvent, {
+        kind: 'guardrail.error',
+        guardrailId: e.guardrailId,
+        ...(e.action !== undefined && { action: e.action }),
+        ...(e.severity !== undefined && { severity: e.severity }),
+        code: e.code,
+        message: e.message,
+      });
+      if (ctx.provenance !== undefined) {
+        ctx.provenance.addNode({
+          id: `guardrail-check:${e.guardrailId}`,
+          kind: 'guardrail-check',
+          timestamp: evaluatedAt,
+          attributes: {
+            guardrailId: e.guardrailId,
+            ...(e.action !== undefined && { action: e.action }),
+            ...(e.severity !== undefined && { severity: e.severity }),
+            evaluated: false,
+            error: e.code,
+            reason: e.message,
+          },
+        });
+        ctx.provenance.addEdge({
+          from: `guardrail-check:${e.guardrailId}`,
+          to: `model-output:${ctx.usage.steps}`,
+          kind: 'influenced-by',
+        });
+      }
+    }
+
+    if (categorized.blocking.length > 0 || categorized.blockingErrors.length > 0) {
+      const message = describeBlockingViolations(categorized.blocking, categorized.blockingErrors);
       await emitTurnEvent(ctx.bindings.onEvent, {
         kind: 'turn.failed',
         conversationId: ctx.input.conversationId,
@@ -154,6 +190,13 @@ export function buildEvaluateGuardrailsHandler(ctx: TurnContext): NodeHandler {
       blocking: categorized.blocking.length,
       warnings: categorized.warnings.length,
       other: categorized.other.length,
+      // The journal records the step's output: a check that couldn't run shows there.
+      errors: categorized.errors.map((e) => ({
+        guardrailId: e.guardrailId,
+        ...(e.action !== undefined && { action: e.action }),
+        code: e.code,
+        message: e.message,
+      })),
     };
   };
 }

package/src/handlers/history.ts

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { AppendMessageInput } from '../conversation-binding.js';
+import { runUserId } from '../remember.js';
+import type { ConversationMessage } from '../types.js';
+
+import type { TurnContext } from './context.js';
+import { throwAgentTurnFailure } from './errors.js';
+
+/**
+ * The messages a turn's prompt carries as history: the newest
+ * `conversationPolicy.historyLimit` before its user message, or all of
+ * them without a limit. The binding reads only those (`beforeSequence`,
+ * `last`); one that ignores the bounds returns every message, and the
+ * window is kept here.
+ */
+export async function readHistory(ctx: TurnContext): Promise<readonly ConversationMessage[]> {
+  const historyLimit = ctx.input.agent.conversationPolicy?.historyLimit;
+  const before = ctx.userMessage?.sequence;
+  const messages = await ctx.bindings.conversationBinding.readMessages({
+    tenantId: ctx.input.tenantId,
+    conversationId: ctx.input.conversationId,
+    ...(before !== undefined && { beforeSequence: before }),
+    ...(historyLimit !== undefined && { last: historyLimit }),
+  });
+  if (messages.kind === 'err') throwAgentTurnFailure(messages.error);
+  // The user message just appended is the composer's last element, not history.
+  const earlier = messages.value.filter((m) => before === undefined || m.sequence < before);
+  return historyLimit === undefined
+    ? earlier
+    : earlier.slice(Math.max(0, earlier.length - historyLimit));
+}
+
+/**
+ * Where the prompt's history starts: `same-conversation` recall reads
+ * only older messages. `undefined` when the prompt carries the whole
+ * conversation (no `historyLimit`).
+ */
+export async function historyStart(ctx: TurnContext): Promise<number | undefined> {
+  if (ctx.input.agent.conversationPolicy?.historyLimit === undefined) return undefined;
+  const history = await readHistory(ctx);
+  return history[0]?.sequence ?? ctx.userMessage?.sequence;
+}
+
+/**
+ * What the conversation-recall index keeps with a message this turn
+ * appends (`AppendMessageInput.recall`): the user it acts for and the
+ * run's segment path, which the conversation row doesn't have.
+ */
+export function recallOf(ctx: TurnContext): NonNullable<AppendMessageInput['recall']> {
+  const userId = runUserId(ctx.input.principal);
+  return {
+    ...(userId !== undefined && { userId: userId as unknown as string }),
+    ...(ctx.input.segments !== undefined && { segments: ctx.input.segments }),
+  };
+}

package/src/handlers/persist-final-message.ts

@@ -11,6 +11,7 @@ import type { ConversationMessage } from '../types.js';
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
 import { finalIteration } from './final-iteration.js';
+import { recallOf } from './history.js';
 
 /**
  * Persist the turn's terminal assistant message (non-intermediate —
@@ -47,6 +48,7 @@ export function buildPersistFinalMessageHandler(ctx: TurnContext): NodeHandler {
         role: 'agent',
         content: assistantMsg.content ?? '',
         actor: ctx.input.agent.id,
+        recall: recallOf(ctx),
       });
       if (persist.kind === 'err') throwAgentTurnFailure(persist.error);
       finalMessage = persist.value;

package/src/handlers/persist-user-message.ts

@@ -8,6 +8,7 @@ import type { ConversationMessage } from '../types.js';
 
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
+import { recallOf } from './history.js';
 import { addInputNode } from './turn-provenance.js';
 
 /**
@@ -44,6 +45,7 @@ export function buildPersistUserMessageHandler(ctx: TurnContext): NodeHandler {
       role: 'user',
       content: ctx.input.userMessage,
       ...(ctx.input.participantId !== undefined && { actor: ctx.input.participantId }),
+      recall: recallOf(ctx),
     });
     if (persisted.kind === 'err') throwAgentTurnFailure(persisted.error);
 

package/src/handlers/public-types.ts

@@ -4,9 +4,15 @@
 import type { Principal } from '@kindgi/authz';
 import type { ProviderRegistry, TenantPolicy, UsageSink } from '@kindgi/capabilities';
 import type { EmbeddingProviderRegistry } from '@kindgi/embedding';
-import type { MemoryQueryBinding } from '@kindgi/memory';
+import type { MemoryQueryBinding, MemoryRememberBinding } from '@kindgi/memory';
 import type { PolicyRegistry } from '@kindgi/policy-contract';
-import type { ParentRunRef, RunBinding, RunReplayRef } from '@kindgi/runtime';
+import type {
+  ParentRunRef,
+  RunBinding,
+  RunIdempotencyKey,
+  RunReplayRef,
+  RunTriggerRef,
+} from '@kindgi/runtime';
 import type { ToolRegistry, ToolSecretRef } from '@kindgi/tools';
 import type {
   AgentVersionVia,
@@ -80,6 +86,10 @@ export interface InvokeAgentInput {
    * is refused when that isn't wired), and only a read-only tool can run.
    */
   readonly replay?: RunReplayRef;
+  /** Start the turn's run at most once per key (`RunIdempotencyKey`). */
+  readonly idempotencyKey?: RunIdempotencyKey;
+  /** Set when a trigger starts the turn; its run records it (`RunTriggerRef`). */
+  readonly trigger?: RunTriggerRef;
   readonly participantId?: string;
   readonly abortSignal?: AbortSignal;
   /**
@@ -142,6 +152,12 @@ export interface InvokeAgentBindings extends GuardrailsBindings {
    * touches a database client directly for memory operations.
    */
   readonly memoryBinding: MemoryQueryBinding;
+  /**
+   * Where an agent that declares `memory.remember` stores what it
+   * remembers (the `kindgi_remember` tool). Absent: the tool still
+   * shows, and a call answers that this host can't remember.
+   */
+  readonly memoryWriter?: MemoryRememberBinding;
   /**
    * Caller-plugged conversation store. Every open / get / list /
    * close / delete / appendMessage / readMessages inside the agent

package/src/handlers/rehydrate.ts

@@ -16,7 +16,7 @@
  *   - the messages the turn stored come back from the conversation, from
  *     the turn's user message (`persist-user-message` journals its
  *     sequence);
- *   - the retrieved facts come from `run-retrievals`' journaled output;
+ *   - the retrieved facts and recalled messages come from `run-retrievals`' journaled output;
  *   - usage is summed from the journaled model calls, so the step and
  *     cost budgets count the whole turn.
  *
@@ -44,7 +44,7 @@ import type { LoopContext } from '@kindgi/handler';
 import { type JournalEntry, type ValueRecordedPayload, bodyStepKey } from '@kindgi/runtime';
 import type { Timestamp } from '@kindgi/types';
 
-import type { ConversationMessage, RetrievedFact } from '../types.js';
+import type { ConversationMessage, RecalledMemory, RetrievedFact } from '../types.js';
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
 import { readGateDecision } from './gate-decision.js';
@@ -142,11 +142,12 @@ export async function rehydrateTurnContext(
     ctx.storedBeforePark = storedBeforePark(ctx, steps);
   }
 
-  const retrievals = outputOf<{ readonly retrieved?: readonly RetrievedFact[] }>(
-    steps,
-    'run-retrievals',
-  );
+  const retrievals = outputOf<{
+    readonly retrieved?: readonly RetrievedFact[];
+    readonly recalled?: readonly RecalledMemory[];
+  }>(steps, 'run-retrievals');
   if (retrievals?.retrieved !== undefined) ctx.retrieved = retrievals.retrieved;
+  if (retrievals?.recalled !== undefined) ctx.recalled = retrievals.recalled;
 
   for (const s of steps.filter((s) => s.nodeId === 'model-call' && s.inLoop)) {
     const out = s.output as {
@@ -167,7 +168,7 @@ export async function rehydrateTurnContext(
     addModelWarnings(ctx, out.warnings);
   }
   ctx.toolApprovals = toolApprovalsOf(journal);
-  rebuildProvenance(ctx, steps, retrievals?.retrieved);
+  rebuildProvenance(ctx, steps, retrievals?.retrieved, retrievals?.recalled);
   rehydrateReplay(ctx, journal);
   return true;
 }
@@ -236,11 +237,14 @@ function rebuildProvenance(
   ctx: TurnContext,
   steps: readonly StepRecord[],
   retrieved: readonly RetrievedFact[] | undefined,
+  recalled: readonly RecalledMemory[] | undefined,
 ): void {
   const input = ctx.userMessage;
   if (ctx.provenance === undefined || input === undefined) return;
   addInputNode(ctx.provenance, input);
-  if (retrieved !== undefined) addRetrievalNodes(ctx.provenance, retrieved, input);
+  if (retrieved !== undefined) {
+    addRetrievalNodes(ctx.provenance, ctx.input.agent.retrieval, retrieved, input, recalled ?? []);
+  }
 
   const storedByStep = new Map<number, readonly ConversationMessage[]>();
   for (const s of steps.filter((s) => s.nodeId === 'dispatch-tools' && s.inLoop)) {

package/src/handlers/remember-tool.ts

@@ -0,0 +1,200 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * The built-in `kindgi_remember` tool, built for each turn of an
+ * agent that declares `memory.remember`. It dispatches like any tool (the
+ * agent's `hitl.tools` policy, replay and the tool error policy apply), but
+ * it isn't in the tool registry: its input schema lists the agent's own
+ * fact types, and its handler places the fact from the run, not from the
+ * model's arguments.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import type { ModelToolDefinition } from '@kindgi/capabilities';
+import { type Tool, type ToolContext, defineTool } from '@kindgi/tools';
+import type { Timestamp, ToolId } from '@kindgi/types';
+
+import {
+  DEFAULT_REMEMBER_DAYS,
+  MAX_REMEMBER_KEY,
+  MAX_REMEMBER_TEXT,
+  REMEMBER_TOOL_ID,
+  REMEMBER_TOOL_VERSION,
+  rememberTarget,
+  reviewReasons,
+  runUserId,
+} from '../remember.js';
+import type { RememberPolicy } from '../types.js';
+
+import type { TurnContext } from './context.js';
+
+/** What the model sends. */
+interface RememberArgs {
+  readonly type: string;
+  readonly content: string;
+  readonly key?: string;
+  readonly validUntil?: string;
+}
+
+/** What the model reads back, and what the turn's provenance is rebuilt from. */
+export interface RememberToolOutput {
+  /**
+   * `remembered`: stored and used from now on. `pending-review`: stored,
+   * but no read sees it until a person approves it. `not-remembered`:
+   * nothing was stored (`reason` says why).
+   */
+  readonly status: 'remembered' | 'pending-review' | 'not-remembered';
+  readonly factId?: string;
+  readonly version?: number;
+  /** `superseded` when it replaced the value this agent kept for the same `key`. */
+  readonly outcome?: 'created' | 'superseded' | 'replayed';
+  readonly reason?: string;
+}
+
+type TurnTools = NonNullable<TurnContext['tools']>;
+
+/** The turn's tools, with `remember` added when the agent declares it. */
+export function withRememberTool(ctx: TurnContext, tools: TurnTools): TurnTools {
+  const policy = ctx.input.agent.memory?.remember;
+  if (policy === undefined) return tools;
+  const tool = rememberTool(ctx, policy);
+  const definition: ModelToolDefinition = {
+    name: tool.id,
+    description: tool.description,
+    inputSchema: tool.input as Readonly<Record<string, unknown>>,
+  };
+  const byName = new Map(tools.byName);
+  byName.set(tool.id, {
+    tool,
+    resolvedVersion: REMEMBER_TOOL_VERSION,
+    requestedRange: REMEMBER_TOOL_VERSION,
+  });
+  return { definitions: [...tools.definitions, definition], byName };
+}
+
+function rememberTool(ctx: TurnContext, policy: RememberPolicy): Tool {
+  const defined = defineTool<RememberArgs, RememberToolOutput>({
+    id: REMEMBER_TOOL_ID as ToolId,
+    version: REMEMBER_TOOL_VERSION,
+    description: description(policy),
+    input: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['type', 'content'],
+      properties: {
+        type: { type: 'string', enum: [...policy.types], description: 'What kind of fact it is.' },
+        content: {
+          type: 'string',
+          minLength: 1,
+          maxLength: MAX_REMEMBER_TEXT,
+          description: 'The fact, in one or two plain sentences.',
+        },
+        key: {
+          type: 'string',
+          minLength: 1,
+          maxLength: MAX_REMEMBER_KEY,
+          description:
+            'Optional name for what it is about (e.g. "preferred-language"). A new fact with the same type and key replaces the one you remembered before.',
+        },
+        validUntil: {
+          type: 'string',
+          format: 'date-time',
+          description: 'Optional: when it stops being true.',
+        },
+      },
+    },
+    output: {
+      type: 'object',
+      required: ['status'],
+      properties: {
+        status: { type: 'string', enum: ['remembered', 'pending-review', 'not-remembered'] },
+        factId: { type: 'string' },
+        version: { type: 'integer' },
+        outcome: { type: 'string', enum: ['created', 'superseded', 'replayed'] },
+        reason: { type: 'string' },
+      },
+    },
+    mutating: true,
+    effects: [{ kind: 'writes', resource: 'memory:facts' }],
+    handler: (args, toolCtx) => remember(ctx, policy, args, toolCtx),
+  });
+  // The schemas are fixed here: a failure is a bug, not an input problem.
+  if (defined.kind === 'err') {
+    throw new Error(`the built-in remember tool failed to build: ${defined.error.message}`);
+  }
+  return defined.value as Tool;
+}
+
+function description(policy: RememberPolicy): string {
+  const whose =
+    policy.scope === 'same-user'
+      ? 'the person you are talking with'
+      : policy.scope === 'same-conversation'
+        ? 'this conversation'
+        : policy.scope === 'same-project'
+          ? 'everyone in this project, after a person approves it'
+          : 'everyone, after a person approves it';
+  return `Use ${REMEMBER_TOOL_ID} to remember a fact for later conversations, for ${whose}. Use it for lasting facts and preferences you were told, not for this turn's working notes. It is stored as unverified.`;
+}
+
+async function remember(
+  ctx: TurnContext,
+  policy: RememberPolicy,
+  args: RememberArgs,
+  toolCtx: ToolContext,
+): Promise<RememberToolOutput> {
+  const writer = ctx.bindings.memoryWriter;
+  if (writer === undefined) {
+    return notRemembered('Not remembered: this runtime cannot store agent memories.');
+  }
+  const userId = runUserId(ctx.input.principal);
+  const participantId = ctx.conversation?.participantId ?? ctx.input.participantId;
+  const target = rememberTarget(policy.scope, {
+    tenantId: ctx.input.tenantId,
+    projectId: ctx.input.projectId,
+    conversationId: ctx.input.conversationId,
+    ...(participantId !== undefined && { participantId }),
+    ...(userId !== undefined && { userId }),
+  });
+  if (target.kind === 'refused') return notRemembered(target.reason);
+  const toolIds = [...(ctx.tools?.byName.keys() ?? [])].filter((id) => id !== REMEMBER_TOOL_ID);
+  const reasons = reviewReasons(policy, args.content, toolIds);
+  const written = await writer.remember({
+    tenantId: ctx.input.tenantId,
+    scope: target.scope,
+    type: args.type,
+    content: { text: args.content, ...(args.key !== undefined && { key: args.key }) },
+    subjects: target.subjects,
+    agent: {
+      id: ctx.input.agent.id as unknown as string,
+      version: ctx.input.agent.version as unknown as string,
+    },
+    generatedBy: {
+      runId: toolCtx.runId as unknown as string,
+      stepId: `step:${ctx.usage.steps}`,
+      // Dispatch always passes the call's id; without one, the write can't
+      // be matched to an earlier attempt, but never to another call's.
+      toolCallId: toolCtx.requestId ?? randomUUID(),
+    },
+    keepDays: policy.keepDays ?? DEFAULT_REMEMBER_DAYS,
+    ...(args.validUntil !== undefined && { validUntil: args.validUntil as Timestamp }),
+    ...(reasons.length > 0 && { review: { reasons } }),
+  });
+  // The store failed: the turn's tool error policy decides what happens.
+  if (written.kind === 'err') throw new Error(written.error.message);
+  const { fact, outcome } = written.value;
+  const pending = fact.review === 'pending';
+  return {
+    status: pending ? 'pending-review' : 'remembered',
+    factId: fact.id as unknown as string,
+    version: fact.version,
+    outcome,
+    ...(pending && { reason: 'A person reviews it before it is used.' }),
+  };
+}
+
+function notRemembered(reason: string): RememberToolOutput {
+  return { status: 'not-remembered', reason };
+}