create-walle 0.9.25 → 0.9.26

package/template/wall-e/coding/action-memory-store.js

@@ -0,0 +1,814 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const Database = requireBetterSqlite3();
+const { enforceSqliteStoragePolicy } = require('../shared/sqlite-storage-policy');
+const { installSqliteWriteLock } = require('../shared/sqlite-write-lock');
+
+const SCHEMA_VERSION = 1;
+const DEFAULT_LIMIT = 50;
+const DEFAULT_PREVIEW_BYTES = 4096;
+const POSITIVE_OUTCOMES = new Set(['unknown', 'succeeded', 'applied', 'verified_passed']);
+
+class ActionMemoryStore {
+  constructor({
+    dbPath = defaultActionMemoryDbPath(),
+    artifactsDir = defaultActionMemoryArtifactsDir(),
+    env = process.env,
+    now = () => new Date().toISOString(),
+    logger = console,
+    db = null,
+    previewBytes = DEFAULT_PREVIEW_BYTES,
+  } = {}) {
+    this.dbPath = dbPath;
+    this.artifactsDir = artifactsDir;
+    this.env = env;
+    this.now = now;
+    this.logger = logger;
+    this.db = db;
+    this.ownsDb = !db;
+    this.previewBytes = previewBytes;
+    this.initialized = false;
+  }
+
+  init() {
+    if (this.initialized) return this;
+    fs.mkdirSync(path.dirname(this.dbPath), { recursive: true });
+    fs.mkdirSync(this.artifactsDir, { recursive: true });
+    enforceSqliteStoragePolicy(this.dbPath, {
+      env: this.env,
+      prefix: 'WALL_E_ACTION_MEMORY',
+      label: 'Wall-E action-memory SQLite database',
+      logger: this.logger,
+    });
+
+    if (!this.db) this.db = new Database(this.dbPath, { timeout: sqliteTimeoutMs(this.env) });
+    installSqliteWriteLock(this.db, this.dbPath, {
+      label: 'wall-e-action-memory',
+      timeoutMs: sqliteWriteLockTimeoutMs(this.env),
+      staleMs: Number(this.env.WALL_E_ACTION_MEMORY_SQLITE_WRITE_LOCK_STALE_MS || 10 * 60 * 1000),
+    });
+    this.db.pragma('journal_mode = WAL');
+    this.db.pragma(`busy_timeout = ${sqliteTimeoutMs(this.env)}`);
+    this.db.pragma('foreign_keys = ON');
+    this.createTables();
+    this.initialized = true;
+    return this;
+  }
+
+  close() {
+    if (this.db && this.ownsDb) this.db.close();
+    this.db = null;
+    this.initialized = false;
+  }
+
+  createTables() {
+    const db = this.requireDb();
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS action_memory_entries (
+        id TEXT PRIMARY KEY,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        source_kind TEXT NOT NULL,
+        source_session_id TEXT,
+        source_tool_call_id TEXT,
+        source_row_id TEXT,
+        source_ts TEXT,
+        provider TEXT,
+        model_id TEXT,
+        tool_format TEXT,
+        tool_catalog_id TEXT,
+        workflow_family_id TEXT,
+        repo_key TEXT,
+        cwd_hash TEXT,
+        intent TEXT,
+        task_fingerprint TEXT,
+        task_preview TEXT,
+        state_signature_hash TEXT,
+        state_sequence TEXT,
+        last_tool TEXT,
+        tool_name TEXT NOT NULL,
+        target_kind TEXT,
+        target_hint TEXT,
+        target_path_suffix TEXT,
+        command_hash TEXT,
+        payload_sha256 TEXT NOT NULL,
+        payload_artifact_path TEXT NOT NULL,
+        payload_bytes INTEGER NOT NULL,
+        payload_preview TEXT,
+        outcome_status TEXT NOT NULL DEFAULT 'unknown',
+        confidence REAL DEFAULT 0.5,
+        redaction_version INTEGER DEFAULT 1,
+        schema_version INTEGER DEFAULT ${SCHEMA_VERSION},
+        disabled_at TEXT,
+        metadata_json TEXT
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_action_memory_tool
+        ON action_memory_entries(tool_name, disabled_at, outcome_status);
+      CREATE INDEX IF NOT EXISTS idx_action_memory_context
+        ON action_memory_entries(workflow_family_id, repo_key, intent, state_sequence);
+      CREATE INDEX IF NOT EXISTS idx_action_memory_target
+        ON action_memory_entries(tool_name, target_path_suffix, command_hash);
+      CREATE INDEX IF NOT EXISTS idx_action_memory_source
+        ON action_memory_entries(source_kind, source_session_id, source_tool_call_id);
+
+      CREATE TABLE IF NOT EXISTS action_memory_selection_log (
+        id TEXT PRIMARY KEY,
+        created_at TEXT NOT NULL,
+        mode TEXT NOT NULL,
+        provider TEXT,
+        model_id TEXT,
+        session_id TEXT,
+        tool_name TEXT,
+        candidate_count INTEGER DEFAULT 0,
+        selected_entry_id TEXT,
+        selected_score REAL,
+        accepted INTEGER DEFAULT 0,
+        reason TEXT,
+        prompt_hash TEXT,
+        prediction_json TEXT,
+        context_json TEXT,
+        outcome_json TEXT,
+        FOREIGN KEY(selected_entry_id) REFERENCES action_memory_entries(id)
+      );
+
+      PRAGMA user_version = ${SCHEMA_VERSION};
+    `);
+  }
+
+  recordActionMemoryEntry({ context = {}, action = {}, outcome = {}, source = {}, model = {}, metadata = {} } = {}) {
+    this.init();
+    const normalizedAction = normalizeAction(action);
+    if (!normalizedAction.toolName) throw new Error('recordActionMemoryEntry requires action.toolName/name/tool');
+    const normalizedContext = normalizeActionContext(context, normalizedAction);
+    const normalizedOutcome = normalizeOutcome(outcome);
+    const normalizedSource = normalizeSource(source);
+    const normalizedModel = normalizeModel(model);
+    const payload = {
+      schema_version: SCHEMA_VERSION,
+      tool: normalizedAction.toolName,
+      input: normalizedAction.input,
+      context: normalizedContext.publicContext,
+      outcome: normalizedOutcome,
+      source: normalizedSource,
+      model: normalizedModel,
+      metadata: safeJsonValue(metadata),
+    };
+    const artifact = this.storePayload(payload, {
+      sessionId: normalizedSource.sessionId,
+      toolCallId: normalizedSource.toolCallId,
+      toolName: normalizedAction.toolName,
+    });
+    const now = this.now();
+    const id = source.id || `am_${sha256([
+      normalizedSource.kind,
+      normalizedSource.sessionId,
+      normalizedSource.toolCallId,
+      normalizedSource.rowId,
+      normalizedAction.toolName,
+      artifact.sha256,
+    ].join('\0')).slice(0, 24)}`;
+
+    const row = {
+      id,
+      created_at: now,
+      updated_at: now,
+      source_kind: normalizedSource.kind,
+      source_session_id: normalizedSource.sessionId,
+      source_tool_call_id: normalizedSource.toolCallId,
+      source_row_id: normalizedSource.rowId,
+      source_ts: normalizedSource.timestamp,
+      provider: normalizedModel.provider,
+      model_id: normalizedModel.modelId,
+      tool_format: normalizedModel.toolFormat,
+      tool_catalog_id: normalizedContext.toolCatalogId,
+      workflow_family_id: normalizedContext.familyId,
+      repo_key: normalizedContext.repoKey,
+      cwd_hash: normalizedContext.cwdHash,
+      intent: normalizedContext.intent,
+      task_fingerprint: normalizedContext.taskFingerprint,
+      task_preview: normalizedContext.taskPreview,
+      state_signature_hash: normalizedContext.stateSignatureHash,
+      state_sequence: normalizedContext.sequence,
+      last_tool: normalizedContext.lastTool,
+      tool_name: normalizedAction.toolName,
+      target_kind: normalizedAction.targetKind,
+      target_hint: normalizedAction.targetHint,
+      target_path_suffix: normalizedAction.targetPathSuffix,
+      command_hash: normalizedAction.commandHash,
+      payload_sha256: artifact.sha256,
+      payload_artifact_path: artifact.path,
+      payload_bytes: artifact.bytes,
+      payload_preview: artifact.preview,
+      outcome_status: normalizedOutcome.status,
+      confidence: normalizedOutcome.confidence,
+      redaction_version: 1,
+      schema_version: SCHEMA_VERSION,
+      disabled_at: null,
+      metadata_json: stringifyJson({
+        ...safeJsonObject(metadata),
+        source: normalizedSource.metadata,
+        context: normalizedContext.metadata,
+        model: normalizedModel.metadata,
+      }),
+    };
+
+    this.requireDb().prepare(`
+      INSERT INTO action_memory_entries (
+        id, created_at, updated_at, source_kind, source_session_id, source_tool_call_id,
+        source_row_id, source_ts, provider, model_id, tool_format, tool_catalog_id,
+        workflow_family_id, repo_key, cwd_hash, intent, task_fingerprint, task_preview,
+        state_signature_hash, state_sequence, last_tool, tool_name, target_kind,
+        target_hint, target_path_suffix, command_hash, payload_sha256, payload_artifact_path,
+        payload_bytes, payload_preview, outcome_status, confidence, redaction_version,
+        schema_version, disabled_at, metadata_json
+      ) VALUES (
+        @id, @created_at, @updated_at, @source_kind, @source_session_id, @source_tool_call_id,
+        @source_row_id, @source_ts, @provider, @model_id, @tool_format, @tool_catalog_id,
+        @workflow_family_id, @repo_key, @cwd_hash, @intent, @task_fingerprint, @task_preview,
+        @state_signature_hash, @state_sequence, @last_tool, @tool_name, @target_kind,
+        @target_hint, @target_path_suffix, @command_hash, @payload_sha256, @payload_artifact_path,
+        @payload_bytes, @payload_preview, @outcome_status, @confidence, @redaction_version,
+        @schema_version, @disabled_at, @metadata_json
+      )
+      ON CONFLICT(id) DO UPDATE SET
+        updated_at = excluded.updated_at,
+        outcome_status = excluded.outcome_status,
+        confidence = excluded.confidence,
+        payload_preview = excluded.payload_preview,
+        metadata_json = excluded.metadata_json,
+        disabled_at = NULL
+    `).run(row);
+
+    return this.getEntry(id);
+  }
+
+  getEntry(id) {
+    this.init();
+    const row = this.requireDb().prepare('SELECT * FROM action_memory_entries WHERE id = ?').get(String(id || ''));
+    return row ? this.rowToEntry(row) : null;
+  }
+
+  searchActionMemoryCandidates({
+    context = {},
+    prediction = null,
+    toolName = '',
+    limit = DEFAULT_LIMIT,
+    includeDisabled = false,
+    positiveOnly = true,
+  } = {}) {
+    this.init();
+    const action = normalizeAction(prediction || { toolName, input: {} });
+    const normalizedTool = String(toolName || action.toolName || '').trim();
+    const normalizedContext = normalizeActionContext(context, action);
+    const where = [];
+    const params = {};
+    if (normalizedTool) {
+      where.push('tool_name = @toolName');
+      params.toolName = normalizedTool;
+    }
+    if (!includeDisabled) where.push('disabled_at IS NULL');
+    if (positiveOnly) where.push(`outcome_status IN (${Array.from(POSITIVE_OUTCOMES).map((_, idx) => `@outcome${idx}`).join(', ')})`);
+    if (positiveOnly) Array.from(POSITIVE_OUTCOMES).forEach((value, idx) => { params[`outcome${idx}`] = value; });
+    params.limit = Math.max(1, Math.min(500, Number(limit) || DEFAULT_LIMIT));
+
+    const db = this.requireDb();
+    const rows = [];
+    const seen = new Set();
+    const addRows = (extraWhere = [], extraParams = {}, orderBy = 'created_at DESC') => {
+      const sql = `
+        SELECT *
+        FROM action_memory_entries
+        ${where.length || extraWhere.length ? `WHERE ${[...where, ...extraWhere].join(' AND ')}` : ''}
+        ORDER BY ${orderBy}
+        LIMIT @limit
+      `;
+      for (const row of db.prepare(sql).all({ ...params, ...extraParams })) {
+        if (seen.has(row.id)) continue;
+        seen.add(row.id);
+        rows.push(row);
+      }
+    };
+
+    const contextual = [];
+    const contextualParams = {};
+    if (normalizedContext.familyId) {
+      contextual.push('workflow_family_id = @ctxFamilyId');
+      contextualParams.ctxFamilyId = normalizedContext.familyId;
+    }
+    if (normalizedContext.repoKey && normalizedContext.intent) {
+      contextual.push('(repo_key = @ctxRepoKey AND intent = @ctxIntent)');
+      contextualParams.ctxRepoKey = normalizedContext.repoKey;
+      contextualParams.ctxIntent = normalizedContext.intent;
+    } else if (normalizedContext.repoKey) {
+      contextual.push('repo_key = @ctxRepoKey');
+      contextualParams.ctxRepoKey = normalizedContext.repoKey;
+    }
+    if (normalizedContext.sequence) {
+      contextual.push('state_sequence = @ctxSequence');
+      contextualParams.ctxSequence = normalizedContext.sequence;
+    }
+    if (normalizedContext.taskFingerprint) {
+      contextual.push('task_fingerprint = @ctxTaskFingerprint');
+      contextualParams.ctxTaskFingerprint = normalizedContext.taskFingerprint;
+    }
+    if (contextual.length) {
+      addRows([`(${contextual.join(' OR ')})`], contextualParams, 'updated_at DESC');
+    }
+    addRows([], {}, 'created_at DESC');
+
+    return rows
+      .map((row) => this.rowToCandidate(row, normalizedContext))
+      .filter(Boolean)
+      .sort((left, right) => {
+        const leftScore = scoreActionMemoryCandidate(left, normalizedContext, action.input || {}).score;
+        const rightScore = scoreActionMemoryCandidate(right, normalizedContext, action.input || {}).score;
+        if (rightScore !== leftScore) return rightScore - leftScore;
+        return String(left.id).localeCompare(String(right.id));
+      })
+      .slice(0, params.limit);
+  }
+
+  selectActionMemoryCandidate({
+    context = {},
+    prediction = null,
+    toolName = '',
+    minScore = 100,
+    minMargin = 0,
+    limit = DEFAULT_LIMIT,
+  } = {}) {
+    const action = normalizeAction(prediction || { toolName, input: {} });
+    const normalizedContext = normalizeActionContext(context, action);
+    const candidates = this.searchActionMemoryCandidates({
+      context: normalizedContext.publicContext,
+      prediction: action,
+      toolName: toolName || action.toolName,
+      limit,
+    }).map((candidate) => {
+      const scored = scoreActionMemoryCandidate(candidate, normalizedContext, action.input || {});
+      return { ...candidate, score: scored.score, reasons: scored.reasons };
+    });
+    const top = candidates[0] || null;
+    if (!top) return { selection: null, candidates };
+    const second = candidates[1] || null;
+    const margin = second ? top.score - second.score : top.score;
+    const accepted = top.score >= minScore && margin >= minMargin;
+    return {
+      selection: {
+        id: top.id,
+        tool: top.tool,
+        input: accepted ? top.input : undefined,
+        score: top.score,
+        reasons: top.reasons,
+        accepted,
+        sourceKind: top.sourceKind,
+        sourceRowId: top.sourceRowId,
+        sourceSessionId: top.sourceSessionId,
+        sourceToolCallId: top.sourceToolCallId,
+        targetHint: top.targetHint,
+      },
+      candidates,
+    };
+  }
+
+  recordSelectionAudit({
+    mode = 'audit',
+    context = {},
+    prediction = null,
+    selected = null,
+    candidates = [],
+    outcome = {},
+    reason = '',
+    model = {},
+    sessionId = '',
+    prompt = '',
+  } = {}) {
+    this.init();
+    const normalizedModel = normalizeModel(model);
+    const normalizedPrediction = normalizeAction(prediction || {});
+    const normalizedContext = normalizeActionContext(context, normalizedPrediction);
+    const row = {
+      id: `ams_${sha256([
+        this.now(),
+        mode,
+        sessionId,
+        selected?.id || '',
+        candidates.length,
+        crypto.randomBytes(8).toString('hex'),
+      ].join('\0')).slice(0, 24)}`,
+      created_at: this.now(),
+      mode: String(mode || 'audit'),
+      provider: normalizedModel.provider,
+      model_id: normalizedModel.modelId,
+      session_id: String(sessionId || normalizedContext.sessionId || ''),
+      tool_name: normalizedPrediction.toolName || selected?.tool || '',
+      candidate_count: Number(candidates.length || 0),
+      selected_entry_id: selected?.id || null,
+      selected_score: Number.isFinite(Number(selected?.score)) ? Number(selected.score) : null,
+      accepted: selected?.accepted ? 1 : 0,
+      reason: String(reason || selected?.reason || ''),
+      prompt_hash: prompt ? sha256(String(prompt)) : '',
+      prediction_json: stringifyJson(prediction || null),
+      context_json: stringifyJson(normalizedContext.publicContext),
+      outcome_json: stringifyJson(outcome || null),
+    };
+    this.requireDb().prepare(`
+      INSERT INTO action_memory_selection_log (
+        id, created_at, mode, provider, model_id, session_id, tool_name,
+        candidate_count, selected_entry_id, selected_score, accepted, reason,
+        prompt_hash, prediction_json, context_json, outcome_json
+      ) VALUES (
+        @id, @created_at, @mode, @provider, @model_id, @session_id, @tool_name,
+        @candidate_count, @selected_entry_id, @selected_score, @accepted, @reason,
+        @prompt_hash, @prediction_json, @context_json, @outcome_json
+      )
+    `).run(row);
+    return row;
+  }
+
+  disableEntry(id, { reason = '' } = {}) {
+    this.init();
+    const metadata = { disabled_reason: String(reason || '') };
+    return this.requireDb().prepare(`
+      UPDATE action_memory_entries
+      SET disabled_at = @disabledAt,
+          updated_at = @updatedAt,
+          metadata_json = json_patch(COALESCE(metadata_json, '{}'), @metadata)
+      WHERE id = @id
+    `).run({
+      id: String(id || ''),
+      disabledAt: this.now(),
+      updatedAt: this.now(),
+      metadata: stringifyJson(metadata),
+    });
+  }
+
+  storePayload(payload, { sessionId = '', toolCallId = '', toolName = '' } = {}) {
+    const text = stringifyJson(payload, 2);
+    const bytes = Buffer.byteLength(text, 'utf8');
+    const hash = sha256(text);
+    const dir = path.join(this.artifactsDir, hash.slice(0, 2), hash.slice(2, 4));
+    fs.mkdirSync(dir, { recursive: true });
+    const name = `${safeName(toolName || 'action')}-${safeName(sessionId || 'session')}-${safeName(toolCallId || hash.slice(0, 12))}-${hash.slice(0, 12)}.json`;
+    const filePath = path.join(dir, name);
+    if (!fs.existsSync(filePath)) fs.writeFileSync(filePath, text, { encoding: 'utf8', mode: 0o600 });
+    return {
+      path: filePath,
+      sha256: hash,
+      bytes,
+      preview: truncateUtf8(text, this.previewBytes),
+    };
+  }
+
+  readPayload(rowOrEntry = {}) {
+    const filePath = rowOrEntry.payload_artifact_path || rowOrEntry.payloadArtifactPath || '';
+    if (!filePath) return null;
+    try {
+      return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    } catch {
+      return null;
+    }
+  }
+
+  rowToEntry(row) {
+    const payload = this.readPayload(row);
+    return {
+      id: row.id,
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+      sourceKind: row.source_kind,
+      sourceSessionId: row.source_session_id,
+      sourceToolCallId: row.source_tool_call_id,
+      sourceRowId: row.source_row_id,
+      provider: row.provider,
+      modelId: row.model_id,
+      toolFormat: row.tool_format,
+      tool: row.tool_name,
+      input: payload?.input || {},
+      familyId: row.workflow_family_id,
+      repo: row.repo_key,
+      intent: row.intent,
+      taskFingerprint: row.task_fingerprint,
+      taskPreview: row.task_preview,
+      sequence: row.state_sequence,
+      lastTool: row.last_tool,
+      targetHint: row.target_hint,
+      targetPathSuffix: row.target_path_suffix,
+      commandHash: row.command_hash,
+      payloadSha256: row.payload_sha256,
+      payloadArtifactPath: row.payload_artifact_path,
+      payloadBytes: row.payload_bytes,
+      payloadPreview: row.payload_preview,
+      outcomeStatus: row.outcome_status,
+      confidence: row.confidence,
+      disabledAt: row.disabled_at,
+      metadata: parseJson(row.metadata_json, {}),
+    };
+  }
+
+  rowToCandidate(row, context = {}) {
+    const entry = this.rowToEntry(row);
+    if (!entry.tool) return null;
+    const scored = scoreActionMemoryCandidate(entry, context, {});
+    return {
+      id: entry.id,
+      tool: entry.tool,
+      input: entry.input || {},
+      familyId: entry.familyId || null,
+      repo: entry.repo || null,
+      intent: entry.intent || null,
+      sequence: entry.sequence || null,
+      lastTool: entry.lastTool || null,
+      taskFingerprint: entry.taskFingerprint || null,
+      targetHint: entry.targetHint || null,
+      commandHash: entry.commandHash || null,
+      sourceKind: entry.sourceKind || null,
+      sourceSessionId: entry.sourceSessionId || null,
+      sourceToolCallId: entry.sourceToolCallId || null,
+      sourceRowId: entry.sourceRowId || null,
+      provider: entry.provider || null,
+      modelId: entry.modelId || null,
+      toolFormat: entry.toolFormat || null,
+      outcomeStatus: entry.outcomeStatus || null,
+      confidence: entry.confidence,
+      payloadSha256: entry.payloadSha256,
+      payloadArtifactPath: entry.payloadArtifactPath,
+      score: scored.score,
+      reasons: scored.reasons,
+    };
+  }
+
+  requireDb() {
+    if (!this.db) throw new Error('ActionMemoryStore is not initialized');
+    return this.db;
+  }
+}
+
+function defaultActionMemoryDir(env = process.env) {
+  const dataDir = env.WALL_E_DATA_DIR || env.WALLE_DATA_DIR || path.join(os.homedir(), '.walle', 'data');
+  return path.join(dataDir, 'action-memory');
+}
+
+function defaultActionMemoryDbPath(env = process.env) {
+  return path.join(defaultActionMemoryDir(env), 'action-memory.db');
+}
+
+function defaultActionMemoryArtifactsDir(env = process.env) {
+  return path.join(defaultActionMemoryDir(env), 'artifacts');
+}
+
+function normalizeAction(action = {}) {
+  const toolName = String(action.toolName || action.name || action.tool || '').trim();
+  const input = safeJsonObject(action.input || action.args || action.arguments || {});
+  const targetHint = targetHintForAction(toolName, input);
+  const command = toolName === 'run_shell' ? String(input.command || input.cmd || '').trim() : '';
+  return {
+    toolName,
+    input,
+    targetKind: command ? 'command' : (targetHint ? 'path' : ''),
+    targetHint,
+    targetPathSuffix: targetHint ? pathSuffix(targetHint) : '',
+    commandHash: command ? sha256(normalizeCommand(command)) : '',
+  };
+}
+
+function normalizeActionContext(context = {}, action = {}) {
+  const taskText = String(context.taskText || context.task || context.userTask || context.taskPreview || '').trim();
+  const sequence = String(context.sequence || context.stateSequence || context.toolSequence || '').trim();
+  const cwd = String(context.cwd || context.projectRoot || '').trim();
+  const publicContext = {
+    familyId: emptyToNull(context.familyId || context.workflowFamilyId || context.workflow_family_id),
+    repoKey: emptyToNull(context.repoKey || context.repo || context.workflowRepo || context.workflow_repo),
+    intent: emptyToNull(context.intent || context.workflowIntent || context.workflow_intent),
+    intendedTool: emptyToNull(context.intendedTool || context.toolName || context.tool_name || action.toolName),
+    taskFingerprint: emptyToNull(context.taskFingerprint || (taskText ? shortHash(taskText) : '')),
+    taskPreview: taskText ? truncateChars(taskText.replace(/\s+/g, ' '), 500) : '',
+    stateSignatureHash: emptyToNull(context.stateSignatureHash || context.stateHash || (sequence ? shortHash(sequence) : '')),
+    sequence: emptyToNull(sequence),
+    lastTool: emptyToNull(context.lastTool || context.last_tool),
+    toolCatalogId: emptyToNull(context.toolCatalogId || context.tool_catalog),
+    cwdHash: cwd ? sha256(cwd) : '',
+    targetHint: action.targetHint || emptyToNull(context.targetHint || context.target_path || context.targetPath),
+    sessionId: emptyToNull(context.sessionId || context.sourceSessionId),
+  };
+  return {
+    ...publicContext,
+    publicContext,
+    metadata: safeJsonObject(context.metadata || {}),
+  };
+}
+
+function normalizeOutcome(outcome = {}) {
+  const status = String(outcome.status || outcome.outcomeStatus || (outcome.verified ? 'verified_passed' : 'unknown')).trim() || 'unknown';
+  const confidence = Number(outcome.confidence);
+  return {
+    status,
+    confidence: Number.isFinite(confidence) ? Math.max(0, Math.min(1, confidence)) : 0.5,
+    verified: Boolean(outcome.verified || status === 'verified_passed'),
+    metadata: safeJsonObject(outcome.metadata || {}),
+  };
+}
+
+function normalizeSource(source = {}) {
+  return {
+    kind: String(source.kind || source.sourceKind || 'manual').trim() || 'manual',
+    sessionId: String(source.sessionId || source.sourceSessionId || '').trim(),
+    toolCallId: String(source.toolCallId || source.sourceToolCallId || '').trim(),
+    rowId: String(source.rowId || source.sourceRowId || source.id || '').trim(),
+    timestamp: String(source.timestamp || source.sourceTs || '').trim(),
+    metadata: safeJsonObject(source.metadata || {}),
+  };
+}
+
+function normalizeModel(model = {}) {
+  return {
+    provider: String(model.provider || model.providerId || '').trim(),
+    modelId: String(model.modelId || model.model || model.name || '').trim(),
+    toolFormat: String(model.toolFormat || model.tool_format || model.chatTemplate || '').trim(),
+    metadata: safeJsonObject(model.metadata || {}),
+  };
+}
+
+function scoreActionMemoryCandidate(candidate = {}, context = {}, predictedInput = {}) {
+  let score = 0;
+  const reasons = [];
+  if (candidate.familyId && candidate.familyId === context.familyId) {
+    score += 70;
+    reasons.push('same_family');
+  }
+  if (candidate.tool && context.intendedTool && candidate.tool === context.intendedTool) {
+    score += 20;
+    reasons.push('same_tool');
+  }
+  if (candidate.sequence && candidate.sequence === context.sequence) {
+    score += 35;
+    reasons.push('same_state_sequence');
+  }
+  if (candidate.lastTool && candidate.lastTool === context.lastTool) {
+    score += 10;
+    reasons.push('same_last_tool');
+  }
+  if (candidate.repo && candidate.repo === context.repoKey) {
+    score += 8;
+    reasons.push('same_repo');
+  }
+  if (candidate.intent && candidate.intent === context.intent) {
+    score += 8;
+    reasons.push('same_intent');
+  }
+  if (candidate.taskFingerprint && candidate.taskFingerprint === context.taskFingerprint) {
+    score += 14;
+    reasons.push('same_task_fingerprint');
+  }
+  const predictedTarget = targetHintForAction(candidate.tool, predictedInput || {});
+  if (predictedTarget && candidate.targetHint && samePathish(candidate.targetHint, predictedTarget)) {
+    score += 12;
+    reasons.push('same_predicted_target');
+  }
+  if (candidate.commandHash && predictedInput?.command && candidate.commandHash === sha256(normalizeCommand(predictedInput.command))) {
+    score += 25;
+    reasons.push('same_predicted_command');
+  }
+  if (candidate.outcomeStatus === 'verified_passed') {
+    score += 5;
+    reasons.push('verified_passed');
+  }
+  const confidence = Number(candidate.confidence);
+  if (Number.isFinite(confidence) && confidence >= 0.75) {
+    score += 3;
+    reasons.push('high_confidence');
+  }
+  return { score, reasons };
+}
+
+function targetHintForAction(toolName, input = {}) {
+  if (toolName === 'apply_patch') return firstPatchFile(input.patch_text || input.patch || '');
+  return input.file_path || input.path || input.target_file || input.targetFile || null;
+}
+
+function firstPatchFile(patchText = '') {
+  const match = String(patchText || '').match(/^\*\*\* (?:Update|Add|Delete) File:\s*(.+)$/m);
+  return match ? match[1].trim() : null;
+}
+
+function pathSuffix(value = '') {
+  const normalized = normalizePathish(value);
+  if (!normalized) return '';
+  const parts = normalized.split('/').filter(Boolean);
+  return parts.slice(-3).join('/');
+}
+
+function samePathish(a, b) {
+  const left = normalizePathish(a);
+  const right = normalizePathish(b);
+  return Boolean(left && right && (left === right || left.endsWith(`/${right}`) || right.endsWith(`/${left}`)));
+}
+
+function normalizePathish(value) {
+  return String(value || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '') || '';
+}
+
+function normalizeCommand(command = '') {
+  return String(command || '').replace(/\r\n/g, '\n').replace(/[ \t]+/g, ' ').trim();
+}
+
+function sha256(value = '') {
+  return crypto.createHash('sha256').update(String(value)).digest('hex');
+}
+
+function shortHash(value = '') {
+  return sha256(String(value)).slice(0, 16);
+}
+
+function stringifyJson(value, space = 0) {
+  return JSON.stringify(safeJsonValue(value), null, space);
+}
+
+function parseJson(value, fallback) {
+  try {
+    return JSON.parse(String(value || ''));
+  } catch {
+    return fallback;
+  }
+}
+
+function safeJsonObject(value) {
+  const safe = safeJsonValue(value);
+  return safe && typeof safe === 'object' && !Array.isArray(safe) ? safe : {};
+}
+
+function safeJsonValue(value) {
+  try {
+    return JSON.parse(JSON.stringify(value ?? null));
+  } catch {
+    return String(value ?? '');
+  }
+}
+
+function safeName(value) {
+  return String(value || 'value')
+    .replace(/[^A-Za-z0-9_.:-]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .slice(0, 80) || 'value';
+}
+
+function truncateUtf8(text, maxBytes) {
+  const value = String(text || '');
+  if (Buffer.byteLength(value, 'utf8') <= maxBytes) return value;
+  let bytes = 0;
+  let out = '';
+  for (const char of value) {
+    const next = Buffer.byteLength(char, 'utf8');
+    if (bytes + next > maxBytes) break;
+    out += char;
+    bytes += next;
+  }
+  return `${out}\n[action memory payload truncated; full content stored as side artifact]`;
+}
+
+function truncateChars(text, maxChars) {
+  const value = String(text || '');
+  return value.length <= maxChars ? value : value.slice(0, maxChars);
+}
+
+function emptyToNull(value) {
+  const text = String(value || '').trim();
+  return text || null;
+}
+
+function sqliteTimeoutMs(env = process.env) {
+  const value = Number(env.WALL_E_ACTION_MEMORY_SQLITE_BUSY_TIMEOUT_MS || env.WALL_E_SQLITE_BUSY_TIMEOUT_MS || 1000);
+  return Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 1000;
+}
+
+function sqliteWriteLockTimeoutMs(env = process.env) {
+  const value = Number(env.WALL_E_ACTION_MEMORY_SQLITE_WRITE_LOCK_TIMEOUT_MS || env.WALL_E_SQLITE_WRITE_LOCK_TIMEOUT_MS || 0);
+  return Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 0;
+}
+
+function requireBetterSqlite3() {
+  try {
+    return require('better-sqlite3');
+  } catch (err) {
+    if (err?.code !== 'MODULE_NOT_FOUND' || !String(err.message || '').includes('better-sqlite3')) throw err;
+    return require(path.join(__dirname, '..', 'node_modules', 'better-sqlite3'));
+  }
+}
+
+module.exports = {
+  ActionMemoryStore,
+  DEFAULT_PREVIEW_BYTES,
+  POSITIVE_OUTCOMES,
+  SCHEMA_VERSION,
+  defaultActionMemoryArtifactsDir,
+  defaultActionMemoryDbPath,
+  defaultActionMemoryDir,
+  normalizeAction,
+  normalizeActionContext,
+  scoreActionMemoryCandidate,
+};