create-walle 0.9.0 → 0.9.3

package/template/wall-e/context/context-builder.js

@@ -0,0 +1,355 @@
+'use strict';
+
+const brain = require('../brain');
+const { classifyTopics } = require('./topic-matcher');
+
+/**
+ * Dynamic context builder for Wall-E chat.
+ * Replaces the static ~4KB system prompt with a three-layer prompt:
+ *   1. Core (always, ~400 tokens): identity, capabilities, reasoning instructions
+ *   2. Relevant (per-message, ~800-1500 tokens): FTS5/LIKE matched knowledge & memories
+ *   3. Situational (conditional, 0-500 tokens): calendar, Slack, tasks — only when relevant
+ *
+ * Estimated savings: 50-70% fewer tokens vs the old static prompt.
+ */
+
+/**
+ * Build a dynamic system prompt based on the user's message.
+ * @param {string} userMessage - The current user message
+ * @param {string} channel - Channel name (ctm, imessage, slack_dm)
+ * @param {object} [opts] - Optional overrides
+ * @param {string} [opts.sessionSummary] - Compacted session summary to include
+ * @returns {string} The assembled system prompt
+ */
+function buildSystemPrompt(userMessage, channel, opts = {}) {
+  const ownerName = brain.getOwnerName() || 'Owner';
+  const stats = brain.getBrainStats();
+  const topics = classifyTopics(userMessage);
+
+  const core = buildCoreLayer(ownerName, stats, channel);
+  const relevant = buildRelevantLayer(userMessage, topics, ownerName);
+  const situational = buildSituationalLayer(topics, ownerName, channel);
+  const instructions = buildInstructionLayer(ownerName, channel);
+
+  const parts = [core];
+  if (opts.sessionSummary) {
+    parts.push(`## Previous Conversation\n${opts.sessionSummary}`);
+  }
+  if (relevant) parts.push(relevant);
+  if (situational) parts.push(situational);
+  parts.push(instructions);
+
+  return parts.join('\n\n');
+}
+
+/** Layer 1: Core identity — always included (~400 tokens) */
+function buildCoreLayer(ownerName, stats, channel) {
+  let slackCoverage = '';
+  try {
+    const getMeta = brain.getDb().prepare('SELECT value FROM brain_metadata WHERE key = ?');
+    slackCoverage = getMeta.get('slack_coverage')?.value || '';
+  } catch {}
+
+  return `You are WALL-E, ${ownerName}'s personal digital twin. You know ${ownerName} deeply through ${stats.memory_count} memories including ${slackCoverage || 'Slack messages across years'}.
+
+You are an AGENT, not just a chatbot. You have tools — USE THEM. Never say "I can't access that."
+Channel: ${channel}${channel === 'imessage' ? ' (keep responses brief)' : ''}`;
+}
+
+/** Layer 2: Relevant context — matched to the user's message (~800-1500 tokens) */
+function buildRelevantLayer(userMessage, topics, ownerName) {
+  const sections = [];
+
+  // FTS5 search for relevant knowledge triples
+  const relevantKnowledge = searchRelevantKnowledge(userMessage, 15);
+  if (relevantKnowledge.length > 0) {
+    const kSummary = relevantKnowledge.map(k =>
+      `- ${k.subject} ${k.predicate} ${k.object} (${Math.round((k.confidence || 0.5) * 100)}%)`
+    ).join('\n');
+    sections.push(`## Relevant Knowledge\n${kSummary}`);
+  }
+
+  // FTS5 search for relevant memories
+  const relevantMemories = searchRelevantMemories(userMessage, 8);
+  if (relevantMemories.length > 0) {
+    const mSummary = relevantMemories.map(m => {
+      const date = m.timestamp ? m.timestamp.slice(0, 10) : '';
+      const ch = m.source_channel ? ` #${m.source_channel}` : '';
+      return `[${date}${ch}] ${(m.content || '').slice(0, 200)}`;
+    }).join('\n');
+    sections.push(`## Relevant Memories\n${mSummary}`);
+  }
+
+  // Include people context only if the message mentions people
+  if (topics.includes('people')) {
+    const peopleSummary = buildPeopleContext(userMessage);
+    if (peopleSummary) sections.push(peopleSummary);
+  }
+
+  // Include pre-computed metadata if asking about relationships or topics
+  if (topics.includes('people') || topics.includes('work') || topics.includes('slack')) {
+    const meta = buildMetadataContext(topics);
+    if (meta) sections.push(meta);
+  }
+
+  return sections.join('\n\n');
+}
+
+/** Layer 3: Situational context — only when relevant (0-500 tokens) */
+function buildSituationalLayer(topics, ownerName, channel) {
+  const sections = [];
+
+  // Calendar context if morning or asking about schedule
+  if (topics.includes('calendar')) {
+    sections.push(`## Calendar\nUse the calendar_events tool to check ${ownerName}'s schedule.`);
+  }
+
+  // Slack context if asking about messages
+  if (topics.includes('slack')) {
+    // Include a small sample of recent Slack messages for voice/context
+    try {
+      const db = brain.getDb();
+      const recentSlack = db.prepare(`
+        SELECT content, timestamp, source_channel FROM memories
+        WHERE source = 'slack' AND direction = 'outbound' AND length(content) > 20
+        ORDER BY timestamp DESC LIMIT 5
+      `).all();
+      if (recentSlack.length > 0) {
+        const sample = recentSlack.map(m =>
+          `[${m.timestamp?.slice(0, 10)} ${m.source_channel || 'DM'}] ${(m.content || '').slice(0, 150)}`
+        ).join('\n');
+        sections.push(`## Recent Slack (${ownerName}'s words)\n${sample}`);
+      }
+    } catch {}
+  }
+
+  // Tools/MCP context if asking about tools or automation
+  if (topics.includes('tools')) {
+    const mcpList = buildMcpContext();
+    if (mcpList) sections.push(`## MCP Servers\n${mcpList}`);
+  }
+
+  // Tasks context if asking about tasks
+  if (topics.includes('tasks')) {
+    try {
+      const pending = brain.listTasks({ status: 'pending', limit: 5 });
+      if (pending.length > 0) {
+        const taskSummary = pending.map(t => `- ${t.title} (${t.priority || 'normal'}, due: ${t.due_at || 'not set'})`).join('\n');
+        sections.push(`## Pending Tasks\n${taskSummary}`);
+      }
+    } catch {}
+  }
+
+  // Weather context — include location hints
+  if (topics.includes('weather')) {
+    sections.push(`## Weather\nUse web_fetch with Open-Meteo API (no key needed):
+\`https://api.open-meteo.com/v1/forecast?latitude=LAT&longitude=LON&current=temperature_2m,apparent_temperature,weather_code,wind_speed_10m,relative_humidity_2m&timezone=auto\`
+Common coords: Seattle(47.61,-122.33), London(51.51,-0.13), Helsinki(60.17,24.94), San Francisco(37.77,-122.42), Beijing(39.90,116.40)
+Weather codes: 0=clear, 1-3=partly cloudy, 45-48=fog, 51-55=drizzle, 61-65=rain, 71-77=snow, 80-82=showers, 95-99=thunderstorm
+First determine ${ownerName}'s location from calendar or recent memories, then fetch weather.`);
+  }
+
+  return sections.join('\n\n');
+}
+
+/** Reasoning and tool usage instructions — always included */
+function buildInstructionLayer(ownerName, channel) {
+  return `## How to Reason and Respond
+
+### Step 1: SEARCH — gather evidence (call ALL searches in ONE turn)
+For ANY question beyond small talk, call search_memories MULTIPLE TIMES IN THE SAME TURN.
+Example: if asked about leadership, call these ALL AT ONCE:
+- search_memories({query: "leadership coaching feedback"})
+- search_memories({query: "团队 管理 反馈", source: "slack"})
+- search_memories({query: "Danni Mengyang Zohaib"})
+
+### Step 2: THINK — reason through the evidence
+ALWAYS use the **think** tool before responding. Use it to:
+- Analyze what the evidence ACTUALLY shows vs what it SEEMS to show
+- Challenge your conclusions: do you have 3+ examples, or are you over-generalizing?
+- Consider if behavior is DELIBERATE and STRATEGIC rather than a gap
+- ${ownerName} is a director managing 60+ engineers — context matters
+
+### Step 3: RESPOND — with depth and nuance
+- Use **bold** for key names, dates, and decisions
+- Use > blockquotes when quoting actual Slack messages
+- Include dates and people: "On **2024-12-12**, you told **Zohaib**: ..."
+- **Bilingual-aware**: Translate Chinese quotes — they contain the most candid opinions
+- Present BOTH sides before drawing conclusions
+
+### Tools
+- **think**: Internal scratchpad (${ownerName} won't see). Use BEFORE every substantive response.
+- **search_memories**: Full-text search (BM25). source:"slack" for Slack only. Batch multiple searches.
+- **remember_fact**: Store facts the user teaches you.
+- **run_skill / mcp_call / list_mcp_tools**: Actions and external services.
+- **Local tools**: web_fetch, run_shell, read_file, write_file, search_files, calendar_events, calendar_create, reminder_create, notification, applescript, open_url, open_app, screenshot, system_info, clipboard_read/write
+- **Slack**: slack_search, slack_read_channel, slack_send_message, pull_slack
+- **Glean**: When using reportsto: queries, "entities" = direct reports only. Check manager.email to verify.
+- When mcp_call returns auth_required, tell the user which server needs auth.
+
+**Location awareness**: For weather/location questions, determine location from calendar or memories first.`;
+}
+
+// --- Helper functions ---
+
+/** Search knowledge triples using FTS5 or LIKE fallback */
+function searchRelevantKnowledge(query, limit) {
+  try {
+    const db = brain.getDb();
+    // Extract search terms from the user message
+    const terms = extractSearchTerms(query);
+    if (terms.length === 0) return [];
+
+    // Try matching against knowledge subject/predicate/object
+    const likeConditions = terms.map(() => '(subject LIKE ? OR predicate LIKE ? OR object LIKE ?)').join(' OR ');
+    const params = [];
+    for (const t of terms) {
+      params.push(`%${t}%`, `%${t}%`, `%${t}%`);
+    }
+
+    return db.prepare(`
+      SELECT * FROM knowledge
+      WHERE status = 'active' AND (${likeConditions})
+      ORDER BY confidence DESC
+      LIMIT ?
+    `).all(...params, limit);
+  } catch {
+    return [];
+  }
+}
+
+/** Search memories using FTS5 with LIKE fallback */
+function searchRelevantMemories(query, limit) {
+  try {
+    const db = brain.getDb();
+    const terms = extractSearchTerms(query);
+    if (terms.length === 0) return [];
+
+    // Try FTS5 first
+    const hasFts = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='memories_fts'").get();
+    if (hasFts) {
+      try {
+        const ftsQuery = terms.join(' OR ');
+        return db.prepare(`
+          SELECT m.*, bm25(memories_fts) as relevance
+          FROM memories_fts f
+          JOIN memories m ON m.rowid = f.rowid
+          WHERE memories_fts MATCH ?
+          ORDER BY bm25(memories_fts)
+          LIMIT ?
+        `).all(ftsQuery, limit);
+      } catch {}
+    }
+
+    // LIKE fallback
+    const likeConditions = terms.map(() => 'content LIKE ?').join(' OR ');
+    const params = terms.map(t => `%${t}%`);
+    return db.prepare(`
+      SELECT * FROM memories
+      WHERE (${likeConditions})
+      ORDER BY timestamp DESC
+      LIMIT ?
+    `).all(...params, limit);
+  } catch {
+    return [];
+  }
+}
+
+/** Extract meaningful search terms from a message */
+function extractSearchTerms(message) {
+  if (!message) return [];
+  // Remove common stop words, keep words 3+ chars
+  const stopWords = new Set([
+    'the', 'and', 'for', 'are', 'but', 'not', 'you', 'all', 'can', 'had', 'her',
+    'was', 'one', 'our', 'out', 'has', 'his', 'how', 'its', 'may', 'new', 'now',
+    'old', 'see', 'way', 'who', 'did', 'get', 'let', 'say', 'she', 'too', 'use',
+    'what', 'when', 'where', 'which', 'with', 'would', 'could', 'should', 'about',
+    'after', 'before', 'between', 'does', 'each', 'from', 'have', 'just', 'like',
+    'make', 'many', 'more', 'most', 'much', 'must', 'name', 'only', 'over', 'such',
+    'take', 'than', 'them', 'then', 'they', 'this', 'very', 'well', 'were', 'will',
+    'your', 'tell', 'know', 'think', 'some', 'want', 'been', 'into', 'that',
+  ]);
+
+  return message
+    .replace(/[^\w\s\u4e00-\u9fff]/g, ' ')  // Keep alphanumeric + Chinese chars
+    .split(/\s+/)
+    .filter(w => w.length >= 3 && !stopWords.has(w.toLowerCase()))
+    .slice(0, 8);  // Cap at 8 terms to avoid huge queries
+}
+
+/** Build people context — only for mentioned people */
+function buildPeopleContext(userMessage) {
+  try {
+    const people = brain.listPeople({});
+    if (people.length === 0) return null;
+
+    const lower = userMessage.toLowerCase();
+    // Find people mentioned in the message
+    const mentioned = people.filter(p =>
+      p.name && lower.includes(p.name.toLowerCase())
+    );
+
+    if (mentioned.length > 0) {
+      const details = mentioned.map(p =>
+        `- **${p.name}**: ${p.relationship || 'unknown'} (trust: ${p.trust_level || 0.5})`
+      ).join('\n');
+      return `## People Mentioned\n${details}`;
+    }
+
+    // No specific people mentioned — include top relationships summary
+    const top = people.slice(0, 10).map(p =>
+      `- ${p.name}: ${p.relationship || 'unknown'}`
+    ).join('\n');
+    return `## Key People\n${top}`;
+  } catch {
+    return null;
+  }
+}
+
+/** Build pre-computed metadata context */
+function buildMetadataContext(topics) {
+  try {
+    const getMeta = brain.getDb().prepare('SELECT value FROM brain_metadata WHERE key = ?');
+    const sections = [];
+
+    if (topics.includes('people')) {
+      const peopleMeta = getMeta.get('people_interaction_summary')?.value;
+      if (peopleMeta) sections.push(`## Relationships (by interaction)\n${peopleMeta}`);
+    }
+    if (topics.includes('work') || topics.includes('slack')) {
+      const topicMeta = getMeta.get('topic_frequency')?.value;
+      if (topicMeta) sections.push(`## Topics (by frequency)\n${topicMeta}`);
+    }
+
+    return sections.join('\n\n') || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Build MCP server context */
+function buildMcpContext() {
+  try {
+    const { loadMcpConfigs } = require('../skills/mcp-client');
+    const configs = loadMcpConfigs();
+    let toolsByServer = {};
+    try {
+      const rows = brain.getDb().prepare('SELECT server, tool_name FROM mcp_tools_cache ORDER BY server').all();
+      for (const r of rows) {
+        if (!toolsByServer[r.server]) toolsByServer[r.server] = [];
+        toolsByServer[r.server].push(r.tool_name);
+      }
+    } catch {}
+
+    return Object.entries(configs).map(([name, cfg]) => {
+      const hasAuth = cfg.oauth?.accessToken ? 'authenticated' : 'needs auth';
+      const tools = toolsByServer[name];
+      const toolStr = tools ? ` — ${tools.slice(0, 8).join(', ')}${tools.length > 8 ? ` +${tools.length - 8} more` : ''}` : '';
+      return `- ${name} [${hasAuth}]${toolStr}`;
+    }).join('\n') || null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { buildSystemPrompt, classifyTopics: classifyTopics, extractSearchTerms, buildCoreLayer, buildRelevantLayer, buildSituationalLayer, buildInstructionLayer };

package/template/wall-e/context/state-snapshot.js

@@ -0,0 +1,209 @@
+'use strict';
+
+const brain = require('../brain');
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+const execFileAsync = promisify(execFile);
+
+/**
+ * Build a compact state snapshot (~500 tokens) of Wall-E's current awareness.
+ * Resilient: returns whatever data is available, skips sections that fail.
+ */
+function buildStateSnapshot() {
+  const snapshot = {};
+  const db = brain.getDb();
+
+  // 1. Time context
+  const now = new Date();
+  snapshot.time = {
+    datetime: now.toISOString(),
+    day_of_week: now.toLocaleDateString('en-US', { weekday: 'long' }),
+    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    hour: now.getHours(),
+  };
+
+  // 2. Calendar: check for cached calendar events in the next 2 hours
+  try {
+    // Look in briefing_items for calendar-related items
+    const calItems = db.prepare(
+      "SELECT title, context, urgency FROM briefing_items WHERE (skill = 'google-calendar' OR category = 'calendar') AND status NOT IN ('done', 'dismissed') ORDER BY urgency DESC, last_seen DESC LIMIT 5"
+    ).all();
+    if (calItems.length > 0) {
+      snapshot.calendar = calItems.map(c => ({
+        title: c.title,
+        context: c.context ? c.context.slice(0, 200) : null,
+        urgency: c.urgency,
+      }));
+    }
+  } catch (_) {
+    // Calendar data unavailable -- skip
+  }
+
+  // 3. Recent memories: last 5 high-importance memories from today
+  try {
+    const todayStart = now.toISOString().slice(0, 10) + 'T00:00:00.000Z';
+    const recentMemories = db.prepare(
+      "SELECT id, source, content, importance, timestamp FROM memories WHERE timestamp >= ? ORDER BY importance DESC, timestamp DESC LIMIT 5"
+    ).all(todayStart);
+    if (recentMemories.length > 0) {
+      snapshot.recent_memories = recentMemories.map(m => ({
+        id: m.id,
+        source: m.source,
+        summary: m.content ? m.content.slice(0, 150) : '',
+        importance: m.importance,
+      }));
+    }
+  } catch (_) {}
+
+  // 4. Pending tasks: tasks due in next 2 hours
+  try {
+    const twoHoursFromNow = new Date(now.getTime() + 2 * 60 * 60 * 1000).toISOString();
+    const dueTasks = db.prepare(
+      "SELECT id, title, priority, due_at FROM tasks WHERE status IN ('pending', 'active') AND due_at IS NOT NULL AND due_at <= ? ORDER BY due_at ASC LIMIT 5"
+    ).all(twoHoursFromNow);
+    if (dueTasks.length > 0) {
+      snapshot.pending_tasks = dueTasks.map(t => ({
+        id: t.id,
+        title: t.title,
+        priority: t.priority,
+        due_at: t.due_at,
+      }));
+    }
+  } catch (_) {}
+
+  // 5. Pending questions: unresolved questions (limit 3)
+  try {
+    const questions = db.prepare(
+      "SELECT id, question, priority FROM pending_questions WHERE status = 'pending' ORDER BY CASE WHEN priority = 'high' THEN 0 WHEN priority = 'normal' THEN 1 ELSE 2 END, created_at DESC LIMIT 3"
+    ).all();
+    if (questions.length > 0) {
+      snapshot.pending_questions = questions.map(q => ({
+        id: q.id,
+        question: q.question.slice(0, 200),
+        priority: q.priority,
+      }));
+    }
+  } catch (_) {}
+
+  // 6. Recent decisions: last 5 initiative_log entries (to avoid repeating)
+  try {
+    const recentDecisions = db.prepare(
+      "SELECT decision, decision_data, reasoning, created_at FROM initiative_log ORDER BY created_at DESC LIMIT 5"
+    ).all();
+    if (recentDecisions.length > 0) {
+      snapshot.recent_decisions = recentDecisions.map(d => ({
+        decision: d.decision,
+        data: d.decision_data ? d.decision_data.slice(0, 200) : null,
+        reasoning: d.reasoning ? d.reasoning.slice(0, 150) : null,
+        at: d.created_at,
+      }));
+    }
+  } catch (_) {}
+
+  // 7. Knowledge gaps: domains with low confidence (tier 1-2)
+  try {
+    const gaps = db.prepare(
+      "SELECT domain, current_tier, confidence FROM domain_confidence WHERE current_tier <= 2 ORDER BY confidence ASC LIMIT 5"
+    ).all();
+    if (gaps.length > 0) {
+      snapshot.knowledge_gaps = gaps.map(g => ({
+        domain: g.domain,
+        tier: g.current_tier,
+        confidence: g.confidence,
+      }));
+    }
+  } catch (_) {}
+
+  // 8. Briefing items: urgent/today items
+  try {
+    const briefing = db.prepare(
+      "SELECT title, category, urgency, context FROM briefing_items WHERE status NOT IN ('done', 'dismissed') AND (urgency IN ('high', 'critical') OR last_seen >= date('now')) ORDER BY CASE WHEN urgency = 'critical' THEN 0 WHEN urgency = 'high' THEN 1 ELSE 2 END LIMIT 5"
+    ).all();
+    if (briefing.length > 0) {
+      snapshot.briefing_items = briefing.map(b => ({
+        title: b.title,
+        category: b.category,
+        urgency: b.urgency,
+      }));
+    }
+  } catch (_) {}
+
+  return snapshot;
+}
+
+/**
+ * Check if the snapshot contains no actionable data.
+ */
+function isStateEmpty(snapshot) {
+  const keys = Object.keys(snapshot).filter(k => k !== 'time');
+  if (keys.length === 0) return true;
+  // Check if all data arrays are empty
+  return keys.every(k => {
+    const val = snapshot[k];
+    return Array.isArray(val) ? val.length === 0 : !val;
+  });
+}
+
+/**
+ * Format the snapshot as human-readable text for the initiative prompt.
+ */
+function formatSnapshot(snapshot) {
+  const lines = [];
+
+  if (snapshot.time) {
+    lines.push(`TIME: ${snapshot.time.day_of_week} ${snapshot.time.datetime} (${snapshot.time.timezone})`);
+  }
+
+  if (snapshot.calendar && snapshot.calendar.length > 0) {
+    lines.push('\nCALENDAR (next 2 hours):');
+    for (const c of snapshot.calendar) {
+      lines.push(`  - [${c.urgency}] ${c.title}`);
+    }
+  }
+
+  if (snapshot.recent_memories && snapshot.recent_memories.length > 0) {
+    lines.push('\nRECENT MEMORIES (today):');
+    for (const m of snapshot.recent_memories) {
+      lines.push(`  - [${m.source}, importance=${m.importance}] ${m.summary}`);
+    }
+  }
+
+  if (snapshot.pending_tasks && snapshot.pending_tasks.length > 0) {
+    lines.push('\nPENDING TASKS (due soon):');
+    for (const t of snapshot.pending_tasks) {
+      lines.push(`  - [${t.priority}] ${t.title} (due: ${t.due_at})`);
+    }
+  }
+
+  if (snapshot.pending_questions && snapshot.pending_questions.length > 0) {
+    lines.push('\nPENDING QUESTIONS:');
+    for (const q of snapshot.pending_questions) {
+      lines.push(`  - [${q.priority}] ${q.question}`);
+    }
+  }
+
+  if (snapshot.recent_decisions && snapshot.recent_decisions.length > 0) {
+    lines.push('\nRECENT INITIATIVE DECISIONS:');
+    for (const d of snapshot.recent_decisions) {
+      lines.push(`  - ${d.decision}: ${d.reasoning || '(no reason)'} (${d.at})`);
+    }
+  }
+
+  if (snapshot.knowledge_gaps && snapshot.knowledge_gaps.length > 0) {
+    lines.push('\nKNOWLEDGE GAPS (low confidence):');
+    for (const g of snapshot.knowledge_gaps) {
+      lines.push(`  - ${g.domain}: tier ${g.tier}, confidence ${g.confidence}`);
+    }
+  }
+
+  if (snapshot.briefing_items && snapshot.briefing_items.length > 0) {
+    lines.push('\nBRIEFING ITEMS (urgent/today):');
+    for (const b of snapshot.briefing_items) {
+      lines.push(`  - [${b.urgency}] ${b.title} (${b.category || 'general'})`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = { buildStateSnapshot, isStateEmpty, formatSnapshot };

package/template/wall-e/context/token-counter.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * Fast token estimation utilities for context compaction.
+ * Uses chars/4 with a 1.2x safety margin (overestimates slightly — safer than underestimating).
+ */
+
+const CHARS_PER_TOKEN = 4;
+const SAFETY_MARGIN = 1.2;
+
+/**
+ * Estimate token count for a string.
+ * @param {string} text
+ * @returns {number}
+ */
+function estimateTokens(text) {
+  if (!text) return 0;
+  return Math.ceil((text.length / CHARS_PER_TOKEN) * SAFETY_MARGIN);
+}
+
+/**
+ * Estimate total tokens across an array of messages.
+ * Handles both string content and structured content blocks (tool_use, tool_result, etc.).
+ * @param {Array} messages - Array of { role, content } objects
+ * @returns {number}
+ */
+function estimateMessagesTokens(messages) {
+  if (!messages || !Array.isArray(messages)) return 0;
+  let total = 0;
+  for (const msg of messages) {
+    if (!msg) continue;
+    if (typeof msg.content === 'string') {
+      total += estimateTokens(msg.content);
+    } else if (Array.isArray(msg.content)) {
+      // Structured content: tool_use blocks, tool_result blocks, text blocks, etc.
+      for (const block of msg.content) {
+        if (block.type === 'text') {
+          total += estimateTokens(block.text || '');
+        } else if (block.type === 'tool_use') {
+          total += estimateTokens(JSON.stringify(block.input || {}));
+          total += estimateTokens(block.name || '');
+        } else if (block.type === 'tool_result') {
+          total += estimateTokens(typeof block.content === 'string' ? block.content : JSON.stringify(block.content || ''));
+        } else {
+          total += estimateTokens(JSON.stringify(block));
+        }
+      }
+    }
+    // Add small overhead per message for role, etc.
+    total += 4;
+  }
+  return total;
+}
+
+module.exports = { estimateTokens, estimateMessagesTokens };