@aion0/forge 0.9.18 → 0.10.2

package/lib/settings.ts

@@ -7,29 +7,62 @@ import { getDataDir } from './dirs';
 const DATA_DIR = getDataDir();
 const SETTINGS_FILE = join(DATA_DIR, 'settings.yaml');
 
+/**
+ * AgentEntry — a CLI agent configuration (one CLI binary + its env / model).
+ *
+ * As of v0.9.20 the agents dict is CLI-only; API endpoints live in the
+ * sibling `apiProfiles` dict. The `tool` field is the discriminator
+ * (which CLI binary to invoke). Multiple entries with the same `tool`
+ * are allowed (used to be "CLI profiles" — now just additional named
+ * agents with their own env).
+ *
+ * Deprecated fields (`base` / `cliType` / `type` / `provider` / `apiKey`
+ * / `baseUrl`) are migrated away by migrateAgentsFlatten on first load
+ * and removed from the schema in a later release.
+ */
 export interface AgentEntry {
-  // Base agent fields (for detected agents like claude, codex, aider)
+  tool?: 'claude' | 'codex' | 'aider' | 'opencode';   // which CLI binary
   path?: string; name?: string; enabled?: boolean;
   flags?: string[]; taskFlags?: string; interactiveCmd?: string; resumeFlag?: string; outputFormat?: string;
   models?: { terminal?: string; task?: string; telegram?: string; help?: string; mobile?: string };
   skipPermissionsFlag?: string;
   requiresTTY?: boolean;
-  // Profile fields (for profiles that extend a base agent)
-  base?: string;                 // base agent ID (e.g., 'claude') — makes this a profile
-  // API profile fields
-  type?: 'cli' | 'api';         // 'api' = API mode, default = 'cli'
-  provider?: string;             // API provider label (e.g., 'anthropic', 'openai', 'litellm', 'grok', 'google')
-  model?: string;                // model override (for both CLI and API profiles)
-  apiKey?: string;               // per-profile API key (encrypted)
-  /**
-   * Base URL override for API profiles. Use this for LiteLLM / Azure /
-   * self-hosted proxies. Empty = default for the provider's protocol.
-   * For CLI profiles, set base URL via `env` (ANTHROPIC_BASE_URL etc.).
-   */
-  baseUrl?: string;
+  model?: string;                // flat model override
   env?: Record<string, string>;  // environment variables injected when spawning CLI
-  cliType?: 'claude-code' | 'codex' | 'aider' | 'generic'; // CLI tool type — determines session support, resume flags, etc.
-  profile?: string;              // linked profile ID — overrides model, env, etc. when launching
+
+  // === Deprecated (kept for migration compat; removed in a later release) ===
+  /** @deprecated migrated to `tool` */
+  base?: string;
+  /** @deprecated migrated to `tool` */
+  cliType?: 'claude-code' | 'codex' | 'aider' | 'generic';
+  /** @deprecated 'api' entries migrated to apiProfiles dict */
+  type?: 'cli' | 'api';
+  /** @deprecated moved to apiProfiles entry */
+  provider?: string;
+  /** @deprecated moved to apiProfiles entry */
+  apiKey?: string;
+  /** @deprecated moved to apiProfiles entry */
+  baseUrl?: string;
+  /** @deprecated unused */
+  profile?: string;
+}
+
+/**
+ * ApiProfile — a direct HTTP LLM endpoint (anthropic / openai-compat).
+ *
+ * Used by chat / summarizer / telegram chat surface — anything that
+ * needs a single-shot or streaming LLM call without a subprocess.
+ * Stored in `settings.apiProfiles`, not `settings.agents`. The two
+ * dicts never cross: tasks/pipelines/terminal pick from agents,
+ * chat/summarizer pick from apiProfiles. UI enforces the boundary.
+ */
+export interface ApiProfile {
+  name?: string;
+  enabled?: boolean;
+  provider: 'anthropic' | 'openai-compatible';
+  model: string;
+  apiKey: string;
+  baseUrl?: string;
 }
 
 /**
@@ -108,6 +141,9 @@ export interface Settings {
    */
   memoryBackend: 'auto' | 'local' | 'temper';
   agents: Record<string, AgentEntry>;
+  /** API endpoint profiles — chat / summarizer / telegram-chat target.
+   *  Separate from `agents` (CLI subprocess) so type guard is structural. */
+  apiProfiles: Record<string, ApiProfile>;
   /** Extra MCP servers merged into each project's .mcp.json (chrome-devtools-mcp etc.) */
   mcpServers: Record<string, McpServerConfig>;
   /**
@@ -177,6 +213,7 @@ const defaults: Settings = {
   temperNamespace: '',
   memoryBackend: 'auto',
   agents: {},
+  apiProfiles: {},
   mcpServers: {},
   timezone: '',
   smtpHost: '',
@@ -191,25 +228,35 @@ const defaults: Settings = {
   pipelineTmpGcIntervalHours: 6,
 };
 
-/** Decrypt nested apiKey fields in agent profiles */
+/** Decrypt nested apiKey fields in agents (legacy migration window) +
+ *  apiProfiles (current canonical location). */
 function decryptNestedSecrets(settings: Settings): void {
+  // Legacy: agent entries may still carry apiKey until migration runs
   if (settings.agents) {
     for (const [id, a] of Object.entries(settings.agents)) {
       if (a.apiKey && isEncrypted(a.apiKey)) {
         a.apiKey = decryptSecret(a.apiKey);
       }
-      // Defensive: a past bug let the masked placeholder get encrypted
-      // and written back. Clear it so callers see "no key" instead of
-      // trying to send '••••••••' as a Bearer header.
       if (a.apiKey && /^•+$/.test(a.apiKey)) {
         console.warn(`[settings] agent '${id}' has a placeholder apiKey — clearing. Re-enter it via Settings.`);
         a.apiKey = '';
       }
     }
   }
+  if (settings.apiProfiles) {
+    for (const [id, p] of Object.entries(settings.apiProfiles)) {
+      if (p.apiKey && isEncrypted(p.apiKey)) {
+        p.apiKey = decryptSecret(p.apiKey);
+      }
+      if (p.apiKey && /^•+$/.test(p.apiKey)) {
+        console.warn(`[settings] apiProfile '${id}' has a placeholder apiKey — clearing. Re-enter it via Settings.`);
+        p.apiKey = '';
+      }
+    }
+  }
 }
 
-/** Encrypt nested apiKey fields in agent profiles */
+/** Encrypt nested apiKey fields */
 function encryptNestedSecrets(settings: Settings): void {
   if (settings.agents) {
     for (const a of Object.values(settings.agents)) {
@@ -218,6 +265,13 @@ function encryptNestedSecrets(settings: Settings): void {
       }
     }
   }
+  if (settings.apiProfiles) {
+    for (const p of Object.values(settings.apiProfiles)) {
+      if (p.apiKey && !isEncrypted(p.apiKey)) {
+        p.apiKey = encryptSecret(p.apiKey);
+      }
+    }
+  }
 }
 
 /** Load settings with secrets decrypted (for internal use) */
@@ -248,7 +302,7 @@ export function loadSettingsMasked(): Settings & { _secretStatus: Record<string,
     status[field] = !!settings[field];
     settings[field] = settings[field] ? '••••••••' : '';
   }
-  // Mask nested apiKeys (agent profiles only)
+  // Mask nested apiKeys — agents (legacy) + apiProfiles (canonical)
   if (settings.agents) {
     for (const [name, a] of Object.entries(settings.agents)) {
       if (a.apiKey) {
@@ -257,6 +311,14 @@ export function loadSettingsMasked(): Settings & { _secretStatus: Record<string,
       }
     }
   }
+  if (settings.apiProfiles) {
+    for (const [name, p] of Object.entries(settings.apiProfiles)) {
+      if (p.apiKey) {
+        status[`apiProfiles.${name}.apiKey`] = true;
+        p.apiKey = '••••••••';
+      }
+    }
+  }
   return { ...settings, _secretStatus: status };
 }
 

package/lib/workspace/skill-installer.ts

@@ -177,6 +177,11 @@ const FORGE_HOOK_MARKER = '# forge-stop-hook';
  * When Claude Code finishes a turn, the hook notifies Forge via HTTP.
  * Preserves existing user hooks. Creates backup before modifying.
  */
+// Auto-prune leaves this many timestamped backups behind. `forge-backup-manual`
+// (or anything not matching the YYYYMMDD-HHMM suffix) is left alone.
+const FORGE_BACKUP_KEEP = 5;
+const FORGE_BACKUP_RE = /^settings\.json\.forge-backup-\d{8}-\d{4}$/;
+
 function installForgeStopHook(forgePort: number): void {
   const settingsFile = join(homedir(), '.claude', 'settings.json');
   const now = new Date();
@@ -191,11 +196,11 @@ function installForgeStopHook(forgePort: number): void {
 
   try {
     let settings: any = {};
+    let raw = '';
     if (existsSync(settingsFile)) {
-      const raw = readFileSync(settingsFile, 'utf-8');
+      raw = readFileSync(settingsFile, 'utf-8');
       settings = JSON.parse(raw);
 
-      // Check if hook already installed
       // Remove old forge hook if present (will re-add with latest version)
       if (settings.hooks?.Stop) {
         settings.hooks.Stop = settings.hooks.Stop.filter((h: any) => {
@@ -204,9 +209,6 @@ function installForgeStopHook(forgePort: number): void {
           return true;
         });
       }
-
-      // Backup before modifying
-      writeFileSync(backupFile, raw, 'utf-8');
     }
 
     if (!settings.hooks) settings.hooks = {};
@@ -222,14 +224,32 @@ function installForgeStopHook(forgePort: number): void {
       }],
     });
 
+    const next = JSON.stringify(settings, null, 2) + '\n';
+    if (next === raw) return;   // no-op — settings already had the current hook
+
     mkdirSync(join(homedir(), '.claude'), { recursive: true });
-    writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+    if (raw) writeFileSync(backupFile, raw, 'utf-8');
+    writeFileSync(settingsFile, next, 'utf-8');
+    pruneForgeBackups();
     console.log('[skills] Installed Forge Stop hook in ~/.claude/settings.json');
   } catch (err: any) {
     console.error('[skills] Failed to install Stop hook:', err.message);
   }
 }
 
+function pruneForgeBackups(): void {
+  try {
+    const dir = join(homedir(), '.claude');
+    const stamped = readdirSync(dir)
+      .filter(f => FORGE_BACKUP_RE.test(f))
+      .sort();   // lexicographic == chronological (YYYYMMDD-HHMM)
+    const stale = stamped.slice(0, -FORGE_BACKUP_KEEP);
+    for (const f of stale) {
+      try { unlinkSync(join(dir, f)); } catch {}
+    }
+  } catch {}
+}
+
 /**
  * Remove Forge Stop hook from user-level settings (cleanup).
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aion0/forge",
-  "version": "0.9.18",
+  "version": "0.10.2",
   "description": "Unified AI workflow platform — multi-model task orchestration, persistent sessions, web terminal, remote access",
   "type": "module",
   "scripts": {

package/scripts/test-agents-migrate.ts

@@ -0,0 +1,149 @@
+/**
+ * Migration smoke test — feed several known-shape settings through
+ * migrateAgentsFlatten and assert post-state. Runs offline, no real
+ * data needed.
+ *
+ *   npx tsx scripts/test-agents-migrate.ts
+ */
+
+import { migrateAgentsFlatten } from '../lib/agents/migrate';
+import type { Settings } from '../lib/settings';
+
+let failures = 0;
+const fail = (msg: string) => { console.log(`  ✗ ${msg}`); failures += 1; };
+const pass = (msg: string) => console.log(`  ✓ ${msg}`);
+
+function baseSettings(): Settings {
+  return {
+    projectRoots: [], docRoots: [], claudePath: '', claudeHome: '',
+    telegramBotToken: '', telegramChatId: '',
+    notifyOnComplete: true, notifyOnFailure: true,
+    tunnelAutoStart: false, telegramTunnelPassword: '',
+    taskModel: 'default', pipelineModel: 'default', telegramModel: 'sonnet',
+    skipPermissions: false, manageClaudeConfig: true,
+    notificationRetentionDays: 30,
+    skillsRepoUrl: '', connectorsRepoUrl: '', workflowRepoUrl: '',
+    maxConcurrentPipelines: 5,
+    displayName: '', displayEmail: '', favoriteProjects: [],
+    defaultAgent: 'claude', telegramAgent: '', docsAgent: '', chatAgent: '',
+    temperUrl: '', temperKey: '', temperNamespace: '', memoryBackend: 'auto',
+    agents: {}, apiProfiles: {}, mcpServers: {}, timezone: '',
+    smtpHost: '', smtpPort: 587, smtpSecure: false, smtpUser: '', smtpPassword: '', smtpFrom: '',
+    pipelineTmpCleanDoneImmediate: true,
+    pipelineTmpKeepFailedDays: 3, pipelineTmpKeepCancelledDays: 3,
+    pipelineTmpGcIntervalHours: 6,
+  } as Settings;
+}
+
+// ── Test 1: type='api' moves to apiProfiles ──────────────────────────
+{
+  console.log('Test 1 — API profile moves out of agents');
+  const s = baseSettings();
+  s.agents = {
+    claude: { enabled: true, path: '/usr/local/bin/claude' },
+    'forti-api': { type: 'api', provider: 'litellm', model: 'DeepSeek-V4-Pro', apiKey: 'sk-...', baseUrl: 'https://x' } as any,
+  };
+  s.chatAgent = 'forti-api';
+  const mutated = migrateAgentsFlatten(s);
+  if (!mutated) fail('expected mutated=true');
+  if (s.agents['forti-api']) fail('forti-api still in agents');
+  else pass('forti-api removed from agents');
+  const p = (s as any).apiProfiles?.['forti-api'];
+  if (!p) fail('forti-api not in apiProfiles');
+  else if (p.provider !== 'openai-compatible') fail(`provider mapped wrong: ${p.provider}`);
+  else if (p.model !== 'DeepSeek-V4-Pro') fail('model lost');
+  else pass(`forti-api in apiProfiles (provider=${p.provider}, model=${p.model})`);
+  if (s.chatAgent !== 'forti-api') fail(`chatAgent corrupted: ${s.chatAgent}`);
+  else pass('chatAgent unchanged');
+}
+
+// ── Test 2: base/cliType → tool flattening ──────────────────────────
+{
+  console.log('Test 2 — CLI profile flattens to tool field');
+  const s = baseSettings();
+  s.agents = {
+    claude: { enabled: true, path: '/usr/local/bin/claude' },
+    'forti-coder': { base: 'claude', model: 'sonnet', env: { ANTHROPIC_AUTH_TOKEN: 'tok' } } as any,
+    'codex-dev': { cliType: 'codex', env: { OPENAI_API_KEY: 'k' } } as any,
+  };
+  migrateAgentsFlatten(s);
+  if (s.agents['claude']?.tool !== 'claude') fail('claude builtin tool not inferred');
+  else pass('claude tool inferred from id');
+  if (s.agents['forti-coder']?.tool !== 'claude') fail(`forti-coder tool wrong: ${s.agents['forti-coder']?.tool}`);
+  else pass('forti-coder tool inferred from base');
+  if ((s.agents['forti-coder'] as any).base) fail('base field not cleaned');
+  else pass('base field removed');
+  if (s.agents['codex-dev']?.tool !== 'codex') fail(`codex-dev tool wrong: ${s.agents['codex-dev']?.tool}`);
+  else pass('codex-dev tool inferred from cliType');
+}
+
+// ── Test 3: defaultAgent pointing to API profile downgrades ──────────
+{
+  console.log('Test 3 — defaultAgent → apiProfile downgrades to claude');
+  const s = baseSettings();
+  s.agents = {
+    claude: { enabled: true, path: '' },
+    'forti-api': { type: 'api', provider: 'anthropic', model: 'm', apiKey: 'k' } as any,
+  };
+  s.defaultAgent = 'forti-api';  // wrong! API id as task default
+  migrateAgentsFlatten(s);
+  if (s.defaultAgent !== 'claude') fail(`expected 'claude', got '${s.defaultAgent}'`);
+  else pass('defaultAgent downgraded to claude');
+}
+
+// ── Test 4: chatAgent pointing to CLI downgrades ─────────────────────
+{
+  console.log('Test 4 — chatAgent → CLI agent downgrades to first apiProfile');
+  const s = baseSettings();
+  s.agents = {
+    claude: { enabled: true, path: '' },
+    'forti-coder': { base: 'claude', model: 'sonnet' } as any,
+  };
+  (s as any).apiProfiles = {
+    'real-api': { provider: 'anthropic', model: 'claude-sonnet-4-6', apiKey: 'k', enabled: true },
+  };
+  s.chatAgent = 'forti-coder';   // wrong! CLI as chat default
+  migrateAgentsFlatten(s);
+  if (s.chatAgent !== 'real-api') fail(`expected 'real-api', got '${s.chatAgent}'`);
+  else pass('chatAgent downgraded to real-api');
+}
+
+// ── Test 5: idempotent on already-migrated shape ────────────────────
+{
+  console.log('Test 5 — idempotent');
+  const s = baseSettings();
+  s.agents = {
+    claude: { tool: 'claude', enabled: true, path: '' },
+    'forti-coder': { tool: 'claude', enabled: true, model: 'sonnet', env: {} },
+  };
+  (s as any).apiProfiles = {
+    'forti-api': { provider: 'openai-compatible', model: 'X', apiKey: 'k', enabled: true },
+  };
+  s.defaultAgent = 'claude';
+  s.chatAgent = 'forti-api';
+  const mutated = migrateAgentsFlatten(s);
+  if (mutated) fail('expected no mutation on already-migrated input');
+  else pass('idempotent (no-op)');
+}
+
+// ── Test 6: orphan entry (no inference possible) is left alone ──────
+{
+  console.log('Test 6 — orphan entry preserved');
+  const s = baseSettings();
+  s.agents = {
+    'mystery-thing': { enabled: true, model: 'whatever' } as any,
+  };
+  migrateAgentsFlatten(s);
+  if (!s.agents['mystery-thing']) fail('mystery-thing got deleted');
+  else if ((s.agents['mystery-thing'] as any).tool) fail('mystery-thing tool inferred when it shouldn\'t');
+  else pass('orphan preserved without tool (UI will skip, user re-adds)');
+}
+
+console.log('');
+if (failures === 0) {
+  console.log('✓ All migration smoke checks passed');
+  process.exit(0);
+} else {
+  console.log(`✗ ${failures} check(s) failed`);
+  process.exit(1);
+}

package/scripts/test-memory-local.ts

@@ -0,0 +1,139 @@
+/**
+ * Phase A §15.4 self-check — LocalMemoryStore must satisfy the
+ * summarizer's needs end-to-end without Temper.
+ *
+ *   pnpm tsx scripts/test-memory-local.ts
+ *
+ * Constructs LocalMemoryStore directly (bypasses getMemoryStore so the
+ * user's settings don't matter — we always exercise the local SQLite
+ * path). Writes summary + fact + cursor + health blocks via the key
+ * helpers, then asserts:
+ *   1. Summarizer happy-path round trip works (put → get → search)
+ *   2. buildMemoryContext recalls user-relevant blocks via search
+ *   3. Cursor putBlock(k, v1) then putBlock(k, v2) replaces, not appends
+ *   4. INTERNAL_KEY_PREFIXES filtering keeps cursor/health out of context
+ */
+
+import { LocalMemoryStore } from '../lib/chat/local-memory';
+import { buildMemoryContext } from '../lib/chat/build-memory-context';
+import {
+  cursorKey,
+  factKey,
+  healthKey,
+  stableHash,
+  summaryKey,
+  INTERNAL_KEY_PREFIXES,
+  type CursorValue,
+} from '../lib/memory/keys';
+
+const NS = '__phaseA_selfcheck__';
+const SID = 'sid-test-1';
+const NOW = Date.now();
+
+async function main() {
+  const store = new LocalMemoryStore(NS);
+  console.log(`Backend: ${store.kind} ns=${store.currentNamespace}`);
+
+  let failures = 0;
+  const fail = (msg: string) => { console.log(`  ✗ ${msg}`); failures += 1; };
+  const pass = (msg: string) => console.log(`  ✓ ${msg}`);
+
+  // ── 1. Summarizer happy-path round trip ──────────────────────────
+  console.log('Test 1 — summarizer round trip');
+  const sk = summaryKey(SID, NOW);
+  await store.putBlock(
+    sk,
+    {
+      text: 'User asked about Forge architecture. Discussed memory layer + summarizer design.',
+      from_ts: NOW - 1000, to_ts: NOW, message_count: 10,
+      model: 'haiku', provider: 'anthropic', ingest_ts: NOW,
+    },
+    { description: 'session summary', scope: 'own' },
+  );
+
+  const fk = factKey('user', 'zliu', stableHash('prefers terse responses with code'));
+  await store.putBlock(
+    fk,
+    {
+      content: 'prefers terse responses with code',
+      subject_kind: 'preference', subject: 'zliu',
+      source_ref: `chat:${SID}@${NOW}`, confidence: null,
+      extracted_by: 'summarizer',
+    },
+    { description: 'prefers terse responses with code', scope: 'own' },
+  );
+
+  const sb = await store.getBlock(sk);
+  const fb = await store.getBlock(fk);
+  if (sb?.value) pass(`summary readable at ${sk}`); else fail('summary block missing');
+  if (fb?.value) pass(`fact readable at ${fk}`); else fail('fact block missing');
+
+  // ── 2. buildMemoryContext recalls relevant content ───────────────
+  console.log('Test 2 — buildMemoryContext recalls summary via search');
+  const ctxA = await buildMemoryContext({
+    store,
+    currentUserMessage: 'tell me about the memory summarizer',
+  });
+  if (ctxA.hits.length > 0) pass(`got ${ctxA.hits.length} hit(s) for query`);
+  else fail('expected search hits for "memory summarizer" query, got 0');
+  const hitText = ctxA.hits.map((h) => h.fact ?? '').join(' | ');
+  if (/summarizer|memory layer/i.test(hitText)) pass('hit contains expected keywords');
+  else fail(`hit text didn't match: ${hitText.slice(0, 200)}`);
+
+  // ── 3. Cursor upsert replaces ────────────────────────────────────
+  console.log('Test 3 — cursor upsert replaces');
+  const ck = cursorKey(SID);
+  const v1: CursorValue = { last_ingested_ts: 1, last_run_ts: 1, ingest_count: 1 };
+  const v2: CursorValue = { last_ingested_ts: 999, last_run_ts: 999, ingest_count: 2 };
+  await store.putBlock(ck, v1);
+  await store.putBlock(ck, v2);
+  const after = (await store.getBlock(ck))?.value as CursorValue | undefined;
+  if (after?.last_ingested_ts === 999) pass('cursor replaced (v2 wins)');
+  else fail(`expected last_ingested_ts=999, got ${after?.last_ingested_ts}`);
+  const rows = (await store.listBlocks()).filter((b) => b.key === ck);
+  if (rows.length === 1) pass('cursor row count = 1 (no append)');
+  else fail(`expected 1 cursor row, got ${rows.length}`);
+
+  // ── 4. INTERNAL_KEY_PREFIXES filters cursor/health out of context ─
+  console.log('Test 4 — buildMemoryContext excludes cursor/health by prefix');
+  await store.putBlock(healthKey(SID), { last_run_ts: NOW, error: null, ingest_count: 1, last_token_estimate: 100 });
+
+  // Make cursor + health look attractive to search by giving the user
+  // message a literal token they'd LIKE-match.
+  const ctxB = await buildMemoryContext({
+    store,
+    currentUserMessage: 'summarizer cursor health status',
+  });
+  const allKeys = [
+    ...ctxB.blocks.map((b) => b.key),
+    ...ctxB.hits.map((h) => h.id),
+  ];
+  const leaked = allKeys.filter((k) =>
+    INTERNAL_KEY_PREFIXES.some((p) =>
+      k.startsWith(p) || k.startsWith('block:' + p),
+    ),
+  );
+  if (leaked.length === 0) pass('no cursor/health leaked into context');
+  else fail(`leaked internal blocks: ${leaked.join(', ')}`);
+
+  // Sanity: render output must not literally contain the cursor key
+  if (!ctxB.text.includes('forge.summarizer.cursor:') && !ctxB.text.includes('forge.summarizer.health:')) {
+    pass('rendered context does not contain internal prefixes');
+  } else {
+    fail('rendered context still mentions internal prefix');
+  }
+
+  console.log('');
+  if (failures === 0) {
+    console.log('✓ Phase A LocalMemoryStore self-check passed.');
+    process.exit(0);
+  } else {
+    console.log(`✗ ${failures} check(s) failed.`);
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('Self-check crashed:', err);
+  process.exit(2);
+});

package/scripts/test-memory-upsert.ts

@@ -0,0 +1,106 @@
+/**
+ * Memory store upsert idempotency check.
+ *
+ *   pnpm tsx scripts/test-memory-upsert.ts
+ *
+ * Verifies putBlock semantics needed by the chat summarizer:
+ *   - Same key written twice → second value wins (replace, not append)
+ *   - listBlocks shows one row, not two
+ *   - factKey() produces stable hashes across runs
+ *
+ * Runs against whichever backend getMemoryStore() picks — typically
+ * LocalMemoryStore unless Temper creds are set. Writes to a sentinel
+ * namespace key prefix and cleans up after itself.
+ */
+
+import { getMemoryStore } from '../lib/chat/memory-store';
+import {
+  cursorKey,
+  factKey,
+  summaryKey,
+  healthKey,
+  stableHash,
+  type CursorValue,
+} from '../lib/memory/keys';
+
+const SENTINEL_SESSION = '__upsert_test__';
+
+async function main() {
+  const store = getMemoryStore();
+  console.log(`Backend: ${store.kind} (enabled=${store.enabled})`);
+  if (!store.enabled) {
+    console.error('Store not enabled — cannot run test.');
+    process.exit(1);
+  }
+
+  let failures = 0;
+  const fail = (msg: string) => {
+    console.log(`  ✗ ${msg}`);
+    failures += 1;
+  };
+  const pass = (msg: string) => console.log(`  ✓ ${msg}`);
+
+  // ── 1. cursor upsert: v1 then v2 → v2 wins ───────────────────────
+  console.log('Test 1 — cursor upsert');
+  const ck = cursorKey(SENTINEL_SESSION);
+  const v1: CursorValue = { last_ingested_ts: 100, last_run_ts: 200, ingest_count: 1 };
+  const v2: CursorValue = { last_ingested_ts: 500, last_run_ts: 600, ingest_count: 2 };
+  await store.putBlock(ck, v1);
+  await store.putBlock(ck, v2);
+  const read = (await store.getBlock(ck))?.value as CursorValue | undefined;
+  if (!read) fail('getBlock returned null after putBlock');
+  else if (read.last_ingested_ts !== 500) fail(`expected last_ingested_ts=500, got ${read.last_ingested_ts}`);
+  else if (read.ingest_count !== 2) fail(`expected ingest_count=2, got ${read.ingest_count}`);
+  else pass('second putBlock replaced first');
+
+  // ── 2. listBlocks has one row for the key, not two ───────────────
+  console.log('Test 2 — listBlocks dedup');
+  const all = await store.listBlocks();
+  const matching = all.filter((b) => b.key === ck);
+  if (matching.length === 1) pass(`exactly one row for ${ck}`);
+  else fail(`expected 1 row for ${ck}, got ${matching.length}`);
+
+  // ── 3. factKey is stable across calls ────────────────────────────
+  console.log('Test 3 — factKey stable hash');
+  const fk1 = factKey('user', 'zliu', stableHash('prefers terse responses'));
+  const fk2 = factKey('user', 'zliu', stableHash('prefers terse responses'));
+  if (fk1 === fk2) pass(`same content → same key (${fk1})`);
+  else fail(`hash drift: ${fk1} vs ${fk2}`);
+
+  // Different content → different key
+  const fk3 = factKey('user', 'zliu', stableHash('uses Chinese in chat'));
+  if (fk3 !== fk1) pass('different content → different key');
+  else fail('hash collision: distinct content produced same key');
+
+  // ── 4. summary / health keys round-trip ──────────────────────────
+  console.log('Test 4 — summary/health keys round-trip');
+  const sk = summaryKey(SENTINEL_SESSION, 12345);
+  const hk = healthKey(SENTINEL_SESSION);
+  await store.putBlock(sk, { text: 'hello', from_ts: 1, to_ts: 12345, message_count: 5, model: 'm', provider: 'p', ingest_ts: Date.now() });
+  await store.putBlock(hk, { last_run_ts: Date.now(), error: null, ingest_count: 1, last_token_estimate: 100 });
+  const sb = await store.getBlock(sk);
+  const hb = await store.getBlock(hk);
+  if (sb) pass('summary block round-tripped');
+  else fail('summary block missing after putBlock');
+  if (hb) pass('health block round-tripped');
+  else fail('health block missing after putBlock');
+
+  // ── cleanup ──────────────────────────────────────────────────────
+  console.log('Cleanup: removing sentinel blocks');
+  // No deleteBlock on the interface — leave them; sentinel ns prefix
+  // makes them identifiable. Re-running the test overwrites in place.
+
+  console.log('');
+  if (failures === 0) {
+    console.log('✓ All checks passed.');
+    process.exit(0);
+  } else {
+    console.log(`✗ ${failures} check(s) failed.`);
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('Test crashed:', err);
+  process.exit(2);
+});