ei-tui 0.1.16 → 0.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ei-tui",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "author": "Flare576",
   "repository": {
     "type": "git",

package/src/cli/retrieval.ts

@@ -1,4 +1,5 @@
 import type { StorageState, Quote, Fact, Trait, Person, Topic } from "../core/types";
+import { decodeAllEmbeddings } from "../storage/embeddings";
 import { crossFind } from "../core/utils/index.ts";
 import { join } from "path";
 import { readFile } from "fs/promises";
@@ -21,7 +22,7 @@ export async function loadLatestState(): Promise<StorageState | null> {
   for (const file of [STATE_FILE, BACKUP_FILE]) {
     try {
       const text = await readFile(join(dataPath, file), "utf-8");
-      if (text) return JSON.parse(text) as StorageState;
+      if (text) return decodeAllEmbeddings(JSON.parse(text) as StorageState);
     } catch {
       continue;
     }

package/src/core/embedding-service.ts

@@ -201,8 +201,17 @@ function createBunService(): EmbeddingService {
     if (embedderPromise) return embedderPromise;
     
     embedderPromise = (async () => {
-      const mod = await import(/* @vite-ignore */ FASTEMBED_MODULE);
-      embedder = await mod.FlagEmbedding.init({ model: mod.EmbeddingModel.AllMiniLML6V2 });
+      const [mod, os, path] = await Promise.all([
+        import(/* @vite-ignore */ FASTEMBED_MODULE),
+        import('os'),
+        import('path'),
+      ]);
+      // Use EI_DATA_PATH if set, otherwise fall back to ~/.local/share/ei/embeddings.
+      // Must be absolute so the cache is stable regardless of cwd.
+      const cacheDir = process.env.EI_DATA_PATH
+        ? path.join(process.env.EI_DATA_PATH, 'embeddings')
+        : path.join(os.homedir(), '.local', 'share', 'ei', 'embeddings');
+      embedder = await mod.FlagEmbedding.init({ model: mod.EmbeddingModel.AllMiniLML6V2, cacheDir });
       return embedder;
     })();
     

package/src/core/handlers/index.ts

@@ -1117,6 +1117,17 @@ function handlePersonaTopicUpdate(response: LLMResponse, state: StateManager): v
 
 
 
+/**
+ * handleToolSynthesis — second LLM call in the tool flow.
+ * The QueueProcessor already injected tool history into messages and got the
+ * final persona response. Parse and store it exactly like handlePersonaResponse.
+ */
+function handleToolSynthesis(response: LLMResponse, state: StateManager): void {
+  console.log(`[handleToolSynthesis] Routing to handlePersonaResponse`);
+  handlePersonaResponse(response, state);
+}
+
+
 export const handlers: Record<LLMNextStep, ResponseHandler> = {
   handlePersonaResponse,
   handlePersonaGeneration,
@@ -1137,4 +1148,5 @@ export const handlers: Record<LLMNextStep, ResponseHandler> = {
   handlePersonaExpire,
   handlePersonaExplore,
   handleDescriptionCheck,
+  handleToolSynthesis,
 };

package/src/core/llm-client.ts

@@ -17,11 +17,17 @@ export interface ResolvedModel {
 export interface LLMCallOptions {
   signal?: AbortSignal;
   temperature?: number;
+  /** OpenAI-compatible tools array. When present and non-empty, sent with tool_choice: "auto". */
+  tools?: Record<string, unknown>[];
 }
 
 export interface LLMRawResponse {
   content: string | null;
   finishReason: string | null;
+  /** Raw tool_calls array from the API response, present when finishReason is "tool_calls". */
+  rawToolCalls?: unknown[];
+  /** The full assistant message object (needed to inject into history for the tool loop). */
+  assistantMessage?: Record<string, unknown>;
 }
 
 let llmCallCount = 0;
@@ -170,14 +176,21 @@ export async function callLLMRaw(
     headers["anthropic-dangerous-direct-browser-access"] = "true";
   }
   
+  const requestBody: Record<string, unknown> = {
+    model,
+    messages: finalMessages,
+    temperature,
+  };
+
+  if (options.tools && options.tools.length > 0) {
+    requestBody.tools = options.tools;
+    requestBody.tool_choice = "auto";
+  }
+
   const response = await fetch(`${normalizedBaseURL}/chat/completions`, {
     method: "POST",
     headers,
-    body: JSON.stringify({
-      model,
-      messages: finalMessages,
-      temperature,
-    }),
+    body: JSON.stringify(requestBody),
     signal,
   });
   
@@ -189,9 +202,16 @@ export async function callLLMRaw(
   const data = await response.json();
   const choice = data.choices?.[0];
   
+  const assistantMessage = choice?.message as Record<string, unknown> | undefined;
+  const rawToolCalls = Array.isArray(choice?.message?.tool_calls)
+    ? (choice.message.tool_calls as unknown[])
+    : undefined;
+
   return {
-    content: choice?.message?.content ?? null,
+    content: (choice?.message?.content as string | null) ?? null,
     finishReason: choice?.finish_reason ?? null,
+    rawToolCalls,
+    assistantMessage,
   };
 }
 

package/src/core/orchestrators/human-extraction.ts

@@ -281,11 +281,14 @@ export async function queueItemMatch(
       break;
   }
 
+  // Traits are personality patterns — they must only match against other traits.
+  // Non-trait candidates (facts, topics, people) must never absorb trait content,
+  // and trait candidates must never cross-match into facts/topics/people.
   const allItemsWithEmbeddings = [
-    ...human.facts.map(f => ({ ...f, data_type: "fact" as DataItemType })),
+    ...(dataType !== "trait" ? human.facts.map(f => ({ ...f, data_type: "fact" as DataItemType })) : []),
     ...human.traits.map(t => ({ ...t, data_type: "trait" as DataItemType })),
-    ...human.topics.map(t => ({ ...t, data_type: "topic" as DataItemType })),
-    ...human.people.map(p => ({ ...p, data_type: "person" as DataItemType })),
+    ...(dataType !== "trait" ? human.topics.map(t => ({ ...t, data_type: "topic" as DataItemType })) : []),
+    ...(dataType !== "trait" ? human.people.map(p => ({ ...p, data_type: "person" as DataItemType })) : []),
   ].filter(item => item.embedding && item.embedding.length > 0);
 
   let topKItems: Array<{
@@ -321,15 +324,18 @@ export async function queueItemMatch(
   }
 
   if (topKItems.length === 0) {
-    console.log(`[queueItemMatch] No embeddings available, using all ${human.facts.length + human.traits.length + human.topics.length + human.people.length} items`);
-    
-    for (const fact of human.facts) {
-      topKItems.push({
-        data_type: "fact",
-        data_id: fact.id,
-        data_name: fact.name,
-        data_description: dataType === "fact" ? fact.description : truncateDescription(fact.description),
-      });
+
+    console.log(`[queueItemMatch] No embeddings available, using filtered items (dataType=${dataType})`);
+
+    if (dataType !== "trait") {
+      for (const fact of human.facts) {
+        topKItems.push({
+          data_type: "fact",
+          data_id: fact.id,
+          data_name: fact.name,
+          data_description: dataType === "fact" ? fact.description : truncateDescription(fact.description),
+        });
+      }
     }
 
     for (const trait of human.traits) {
@@ -341,22 +347,24 @@ export async function queueItemMatch(
       });
     }
 
-    for (const topic of human.topics) {
-      topKItems.push({
-        data_type: "topic",
-        data_id: topic.id,
-        data_name: topic.name,
-        data_description: dataType === "topic" ? topic.description : truncateDescription(topic.description),
-      });
-    }
-
-    for (const person of human.people) {
-      topKItems.push({
-        data_type: "person",
-        data_id: person.id,
-        data_name: person.name,
-        data_description: dataType === "person" ? person.description : truncateDescription(person.description),
-      });
+    if (dataType !== "trait") {
+      for (const topic of human.topics) {
+        topKItems.push({
+          data_type: "topic",
+          data_id: topic.id,
+          data_name: topic.name,
+          data_description: dataType === "topic" ? topic.description : truncateDescription(topic.description),
+        });
+      }
+
+      for (const person of human.people) {
+        topKItems.push({
+          data_type: "person",
+          data_id: person.id,
+          data_name: person.name,
+          data_description: dataType === "person" ? person.description : truncateDescription(person.description),
+        });
+      }
     }
   }
 

package/src/core/processor.ts

@@ -25,6 +25,8 @@ import {
   type StorageState,
   type StateConflictResolution,
   type StateConflictData,
+  type ToolDefinition,
+  type ToolProvider,
 } from "./types.js";
 import type { Storage } from "../storage/interface.js";
 import { remoteSync } from "../storage/remote.js";
@@ -57,6 +59,8 @@ import { EI_WELCOME_MESSAGE, EI_PERSONA_DEFINITION } from "../templates/welcome.
 import { getEmbeddingService, findTopK, needsEmbeddingUpdate, needsQuoteEmbeddingUpdate, computeDataItemEmbedding, computeQuoteEmbedding } from "./embedding-service.js";
 import { ContextStatus as ContextStatusEnum } from "./types.js";
 import { buildChatMessageContent } from "../prompts/message-utils.js";
+import { registerReadMemoryExecutor, registerFileReadExecutor } from "./tools/index.js";
+import { createReadMemoryExecutor } from "./tools/builtin/read-memory.js";
 
 // =============================================================================
 // EMBEDDING STRIPPING - Remove embeddings from data items before returning to FE
@@ -208,6 +212,14 @@ export class Processor {
     if (!this.stateManager.hasExistingData() || this.stateManager.persona_getAll().length === 0) {
       await this.bootstrapFirstRun();
     }
+    // Seed built-in tool providers and tools if absent
+    this.bootstrapTools();
+    // Register read_memory executor (injected to avoid circular deps)
+    registerReadMemoryExecutor(createReadMemoryExecutor(this.searchHumanData.bind(this)));
+    // file_read is Node-only — dynamic import to keep node:fs/promises out of the web bundle
+    if (this.isTUI) {
+      registerFileReadExecutor();
+    }
     this.running = true;
     console.log(`[Processor ${this.instanceId}] initialized, starting loop`);
     this.runLoop();
@@ -251,6 +263,145 @@ export class Processor {
     this.interface.onMessageAdded?.(eiEntity.id);
   }
 
+  /**
+   * Seed built-in tool providers and tools if they don't exist yet.
+   * Called on every startup (after state load/restore) — safe to call repeatedly.
+   * New builtins added in future releases will be seeded automatically.
+   */
+  private bootstrapTools(): void {
+    const now = new Date().toISOString();
+
+    // --- Ei built-in provider ---
+    if (!this.stateManager.tools_getProviderById("ei")) {
+      const eiProvider: ToolProvider = {
+        id: "ei",
+        name: "ei",
+        display_name: "Ei Built-ins",
+        description: "Built-in tools that ship with Ei. No external API needed.",
+        builtin: true,
+        config: {},
+        enabled: true,
+        created_at: now,
+      };
+      this.stateManager.tools_addProvider(eiProvider);
+    }
+
+    // read_memory tool
+    if (!this.stateManager.tools_getByName("read_memory")) {
+      this.stateManager.tools_add({
+        id: crypto.randomUUID(),
+        provider_id: "ei",
+        name: "read_memory",
+        display_name: "Read Memory",
+        description: "Search your personal memory for relevant facts, traits, topics, people, or quotes. Use this when you need information about the user that may not be in the current conversation.",
+        input_schema: {
+          type: "object",
+          properties: {
+            query: { type: "string", description: "What to search for in memory" },
+            types: {
+              type: "array",
+              items: { type: "string", enum: ["fact", "trait", "topic", "person", "quote"] },
+              description: "Limit search to specific memory types (default: all types)"
+            },
+            limit: { type: "number", description: "Max results to return (default: 10, max: 20)" },
+          },
+          required: ["query"],
+        },
+        runtime: "any",
+        builtin: true,
+        enabled: true,
+        created_at: now,
+        max_calls_per_interaction: 3,
+      });
+    }
+
+    // file_read tool (TUI only)
+    if (!this.stateManager.tools_getByName("file_read")) {
+      this.stateManager.tools_add({
+        id: crypto.randomUUID(),
+        provider_id: "ei",
+        name: "file_read",
+        display_name: "Read File",
+        description: "Read the contents of a file from the local filesystem. Only available in the TUI.",
+        input_schema: {
+          type: "object",
+          properties: {
+            path: { type: "string", description: "Absolute or relative path to the file" },
+          },
+          required: ["path"],
+        },
+        runtime: "node",
+        builtin: true,
+        enabled: true,
+        created_at: now,
+        max_calls_per_interaction: 5,
+      });
+    }
+
+    // --- Tavily Search provider ---
+    if (!this.stateManager.tools_getProviderById("tavily")) {
+      const tavilyProvider: ToolProvider = {
+        id: "tavily",
+        name: "tavily",
+        display_name: "Tavily Search",
+        description: "Browser-compatible web search. Requires a Tavily API key (free tier: 1000 requests/month).",
+        builtin: true,
+        config: { api_key: '' },  // user fills in their Tavily API key via Settings → Toolkits
+        enabled: false,  // disabled until user adds API key
+        created_at: now,
+      };
+      this.stateManager.tools_addProvider(tavilyProvider);
+    }
+
+    // tavily_web_search
+    if (!this.stateManager.tools_getByName("tavily_web_search")) {
+      this.stateManager.tools_add({
+        id: crypto.randomUUID(),
+        provider_id: "tavily",
+        name: "tavily_web_search",
+        display_name: "Web Search",
+        description: "Search the web using Tavily. Use for current events, fact verification, or any topic that benefits from up-to-date information.",
+        input_schema: {
+          type: "object",
+          properties: {
+            query: { type: "string", description: "Search query" },
+            max_results: { type: "number", description: "Number of results (default: 5, max: 10)" },
+          },
+          required: ["query"],
+        },
+        runtime: "any",
+        builtin: true,
+        enabled: true,
+        created_at: now,
+        max_calls_per_interaction: 3,
+      });
+    }
+
+    // tavily_news_search
+    if (!this.stateManager.tools_getByName("tavily_news_search")) {
+      this.stateManager.tools_add({
+        id: crypto.randomUUID(),
+        provider_id: "tavily",
+        name: "tavily_news_search",
+        display_name: "News Search",
+        description: "Search recent news articles using Tavily. Use for current events and recent developments.",
+        input_schema: {
+          type: "object",
+          properties: {
+            query: { type: "string", description: "News search query" },
+            max_results: { type: "number", description: "Number of results (default: 5, max: 10)" },
+          },
+          required: ["query"],
+        },
+        runtime: "any",
+        builtin: true,
+        enabled: true,
+        created_at: now,
+        max_calls_per_interaction: 3,
+      });
+    }
+  }
+
   async stop(): Promise<void> {
     console.log(`[Processor ${this.instanceId}] stop() called, running=${this.running}, stopped=${this.stopped}`);
     this.stopped = true;
@@ -292,11 +443,14 @@ export class Processor {
       const result = await remoteSync.sync(state);
       
       if (!result.success) {
-        // Push failed — likely 412 etag mismatch or network error
-        // Do NOT moveToBackup — leave state.json intact
-        // Next boot will detect primary + remote → conflict resolution
+        // Sync failed (e.g. 429, network error, 412 etag mismatch).
+        // Do NOT stop() — leave the processor loop running so the user can
+        // keep using the TUI and retry /quit later.
+        // Do NOT moveToBackup — leave state.json intact so next boot can
+        // detect primary + remote → conflict resolution if needed.
         console.log(`[Processor ${this.instanceId}] Remote sync failed: ${result.error}`);
-        await this.stop();
+        // Reset the import abort controller so imports can resume normally.
+        this.importAbortController = new AbortController();
         this.interface.onSaveAndExitFinish?.();
         return { success: false, error: result.error };
       }
@@ -365,6 +519,17 @@ export class Processor {
               this.interface.onMessageProcessing?.(personaId);
             }
 
+            const toolNextSteps = new Set([
+              LLMNextStep.HandlePersonaResponse,
+              LLMNextStep.HandleHeartbeatCheck,
+              LLMNextStep.HandleEiHeartbeat,
+            ]);
+            const toolPersonaId = personaId ?? (request.next_step === LLMNextStep.HandleEiHeartbeat ? "ei" : undefined);
+            const tools = (toolNextSteps.has(request.next_step) && toolPersonaId)
+              ? this.stateManager.tools_getForPersona(toolPersonaId, this.isTUI)
+              : [];
+            console.log(`[Tools] Dispatch for ${request.next_step} persona=${toolPersonaId ?? "none"}: ${tools.length} tool(s) attached`);
+
             this.queueProcessor.start(request, async (response) => {
               this.currentRequest = null;
               await this.handleResponse(response);
@@ -375,6 +540,8 @@ export class Processor {
               accounts: this.stateManager.getHuman().settings?.accounts,
               messageFetcher: (pName) => this.fetchMessagesForLLM(pName),
               rawMessageFetcher: (pName) => this.stateManager.messages_get(pName),
+              tools: tools.length > 0 ? tools : undefined,
+              onEnqueue: (req) => this.stateManager.queue_enqueue(req),
             });
 
             this.interface.onQueueStateChanged?.("busy");
@@ -430,7 +597,13 @@ export class Processor {
         const timeSinceHeartbeat = now - lastHeartbeat;
 
         if (timeSinceHeartbeat >= heartbeatDelay) {
-          this.queueHeartbeatCheck(persona.id);
+          const history = this.stateManager.messages_get(persona.id);
+          const contextWindowHours = persona.context_window_hours ?? DEFAULT_CONTEXT_WINDOW_HOURS;
+          const contextHistory = filterMessagesForContext(history, persona.context_boundary, contextWindowHours);
+          const trailing = this.countTrailingPersonaMessages(contextHistory);
+          if (trailing < 3) {
+            this.queueHeartbeatCheck(persona.id);
+          }
         }
       }
     }
@@ -514,7 +687,7 @@ export class Processor {
         if (result.sessionsProcessed > 0) {
           console.log(
             `[Processor] OpenCode sync complete: ${result.sessionsProcessed} sessions, ` +
-            `${result.topicsCreated} topics created, ${result.messagesImported} messages imported, ` +
+            `${result.messagesImported} messages imported, ` +
             `${result.extractionScansQueued} extraction scans queued`
           );
         }
@@ -621,14 +794,32 @@ export class Processor {
       }, []);
   }
 
+  /**
+   * Count consecutive conversational messages the persona sent at the end of history
+   * without a human reply. Used to prevent heartbeat spam when the user is away.
+   */
+  private countTrailingPersonaMessages(history: Message[]): number {
+    let count = 0;
+    for (let i = history.length - 1; i >= 0; i--) {
+      const msg = history[i];
+      if (msg.role === 'human') break;
+      if (msg.role === 'system' && msg.verbal_response && msg.silence_reason === undefined) {
+        count++;
+      }
+    }
+    return count;
+  }
+
   private async queueHeartbeatCheck(personaId: string): Promise<void> {
     const persona = this.stateManager.persona_getById(personaId);
     if (!persona) return;
     this.stateManager.persona_update(personaId, { last_heartbeat: new Date().toISOString() });
     const human = this.stateManager.getHuman();
     const history = this.stateManager.messages_get(personaId);
+    const contextWindowHours = persona.context_window_hours ?? DEFAULT_CONTEXT_WINDOW_HOURS;
+    const contextHistory = filterMessagesForContext(history, persona.context_boundary, contextWindowHours);
     if (personaId === "ei") {
-      await this.queueEiHeartbeat(human, history);
+      await this.queueEiHeartbeat(human, contextHistory);
       return;
     }
 
@@ -648,7 +839,7 @@ export class Processor {
         topics: sortByEngagementGap(filteredHuman.topics).slice(0, 5),
         people: sortByEngagementGap(filteredHuman.people).slice(0, 5),
       },
-      recent_history: history.slice(-10),
+      recent_history: contextHistory.slice(-10),
       inactive_days: inactiveDays,
     };
 
@@ -813,6 +1004,14 @@ export class Processor {
       return;
     }
 
+    // Tool-phase complete: tools were executed and HandleToolSynthesis was enqueued.
+    // The persona message will arrive when synthesis completes — nothing to handle here.
+    if (response.finish_reason === "tool_calls_enqueued") {
+      console.log(`[Processor] tool_calls_enqueued for ${response.request.next_step} — awaiting HandleToolSynthesis`);
+      this.stateManager.queue_complete(response.request.id);
+      return;
+    }
+
     const handler = handlers[response.request.next_step as LLMNextStep];
     if (!handler) {
       const errorMsg = `No handler for ${response.request.next_step}`;
@@ -828,7 +1027,10 @@ export class Processor {
       await handler(response, this.stateManager);
       this.stateManager.queue_complete(response.request.id);
 
-      if (response.request.next_step === LLMNextStep.HandlePersonaResponse) {
+      if (
+        response.request.next_step === LLMNextStep.HandlePersonaResponse ||
+        response.request.next_step === LLMNextStep.HandleToolSynthesis
+      ) {
         // Always notify FE - even without content, user's message was "read" by the persona
         const personaId = response.request.data.personaId as string;
         if (personaId) {
@@ -956,6 +1158,7 @@ export class Processor {
       groups_visible: input.groups_visible ?? [DEFAULT_GROUP],
       traits: [],
       topics: [],
+      tools: input.tools && input.tools.length > 0 ? input.tools : undefined,
       is_paused: false,
       is_archived: false,
       is_static: false,
@@ -1652,6 +1855,94 @@ export class Processor {
     });
   }
 
+  // ============================================================================
+  // TOOL PROVIDER API
+  // ============================================================================
+
+  getToolProviderList(): ToolProvider[] {
+    return this.stateManager.tools_getProviders();
+  }
+
+  getToolProvider(id: string): ToolProvider | null {
+    return this.stateManager.tools_getProviderById(id);
+  }
+
+  async addToolProvider(provider: Omit<ToolProvider, 'id' | 'created_at'>): Promise<string> {
+    const id = crypto.randomUUID();
+    const now = new Date().toISOString();
+    const newProvider: ToolProvider = { ...provider, id, created_at: now };
+    this.stateManager.tools_addProvider(newProvider);
+    this.interface.onToolProviderAdded?.();
+    return id;
+  }
+
+  async updateToolProvider(id: string, updates: Partial<Omit<ToolProvider, 'id' | 'created_at'>>): Promise<boolean> {
+    const result = this.stateManager.tools_updateProvider(id, updates);
+    if (result) this.interface.onToolProviderUpdated?.(id);
+    return result;
+  }
+
+  async removeToolProvider(id: string): Promise<boolean> {
+    // Cascade: unassign all tools from this provider from all personas before removing
+    const providerTools = this.stateManager.tools_getAll().filter(t => t.provider_id === id);
+    const providerToolIds = new Set(providerTools.map(t => t.id));
+    if (providerToolIds.size > 0) {
+      const personas = this.stateManager.persona_getAll();
+      for (const persona of personas) {
+        if (persona.tools?.some(tid => providerToolIds.has(tid))) {
+          await this.stateManager.persona_update(persona.id, {
+            tools: persona.tools.filter(tid => !providerToolIds.has(tid)),
+          });
+        }
+      }
+    }
+    const result = this.stateManager.tools_removeProvider(id);
+    if (result) this.interface.onToolProviderRemoved?.();
+    return result;
+  }
+
+  // ============================================================================
+  // TOOL API
+  // ============================================================================
+
+  getToolList(): ToolDefinition[] {
+    return this.stateManager.tools_getAll();
+  }
+
+  getTool(id: string): ToolDefinition | null {
+    return this.stateManager.tools_getById(id);
+  }
+
+  async addTool(tool: Omit<ToolDefinition, 'id' | 'created_at'>): Promise<string> {
+    const id = crypto.randomUUID();
+    const now = new Date().toISOString();
+    const newTool: ToolDefinition = { ...tool, id, created_at: now };
+    this.stateManager.tools_add(newTool);
+    this.interface.onToolAdded?.();
+    return id;
+  }
+
+  async updateTool(id: string, updates: Partial<Omit<ToolDefinition, 'id' | 'created_at'>>): Promise<boolean> {
+    const result = this.stateManager.tools_update(id, updates);
+    if (result) this.interface.onToolUpdated?.(id);
+    return result;
+  }
+
+  async removeTool(id: string): Promise<boolean> {
+    // Remove this tool from all persona tool lists before deleting
+    const personas = this.stateManager.persona_getAll();
+    for (const persona of personas) {
+      if (persona.tools?.includes(id)) {
+        await this.stateManager.persona_update(persona.id, {
+          tools: persona.tools.filter(t => t !== id),
+        });
+      }
+    }
+    const result = this.stateManager.tools_remove(id);
+    if (result) this.interface.onToolRemoved?.();
+    return result;
+  }
+
   // ============================================================================
   // DEBUG / TESTING UTILITIES
   // ============================================================================