Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.2 KB
Raw Blame
/**
 * `remember` with `items[]`: save several facts in one call (the
 * pre-compaction "save what matters" path). Additive to the frozen
 * MEMORY_VERBS v1 `remember` contract: a call without `items` is unchanged.
 *
 * Semantics:
 *  - every item is validated (same rules as a single remember) before any is
 *    admitted; one invalid item refuses the whole call and writes nothing;
 *  - each item is then admitted as its own write request with a
 *    deterministic child request_id derived from the caller's request_id and
 *    the item index, so replaying the same request_id replays each child
 *    (committed children return their receipt, nothing is written twice);
 *  - each item's receipt is compact (status, fact id, entity, the fact it
 *    superseded, warnings, and the write state only when it is not
 *    committed); repeated hints appear
 *    once at the top level;
 *  - publication is per item: the response reports each item's status and
 *    `partial: true` when some failed. Replaying the same request_id returns
 *    the same per-item outcomes; failed items are resubmitted in a new call
 *    with a new request_id.
 */
import { createHash, randomUUID } from 'node:crypto';
import type { OperationContext } from './operations.ts';
import { OperationError } from './ops/contract.ts';
import { clientRequestIdOf, parseWriteRequestId } from './persistence/preconditions.ts';
import { CLAIM_PARAM_KEYS, claimColumns } from './facts/typed-claim.ts';
import { withRefreshFenceBudget } from './persistence/admission-retry.ts';

export const REMEMBER_BATCH_MAX = 20;
const CLAIM_KEYS: readonly string[] = CLAIM_PARAM_KEYS;
const ITEM_KEYS = new Set(['fact', 'provenance', 'entity', 'infer_entity', 'kind', 'ttl', 'visibility', 'share', 'content_origin', 'valid_from', 'replaces', ...CLAIM_KEYS]);
/** #7432: every per-item field but the claim, `replaces` and the typed claim keys is also a top-level default (an item's own value wins); `source_id` is top-level only. */
const SHARED_KEYS = [...ITEM_KEYS].filter(key => key !== 'fact' && key !== 'replaces' && !CLAIM_KEYS.includes(key)).concat('source_id');

/** Deterministic UUID for child `index` of a batch request (stable across replays). */
export function childRequestId(requestId: string, index: number): string {
  const h = createHash('sha256').update(`${requestId}\u0000remember-item\u0000${index}`).digest('hex');
  // RFC 4122 layout with version 5 / variant bits so it reads as a UUID everywhere.
  return `${h.slice(0, 8)}-${h.slice(8, 12)}-5${h.slice(13, 16)}-${((parseInt(h.slice(16, 18), 16) & 0x3f) | 0x80).toString(16)}${h.slice(18, 20)}-${h.slice(20, 32)}`;
}

type Handler = (ctx: OperationContext, p: Record<string, unknown>) => Promise<unknown>;

export interface BatchItemResult {
  index: number;
  status: string;
  request_id: string;
  [key: string]: unknown;
}

/** Runs a remember batch through the single-item handler. */
export async function runRememberBatch(ctx: OperationContext, p: Record<string, unknown>, single: Handler,
  verbError: (code: string, message: string, suggestion: string) => Error): Promise<Record<string, unknown>> {
  const items = p.items;
  if (!Array.isArray(items) || items.length < 1 || items.length > REMEMBER_BATCH_MAX) {
    throw verbError('invalid_params', `items must be an array of 1 to ${REMEMBER_BATCH_MAX} facts.`,
      'Pass items: [{ "fact": "...", "entity": "..." }, ...] with provenance on each item or once at the top level.');
  }
  if (typeof p.fact === 'string' && p.fact.trim()) {
    throw verbError('invalid_params', 'Pass either fact or items, not both.', 'Move the single fact into items, or drop items.');
  }
  if (p.replaces !== undefined) {
    throw verbError('invalid_params', 'replaces names one fact, so it cannot apply to a whole batch.',
      'Put replaces on the item it belongs to: items: [{ "fact": "...", "replaces": "<fact_id>" }].');
  }
  const sharedClaim = CLAIM_KEYS.filter(key => p[key] !== undefined);
  if (sharedClaim.length) {
    throw verbError('invalid_params', `${sharedClaim.join(', ')} describe one fact, so they cannot apply to a whole batch.`,
      'Put the typed claim on the item it belongs to: items: [{ "fact": "...", "claim_metric": "mrr", "claim_value": 50000 }].');
  }
  // #6280: an unusable request_id refuses the batch before any write (F6 accepts a UUID or a printable client id).
  if (p.request_id !== undefined) parseWriteRequestId(p.request_id);
  const shared: Record<string, unknown> = {};
  for (const key of SHARED_KEYS) if (p[key] !== undefined) shared[key] = p[key];
  const normalized = items.map((raw, index) => {
    // A bare string is the common shorthand for one fact.
    if (typeof raw === 'string') return { ...shared, fact: raw };
    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
      throw verbError('invalid_params', `items[${index}] must be an object.`, 'Each item is { "fact": "...", optional entity, kind, ttl, visibility, provenance, content_origin, valid_from }.');
    }
    const extra = Object.keys(raw).filter(k => !ITEM_KEYS.has(k));
    if (extra.length) throw verbError('invalid_params', `items[${index}] has unknown field(s): ${extra.join(', ')}.`,
      `${extra.includes('text') ? 'Rename text to fact. ' : ''}Allowed item fields: ${[...ITEM_KEYS].join(', ')}.`);
    return { ...shared, ...(raw as Record<string, unknown>) };
  });
  // All-or-none validation before any admission.
  for (const [index, item] of normalized.entries()) {
    try { await single({ ...ctx, dryRun: true }, item); } catch (e) {
      if (e instanceof OperationError) e.message = `items[${index}]: ${e.message} Nothing was saved; fix that item and resend the whole batch.`;
      throw e;
    }
  }
  if (ctx.dryRun) return { dry_run: true, action: 'remember', items: normalized.length, protocol_version: 1 };
  // F6: child ids derive from the root string the client sent, so an accepted batch replays to the same receipts.
  const rootId = typeof p.request_id === 'string' ? p.request_id : randomUUID();
  const requestId = parseWriteRequestId(rootId)!;
  const clientRequestId = clientRequestIdOf(rootId);
  const results: BatchItemResult[] = [];
  const hints = new Set<string>();
  const failures: Array<{ index: number; error: OperationError }> = [];
  // GST-1387: the items share one refresh-fence wait, so a fenced checkout delays the batch once, not once per item.
  await withRefreshFenceBudget(async () => { for (const [index, item] of normalized.entries()) {
    const child = childRequestId(rootId, index);
    try {
      const out = await single(ctx, { ...item, request_id: child }) as Record<string, unknown>;
      // Compact per-item receipt: a batch lands in the agent's context, so it carries what the agent acts on, not the full single-fact envelope.
      if (typeof out?.hint === 'string') hints.add(out.hint);
      results.push({
        index, request_id: child, status: String(out?.status ?? 'saved'),
        ...(out?.id !== undefined ? { id: out.id } : {}),
        ...(out?.entity_slug !== undefined ? { entity_slug: out.entity_slug } : {}),
        ...(out?.page !== undefined ? { page: out.page } : {}), ...(out?.visibility !== undefined ? { visibility: out.visibility } : {}),
        // GST-2446: where the item landed (a page file, or the database alone and why), as the single form reports it.
        ...(out?.persistence !== undefined ? { persistence: out.persistence } : {}), ...(out?.write_through !== undefined ? { write_through: out.write_through } : {}),
        ...(out?.superseded_fact_id !== undefined ? { superseded_fact_id: out.superseded_fact_id } : {}), ...claimColumns(out),
        ...(Array.isArray(out?.warnings) && out.warnings.length ? { warnings: out.warnings } : {}),
        ...(out?.valid_until ? { valid_until: out.valid_until } : {}),
        ...(typeof out?.state === 'string' && out.state !== 'committed' ? { state: out.state, retry_after_ms: out.retry_after_ms ?? null } : {}),
      });
    } catch (e) {
      if (!(e instanceof OperationError)) throw e;
      // #7248: an accepted item still publishing is pending, not failed; resending it would save it twice.
      if (e.writeError === 'write_pending' && e.writeRequest) {
        results.push({ index, request_id: child, status: 'pending', state: e.writeRequest.state, retry_after_ms: e.writeRequest.retry_after_ms ?? null,
          ...(e.writeRequest.target ? { target: e.writeRequest.target } : {}) });
        continue;
      }
      failures.push({ index, error: e });
      results.push({ index, request_id: child, status: 'failed', error: { code: e.code, message: e.message, ...(e.canonical ? { canonical: e.canonical } : {}), ...(e.retryable !== undefined ? { retryable: e.retryable } : {}), ...(e.writeError ? { write_error: e.writeError } : {}), ...(e.detail ? { detail: e.detail } : {}), ...(e.suggestion ? { suggestion: e.suggestion } : {}), ...(e.withdrawn ? { withdrawn: e.withdrawn } : {}) } });
    }
  } });
  const failed = results.filter(r => r.status === 'failed').length;
  const pending = results.filter(r => r.status === 'pending').length;
  // GST-1387: a batch that saved nothing is a refusal on every surface (CLI exit non-zero, MCP isError), never a success
  // envelope; its first item's error keeps that item's code and fix. An item with a receipt (accepted, or its outcome
  // unknown) keeps the per-item envelope so its child request_id is never lost.
  if (failures.length && failed === results.length && failures.every(f => !f.error.writeRequest && f.error.writeError !== 'write_outcome_unknown')) {
    const [{ index, error }] = failures as [{ index: number; error: OperationError }];
    // A fence refusal names the batch's request_id, never an item's derived id: a retry under an item's id derives new
    // item ids, so retrying it and the batch's own id would save every item twice.
    if (error.requestId === childRequestId(rootId, index)) {
      const child = error.requestId;
      error.message = error.message.replaceAll(child, () => rootId);
      error.suggestion = error.suggestion?.replaceAll(child, () => rootId);
      if (error.fix) error.fix = { ...error.fix, why: error.fix.why.replaceAll(child, () => rootId) };
      error.requestId = rootId;
    }
    error.message = `items[${index}]: ${error.message} None of the ${results.length} item(s) was saved.`;
    throw error;
  }
  return {
    ...(failures.length ? { status: 'error', error: failures[0]!.error.code, code: failures[0]!.error.code,
      message: `${failed} of ${results.length} item(s) failed (first: items[${failures[0]!.index}] ${failures[0]!.error.code}); see items[].error. Items not marked failed are stored.` } : {}),
    protocol_version: 1,
    request_id: requestId,
    ...(clientRequestId ? { client_request_id: clientRequestId } : {}),
    items: results,
    saved: results.length - failed - pending,
    failed,
    ...(pending ? { pending } : {}),
    partial: failed > 0 && failed < results.length,
    ...(hints.size ? { hints: [...hints] } : {}),
    ...(failed > 0 ? { next: 'Fix each failed item as its error says, then send only the failed items in a new remember call with a new request_id; the saved items are already stored.' }
      : pending > 0 ? { next: 'Pending items are accepted and still publishing: poll get_write_request with each pending item\'s request_id; do not send them again.' } : {}),
  };
}