kiku-agent 1.3.1 → 1.3.3

package/server/agent/tests/sessionAndCopy.test.js

@@ -0,0 +1,267 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { AgentSession } from '../session.js';
+import { parseDetailsRequest, getCopyableContent } from '../queryDetails.js';
+import { savePersistedProviderKey, getPersistedProviderKeys, CLOUD_PROVIDERS } from '../config.js';
+import { LLMClient } from '../llmClient.js';
+import { routeCommand } from '../commands.js';
+
+test('AgentSession records full conversation metadata, tools, reasoning, and exports', async () => {
+  const session = new AgentSession({ persistence: false });
+  
+  const userMsg = session.createUserMessage('Who is Ju Jingyi?', { queryNumber: 1 });
+  assert.equal(userMsg.role, 'user');
+  assert.equal(userMsg.queryNumber, 1);
+  assert.equal(userMsg.parts[0].content, 'Who is Ju Jingyi?');
+
+  const assistantMsg = session.createAssistantMessage({
+    model: 'openai/gpt-oss-120b',
+    provider: 'Groq Cloud',
+    queryNumber: 1,
+  });
+  assert.equal(assistantMsg.role, 'assistant');
+  assert.equal(assistantMsg.model, 'openai/gpt-oss-120b');
+
+
+  session.addReasoningPart(assistantMsg, 'Analyzing query about Ju Jingyi profile...');
+  session.finalizeReasoningPart(assistantMsg);
+  assert.equal(assistantMsg.parts[0].type, 'reasoning');
+
+
+  const toolPart = session.addToolPart(assistantMsg, 'get_profile_and_fandom', {});
+  session.finalizeToolPart(assistantMsg, toolPart.id, {
+    status: 'ok', 
+    profile: { name: 'Ju Jingyi', fandom: 'Miju' },
+  });
+  assert.equal(assistantMsg.parts[1].type, 'tool');
+  assert.equal(assistantMsg.parts[1].status, 'ok');
+
+
+  session.addTextPart(assistantMsg, 'Ju Jingyi is a talented Chinese singer and actress.');
+
+
+  const stats = session.getToolStats();
+  assert.ok(stats.get_profile_and_fandom);
+  assert.equal(stats.get_profile_and_fandom.count, 1);
+  assert.equal(stats.get_profile_and_fandom.successCount, 1);
+
+
+  const md = session.getTranscriptMarkdown();
+  assert.ok(md.includes('# Kiku AI Agent — Session Transcript'));
+  assert.ok(md.includes('get_profile_and_fandom'));
+  assert.ok(md.includes('Ju Jingyi is a talented Chinese singer'));
+
+ 
+  const jsonStr = session.getTranscriptJson();
+  const parsedJson = JSON.parse(jsonStr);
+  assert.equal(parsedJson.id, session.id);
+  assert.equal(parsedJson.messages.length, 2);
+
+ 
+  const textTranscript = session.getTranscriptText();
+  assert.ok(textTranscript.includes('Who is Ju Jingyi?'));
+
+ 
+  const expMd = await session.exportToMarkdown();
+  assert.equal(expMd.format, 'markdown');
+  assert.ok(expMd.filePath.endsWith('.md'));
+
+  const expJson = await session.exportToJson();
+  assert.equal(expJson.format, 'json');
+  assert.ok(expJson.filePath.endsWith('.json'));
+
+  const expTxt = await session.exportToText();
+  assert.equal(expTxt.format, 'text');
+  assert.ok(expTxt.filePath.endsWith('.txt'));
+});
+
+test('Isolated Provider Keys persist and do not overwrite each other', () => {
+
+  savePersistedProviderKey('groq', 'fixture-groq-key');
+  assert.equal(CLOUD_PROVIDERS.groq.apiKey, 'fixture-groq-key');
+
+ 
+  savePersistedProviderKey('openrouter', 'fixture-openrouter-key');
+  assert.equal(CLOUD_PROVIDERS.openrouter.apiKey, 'fixture-openrouter-key');
+
+ 
+  assert.equal(CLOUD_PROVIDERS.groq.apiKey, 'fixture-groq-key');
+
+ 
+  const keys = getPersistedProviderKeys();
+  assert.equal(keys.groq, 'fixture-groq-key');
+  assert.equal(keys.openrouter, 'fixture-openrouter-key');
+
+
+  const client = new LLMClient({ provider: 'groq' });
+  client.setApiKey('sk-openai-custom-key', 'openai');
+  assert.equal(CLOUD_PROVIDERS.openai.apiKey, 'sk-openai-custom-key');
+  assert.equal(client.apiKey, 'fixture-groq-key'); 
+
+  savePersistedProviderKey('groq', '');
+  savePersistedProviderKey('openrouter', '');
+  savePersistedProviderKey('openai', '');
+});
+
+test('queryDetails parses session and granular query copy requests', () => {
+  const reqSession = parseDetailsRequest('session');
+  assert.equal(reqSession.isSession, true);
+  assert.equal(reqSession.view, 'markdown');
+
+  const reqSessionJson = parseDetailsRequest('session json');
+  assert.equal(reqSessionJson.isSession, true);
+  assert.equal(reqSessionJson.view, 'json');
+
+  const reqQ1All = parseDetailsRequest('Q1 all');
+  assert.equal(reqQ1All.queryNumber, 1);
+  assert.equal(reqQ1All.view, 'all');
+
+  const reqQ1Tool = parseDetailsRequest('Q1 tool 2');
+  assert.equal(reqQ1Tool.queryNumber, 1);
+  assert.equal(reqQ1Tool.view, 'tool');
+  assert.equal(reqQ1Tool.toolIndex, 2);
+
+  const session = new AgentSession({ persistence: false });
+  session.createUserMessage('Test question');
+  const asst = session.createAssistantMessage({ model: 'gemma-4' });
+  session.addTextPart(asst, 'Test answer');
+
+  const copyableSession = getCopyableContent(null, reqSession, session);
+  assert.ok(copyableSession.text.includes('# Kiku AI Agent — Session Transcript'));
+  assert.ok(copyableSession.text.includes('Test question'));
+
+  const copyableJson = getCopyableContent(null, reqSessionJson, session);
+  const parsed = JSON.parse(copyableJson.text);
+  assert.equal(parsed.id, session.id);
+});
+
+test('Commands /session export and /session clear execute cleanly', async () => {
+  let ended = false;
+  const mockAgent = {
+    session: new AgentSession({ persistence: false }),
+    endSession: async () => {
+      ended = true;
+      return true;
+    },
+    memory: {
+      getArchivedSessions: () => [],
+    },
+  };
+
+  mockAgent.session.createUserMessage('Sample query');
+
+  const ctxExport = {
+    agent: mockAgent,
+    sub: 'export',
+    extra: 'markdown',
+  };
+  const resExport = await routeCommand('/session export markdown', ctxExport);
+  assert.equal(resExport, 'HANDLED');
+
+  const ctxClear = {
+    agent: mockAgent,
+    sub: 'clear',
+    extra: '',
+  };
+  const resClear = await routeCommand('/session clear', ctxClear);
+  assert.equal(resClear, 'HANDLED');
+  assert.equal(ended, true);
+});
+
+test('Commands /copy routes answer, thinking, tools, all, and session variants', async () => {
+  let copiedText = '';
+  const mockDetails = {
+    number: 1,
+    prompt: 'Who is Ju Jingyi?',
+    answer: 'Ju Jingyi is a singer and actress.',
+    thinking: 'Querying catalog profile.',
+    tools: [{ name: 'get_profile', duration: 15, args: { query: 'Ju Jingyi' }, result: { count: 1 } }],
+    status: 'complete',
+  };
+
+  const session = new AgentSession({ persistence: false });
+  session.createUserMessage('Who is Ju Jingyi?');
+  const asst = session.createAssistantMessage({ model: 'gemma-4' });
+  session.addTextPart(asst, 'Ju Jingyi is a singer and actress.');
+
+  const ctx = {
+    agent: {
+      session,
+      lastQueryDetails: mockDetails,
+    },
+    copyQueryDetails: (ref) => {
+      const req = parseDetailsRequest(ref);
+      const copyable = getCopyableContent(mockDetails, req, session);
+      copiedText = copyable?.text || '';
+      return Boolean(copyable?.text);
+    },
+    sub: '',
+    extra: '',
+  };
+
+
+  await routeCommand('/copy', ctx);
+  assert.equal(copiedText, 'Ju Jingyi is a singer and actress.');
+
+
+  await routeCommand('/copy thinking', { ...ctx, sub: 'thinking', extra: '' });
+  assert.equal(copiedText, 'Querying catalog profile.');
+
+ 
+  await routeCommand('/copy think', { ...ctx, sub: 'think', extra: '' });
+  assert.equal(copiedText, 'Querying catalog profile.');
+
+  
+  await routeCommand('/copy tools', { ...ctx, sub: 'tools', extra: '' });
+  assert.ok(copiedText.includes('get_profile'));
+
+
+  await routeCommand('/copy tool 1', { ...ctx, sub: 'tool', extra: '1' });
+  assert.ok(copiedText.includes('get_profile'));
+
+  
+  await routeCommand('/copy all', { ...ctx, sub: 'all', extra: '' });
+  assert.ok(copiedText.includes('# Question 1'));
+  assert.ok(copiedText.includes('Ju Jingyi is a singer and actress.'));
+
+  
+  await routeCommand('/copy session markdown', { ...ctx, sub: 'session', extra: 'markdown' });
+  assert.ok(copiedText.includes('# Kiku AI Agent — Session Transcript'));
+  assert.ok(copiedText.includes('Who is Ju Jingyi?'));
+});
+
+test('AgentSession synchronizes totalToolCalls and /session info from message tool parts', async () => {
+  const session = new AgentSession({ persistence: false });
+  session.restoreFromSnapshot({
+    id: 'sess_test_sync',
+    createdAt: new Date(),
+    messages: [
+      { role: 'user', parts: [{ type: 'text', content: 'hello' }] },
+      {
+        role: 'assistant',
+        parts: [
+          { type: 'tool', name: 'search_works', args: { query: 'In Blossom' }, status: 'ok', durationMs: 40 },
+          { type: 'text', content: 'In Blossom info' }
+        ]
+      }
+    ],
+    stats: {
+      totalQueries: 1,
+      totalToolCalls: 0,
+      totalDurationMs: 0
+    }
+  });
+
+  assert.equal(session.stats.totalToolCalls, 1);
+  assert.equal(session.getTotalToolCalls(), 1);
+  assert.equal(session.stats.totalDurationMs, 40);
+
+  const toolStats = session.getToolStats();
+  assert.equal(toolStats.search_works.count, 1);
+
+  const mockAgent = { session };
+  const res = await routeCommand('/session info', { agent: mockAgent, sub: 'info', extra: '' });
+  assert.equal(res, 'HANDLED');
+});
+

package/server/agent/tests/sidebarControls.test.js

@@ -0,0 +1,135 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import test from 'node:test';
+import serverlessHandler, { isWebChatRequest } from '../../../api/index.js';
+import { getWebChatHtml } from '../../web-chat/ui/htmlBuilder.js';
+
+test('Vercel routes the web chat page through the serverless web-chat handler first', () => {
+  const config = JSON.parse(readFileSync(new URL('../../../vercel.json', import.meta.url), 'utf8'));
+  const chatIndex = config.rewrites.findIndex(rule => rule.source === '/chat');
+  const apiIndex = config.rewrites.findIndex(rule => rule.source === '/api/(.*)');
+  const spaIndex = config.rewrites.findIndex(rule => rule.source === '/(.*)');
+
+  assert.ok(chatIndex >= 0);
+  assert.equal(config.rewrites[chatIndex].destination, '/api/index.js');
+  assert.ok(chatIndex < apiIndex);
+  assert.ok(apiIndex < spaIndex);
+});
+
+test('serverless dispatcher separates web-chat APIs from REST API v1', () => {
+  [
+    '/chat',
+    '/chat/session',
+    '/api/chat',
+    '/api/status',
+    '/api/suggestions',
+    '/api/ai-suggest',
+    '/api/quiz',
+    '/api/export',
+    '/api/verify',
+    '/api/news',
+    '/api/compare',
+    '/api/clarify',
+    '/api/clarify/analytics',
+    '/api/feedback',
+    '/api/feedback/stats'
+  ].forEach(url => assert.equal(isWebChatRequest({ url }), true, url));
+
+  assert.equal(isWebChatRequest({ url: '/api/v1/timeline' }), false);
+  assert.equal(isWebChatRequest({ url: '/api/v1/profile' }), false);
+});
+
+test('serverless dispatcher renders the Agent Chat page for /chat routes', async () => {
+  const response = {
+    headers: {},
+    statusCode: 0,
+    body: '',
+    setHeader(name, value) { this.headers[name] = value; },
+    writeHead(statusCode, headers = {}) {
+      this.statusCode = statusCode;
+      Object.assign(this.headers, headers);
+    },
+    end(body = '') { this.body += body; }
+  };
+
+  await serverlessHandler({ url: '/chat', method: 'GET' }, response);
+
+  assert.equal(response.statusCode, 200);
+  assert.match(response.headers['Content-Type'], /text\/html/);
+  assert.match(response.body, /id="app-sidebar"/);
+  assert.match(response.body, /KIKU AGENT/);
+});
+
+test('sidebar language refresh preserves dynamic control state labels', () => {
+  const html = getWebChatHtml();
+  const start = html.indexOf('function updateLanguageUi()');
+  const end = html.indexOf('var JU_JINGYI_PLAYLIST', start);
+  const languageFunction = html.slice(start, end);
+
+  const genericLabels = languageFunction.indexOf('updateSidebarLabels(t);');
+  assert.ok(genericLabels >= 0);
+  assert.ok(genericLabels < languageFunction.indexOf('updatePetalsLabel();'));
+  assert.ok(genericLabels < languageFunction.indexOf('updateThemeIcon();'));
+  assert.ok(genericLabels < languageFunction.indexOf('updateSoundIcon();'));
+  assert.ok(genericLabels < languageFunction.indexOf("document.getElementById('sidebar-lang-label')"));
+});
+
+test('jukebox derives sidebar and tab counts from the playlist', () => {
+  const html = getWebChatHtml();
+
+  assert.match(html, /function updateJukeboxCountLabels\(\)/);
+  assert.match(html, /const total = JU_JINGYI_PLAYLIST\.length/);
+  assert.match(html, /id="sidebar-music-button"/);
+  assert.doesNotMatch(html, /Jukebox \(44 บทเพลง\)/);
+  assert.doesNotMatch(html, /ทั้งหมด \(44\)/);
+});
+
+test('quick-action-menu jukebox entry opens through a single-call wrapper', () => {
+  const html = getWebChatHtml();
+
+  assert.match(html, /function openMusicFromQuickActions\(\)/);
+  const wrapperStart = html.indexOf('function openMusicFromQuickActions()');
+  const wrapperBody = html.slice(wrapperStart, wrapperStart + 300);
+  assert.match(wrapperBody, /closeQuickActions\(\)/);
+  assert.match(wrapperBody, /openMusicModal\(\)/);
+  assert.ok(wrapperBody.indexOf('closeQuickActions()') < wrapperBody.indexOf('openMusicModal()'));
+
+  assert.match(html, /onclick="openMusicFromQuickActions\(\)"/);
+  assert.doesNotMatch(html, /onclick="openMusicModal\(\); closeQuickActions\(\)"/);
+});
+
+test('every static onclick handler in the chat shell is exposed on window', () => {
+  const html = getWebChatHtml();
+
+  for (const name of [
+    'openMusicModal',
+    'openMusicFromQuickActions',
+    'closeMusicModal',
+    'toggleAppSidebar',
+    'toggleQuickActions',
+    'closeQuickActions',
+    'openMiniPlayerFromCard',
+    'switchVoiceToDetectedLang',
+    'handleQuickChipClick',
+    'cycleSidebarAd'
+  ]) {
+    assert.match(html, new RegExp('function ' + name + '\\('), name + ' is defined');
+    assert.match(html, new RegExp('\\b' + name + ','), name + ' is exposed on window');
+  }
+});
+
+test('sidebar export downloads through the export API and reports failures', () => {
+  const html = getWebChatHtml();
+  const start = html.indexOf('async function exportChat()');
+  const end = html.indexOf('function shareChatLink()', start);
+  const exportFunction = html.slice(start, end);
+
+  assert.ok(start >= 0);
+  assert.match(exportFunction, /fetch\('\/api\/export'/);
+  assert.match(exportFunction, /if \(!response\.ok\) throw new Error/);
+  assert.match(exportFunction, /link\.download = filename/);
+  assert.doesNotMatch(exportFunction, /showToast/);
+  assert.doesNotMatch(exportFunction, /navigator\.clipboard/);
+  assert.match(html, /title="ส่งออกบทสนทนาเป็นไฟล์ Markdown"/);
+  assert.doesNotMatch(html, /Export \/ Copy Chat/);
+});

package/server/agent/tests/statefulMemory.test.js

@@ -0,0 +1,277 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import os from 'node:os';
+import path from 'node:path';
+import { mkdtemp, rm } from 'node:fs/promises';
+
+import { HierarchicalStore, parseAndValidatePath, computeContentHash } from '../memory/hierarchicalStore.js';
+import { ContextAllocator, extractWordTokens } from '../memory/contextAllocator.js';
+import { ReflectionWorker } from '../memory/reflectionWorker.js';
+import { AgentMemory } from '../memory.js';
+import { executeTool } from '../tools.js';
+
+test('extractWordTokens segments Thai and CJK text without whitespace', () => {
+  const thaiTokens = extractWordTokens('จวีจิ้งอีผลงานเพลง');
+  const cjkTokens = extractWordTokens('鞠婧祎音乐作品');
+  assert.ok(thaiTokens.length >= 2, `expected Thai segmentation, got ${thaiTokens.join('|')}`);
+  assert.ok(cjkTokens.length >= 2, `expected CJK segmentation, got ${cjkTokens.join('|')}`);
+});
+
+test('parseAndValidatePath correctly parses valid hierarchical memory paths', () => {
+  const p1 = parseAndValidatePath('kiku/runs/run_task_001/state');
+  assert.equal(p1.section, 'runs');
+  assert.equal(p1.runId, 'run_task_001');
+  assert.equal(p1.subpath, 'state');
+
+  const p2 = parseAndValidatePath('kiku/runs/run_task_001/plan');
+  assert.equal(p2.subpath, 'plan');
+
+  const p3 = parseAndValidatePath('kiku/runs/run_task_001/artifacts');
+  assert.equal(p3.subpath, 'artifacts');
+
+  const p4 = parseAndValidatePath('kiku/reflections/web_search');
+  assert.equal(p4.section, 'reflections');
+  assert.equal(p4.domain, 'web_search');
+
+  const p5 = parseAndValidatePath('kiku/guidelines/drama');
+  assert.equal(p5.section, 'guidelines');
+  assert.equal(p5.domain, 'drama');
+
+  const p6 = parseAndValidatePath('kiku/archive/run_task_001');
+  assert.equal(p6.section, 'archive');
+  assert.equal(p6.runId, 'run_task_001');
+});
+
+test('parseAndValidatePath rejects invalid paths, traversal, and invalid IDs', () => {
+  assert.throws(() => parseAndValidatePath('../kiku/runs/run_1/state'), /Invalid path traversal/);
+  assert.throws(() => parseAndValidatePath('invalid/runs/run_1/state'), /Path must start with "kiku\/"/);
+  assert.throws(() => parseAndValidatePath('kiku/unknown/section'), /Unrecognized memory section/);
+  assert.throws(() => parseAndValidatePath('kiku/runs/!bad@id/state'), /Invalid run_id/);
+  assert.throws(() => parseAndValidatePath('kiku/runs/run_1/bad_subpath'), /Invalid run subpath/);
+});
+
+test('HierarchicalStore enforces Pointer-Over-Data Rule (>1000 characters)', async () => {
+  const tempDir = await mkdtemp(path.join(os.tmpdir(), 'kiku-hstore-'));
+  try {
+    const store = new HierarchicalStore({
+      baseDir: path.join(tempDir, 'nodes'),
+      artifactsDir: path.join(tempDir, 'artifacts')
+    });
+
+  
+    const smallText = 'Hello Kiku memory engine';
+    const smallRes = await store.setNode('kiku/guidelines/small', smallText);
+    assert.equal(smallRes.node.content, smallText);
+    const largePayload = 'A'.repeat(2500);
+    const largeRes = await store.setNode('kiku/runs/run_pointer_test/state', {
+      rawLog: largePayload,
+      step: 'step1'
+    });
+
+    assert.equal(largeRes.node.content.$type, 'pointer');
+    assert.ok(largeRes.node.content.uri.startsWith('file://'));
+    assert.equal(largeRes.node.content.charCount > 2500, true);
+
+ 
+    const resolved = await store.resolvePointer(largeRes.node.content);
+    assert.equal(resolved.step, 'step1');
+    assert.equal(resolved.rawLog, largePayload);
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+});
+
+test('HierarchicalStore enforces Run-ID Scoping & Path Isolation', async () => {
+  const store = new HierarchicalStore({ persistence: false });
+  await store.setNode('kiku/runs/run_alpha/state', { status: 'IN_PROGRESS' }, { scopedRunId: 'run_alpha' });
+
+
+  await assert.rejects(
+    async () => store.setNode('kiku/runs/run_beta/state', { status: 'ATTACK' }, { scopedRunId: 'run_alpha' }),
+    /Run scoping violation/
+  );
+});
+
+test('HierarchicalStore enforces Idempotency with content hashing', async () => {
+  const store = new HierarchicalStore({ persistence: false });
+  const content = { status: 'IN_PROGRESS', step: 'search_works' };
+
+  const first = await store.setNode('kiku/runs/run_idem/state', content);
+  assert.equal(first.status, 'saved');
+
+ 
+  const second = await store.setNode('kiku/runs/run_idem/state', content);
+  assert.equal(second.status, 'unchanged');
+  assert.equal(first.contentHash, second.contentHash);
+});
+
+test('Real-time Checkpointing: checkpointStep and recordFailure', async () => {
+  const store = new HierarchicalStore({ persistence: false });
+
+  const cp1 = await store.checkpointStep({
+    runId: 'run_cp_test',
+    stepName: 'analyze_query',
+    status: 'completed',
+    summary: 'Analyzed user query successfully'
+  });
+  assert.equal(cp1.status, 'completed');
+  assert.equal(cp1.currentStep, 'analyze_query');
+
+  const cp2 = await store.checkpointStep({
+    runId: 'run_cp_test',
+    stepName: 'query_catalog',
+    status: 'in_progress',
+    summary: 'Querying catalog works for Ju Jingyi'
+  });
+  assert.equal(cp2.currentStep, 'query_catalog');
+  assert.equal(cp2.totalSubtasks, 2);
+
+
+  const failRes = await store.recordFailure({
+    runId: 'run_cp_test',
+    errorTrace: 'HTTP 429 Rate limited on endpoint',
+    recoveryAction: 'Fallback to local catalog tools',
+    toolName: 'web_search'
+  });
+  assert.equal(failRes.status, 'recorded');
+
+ 
+  const hydrated = await store.loadActiveRun('run_cp_test');
+  assert.equal(hydrated.exists, true);
+  assert.equal(hydrated.state.currentStep, 'query_catalog');
+  assert.equal(hydrated.plan.subtasks.length, 2);
+  assert.equal(hydrated.state.failures.length, 1);
+  assert.equal(hydrated.state.failures[0].toolName, 'web_search');
+});
+
+test('Post-Run Compaction Worker: Summarization, Reflection Extraction, Archival & TTL', async () => {
+  const store = new HierarchicalStore({ persistence: false });
+  const worker = new ReflectionWorker({ store, ttlDays: 3 });
+
+  const runId = 'run_worker_test';
+  await store.checkpointStep({
+    runId,
+    stepName: 'fetch_data',
+    status: 'completed',
+    summary: 'Fetched video information'
+  });
+
+  await store.recordFailure({
+    runId,
+    errorTrace: 'Connection timeout after 30s',
+    recoveryAction: 'Switched to bilibili mirror search',
+    toolName: 'search_youtube'
+  });
+
+ 
+  const result = await worker.processPostRunCompaction(runId, 'COMPLETED');
+  assert.equal(result.success, true);
+  assert.equal(result.finalStatus, 'COMPLETED');
+  assert.equal(result.executiveSummary.completedSteps, 1);
+  assert.equal(result.reflectionsExtracted, 1);
+
+
+  const reflection = await store.getNode('kiku/reflections/search_youtube');
+  assert.ok(reflection);
+  assert.equal(reflection.content.recoveryAction, 'Switched to bilibili mirror search');
+  assert.equal(reflection.content.occurrences, 1);
+
+ 
+  const activeCheck = await store.loadActiveRun(runId);
+  assert.equal(activeCheck.exists, false);
+
+  const archiveNode = await store.getNode(`kiku/archive/${runId}`);
+  assert.ok(archiveNode);
+  const resolvedArchive = await store.resolvePointer(archiveNode.content);
+  assert.equal(resolvedArchive.runId, runId);
+  assert.ok(resolvedArchive.expiresAt);
+});
+
+test('ContextAllocator implements 4-Tier Quota and Context Hydration', async () => {
+  const store = new HierarchicalStore({ persistence: false });
+  const memory = new AgentMemory({ persistence: false });
+
+ 
+  await store.setNode('kiku/guidelines/drama', 'Always verify broadcast year with get_work_detail before stating.');
+  memory.addUserSkill('ตอบคำถามสั้น กระชับ ชัดเจน');
+
+ 
+  const runId = 'run_context_alloc_test';
+  await store.checkpointStep({
+    runId,
+    stepName: 'verify_year',
+    status: 'in_progress',
+    summary: 'Checking year for The Legend of White Snake'
+  });
+
+  
+  await store.setNode('kiku/reflections/search_works', {
+    domain: 'search_works',
+    issuePattern: 'Generic title search matches too many items',
+    recoveryAction: 'Include artist name Ju Jingyi to narrow results',
+    confidence: 1.2
+  });
+
+ 
+  memory.addFact('鞠婧祎 played Bai Suzhen in The Legend of White Snake (2019)');
+
+  const allocator = new ContextAllocator({ store, maxTokens: 1500 });
+  const context = await allocator.allocateContext({
+    currentQuery: 'search works White Snake',
+    activeRunId: runId,
+    memory
+  });
+
+  assert.match(context, /=== STATEFUL & SELF-REFLECTIVE MEMORY CONTEXT ===/);
+  assert.match(context, /USER GUIDELINES & PREFERENCES/);
+  assert.match(context, /Always verify broadcast year/);
+  assert.match(context, /ACTIVE TASK RUN STATE/);
+  assert.match(context, /verify_year/);
+  assert.match(context, /EPISODIC REFLECTIONS & GOTCHAS/);
+  assert.match(context, /Generic title search/);
+  assert.match(context, /GENERAL KNOWLEDGE & CONTEXT/);
+});
+
+test('Agent Tools: checkpoint_step, record_failure, and load_active_run work via executeTool', async () => {
+  const memory = new AgentMemory({ persistence: false });
+  const runId = 'run_tool_exec_test';
+
+ 
+  const cpRes = await executeTool('checkpoint_step', {
+    run_id: runId,
+    step_name: 'parse_input',
+    status: 'completed',
+    summary: 'Input arguments verified'
+  }, { memory });
+  assert.equal(cpRes.status, 'success');
+  assert.equal(cpRes.checkpoint.currentStep, 'parse_input');
+
+ 
+  const failRes = await executeTool('record_failure', {
+    run_id: runId,
+    error_trace: 'ETIMEDOUT on remote host',
+    recovery_action: 'Switched to cache fallback',
+    tool_name: 'fetch_webpage'
+  }, { memory });
+  assert.equal(failRes.status, 'success');
+
+
+  const loadRes = await executeTool('load_active_run', {
+    run_id: runId
+  }, { memory });
+  assert.equal(loadRes.status, 'success');
+  assert.equal(loadRes.run.state.currentStep, 'parse_input');
+  assert.equal(loadRes.run.state.failures.length, 1);
+});
+
+test('AgentMemory backward compatibility: legacy methods and facts remain unaffected', () => {
+  const memory = new AgentMemory({ persistence: false });
+  memory.addFact('Test fact about Ju Jingyi', { category: 'music' });
+  const facts = memory.getRelevantFacts('music');
+  assert.equal(facts.length, 1);
+  assert.equal(facts[0].content, 'Test fact about Ju Jingyi');
+
+  const legacyContext = memory.buildMemoryContext('music');
+  assert.match(legacyContext, /=== LONG-TERM MEMORY CONTEXT ===/);
+  assert.match(legacyContext, /Test fact about Ju Jingyi/);
+});