@tenex-chat/backend 0.9.1

package/src/services/storage/PrefixKVStore.ts

@@ -0,0 +1,242 @@
+/**
+ * PrefixKVStore - Centralized prefix-to-full-ID lookup store
+ *
+ * Provides O(1) lookups of event IDs and pubkeys by their 12-character hex prefix.
+ * Uses LMDB for fast, persistent storage.
+ *
+ * Storage location: ~/.tenex/data/prefix-kv/
+ *
+ * Key format: 12-char prefix -> 64-char full ID
+ * Collision policy: First write wins (collisions are statistically irrelevant)
+ *
+ * LIFECYCLE: This store is GLOBAL across all projects and uses reference counting.
+ * - Each call to initialize() increments the reference count
+ * - Each call to close() decrements the reference count (does NOT close the DB)
+ * - The DB remains open as long as at least one reference exists
+ * - Use forceClose() only during full daemon shutdown to actually close the DB
+ *
+ * Per-project runtimes SHOULD call:
+ * - initialize() during startup (increments refcount)
+ * - close() during shutdown (decrements refcount, keeps DB open for other runtimes)
+ *
+ * Migration scripts SHOULD call:
+ * - initialize() at start
+ * - forceClose() at end (since they run standalone, not within the daemon)
+ *
+ * CONCURRENCY NOTE: The first-write-wins policy uses check-then-put which is
+ * not strictly atomic under concurrent writers. In practice, this is acceptable
+ * because prefix collisions are extremely rare (1 in 2^48 for random IDs), and
+ * the worst case is that a later ID wins over an earlier one for the same prefix.
+ */
+
+import { open, type RootDatabase } from "lmdb";
+import { join } from "node:path";
+import { getTenexBasePath } from "@/constants";
+import { logger } from "@/utils/logger";
+
+const PREFIX_LENGTH = 12;
+const FULL_ID_LENGTH = 64;
+
+export class PrefixKVStore {
+    private static instance: PrefixKVStore | null = null;
+    private db: RootDatabase<string, string> | null = null;
+    private initialized = false;
+    private initializationPromise: Promise<void> | null = null;
+    private referenceCount = 0;
+
+    private constructor() {}
+
+    static getInstance(): PrefixKVStore {
+        if (!PrefixKVStore.instance) {
+            PrefixKVStore.instance = new PrefixKVStore();
+        }
+        return PrefixKVStore.instance;
+    }
+
+    /**
+     * Initialize the LMDB store.
+     * Thread-safe: concurrent calls share a single initialization.
+     * Must be called before any operations.
+     */
+    async initialize(): Promise<void> {
+        // Fast path: already initialized
+        if (this.initialized) {
+            this.referenceCount++;
+            return;
+        }
+
+        // Concurrency guard: if initialization is in progress, wait for it
+        if (this.initializationPromise) {
+            await this.initializationPromise;
+            this.referenceCount++;
+            return;
+        }
+
+        // Start initialization
+        this.initializationPromise = this.doInitialize();
+
+        try {
+            await this.initializationPromise;
+            this.referenceCount++;
+        } finally {
+            // Clear the promise after completion (success or failure)
+            this.initializationPromise = null;
+        }
+    }
+
+    /**
+     * Internal initialization logic.
+     */
+    private async doInitialize(): Promise<void> {
+        const dataPath = join(getTenexBasePath(), "data", "prefix-kv");
+
+        try {
+            this.db = open<string, string>({
+                path: dataPath,
+                compression: false,
+                encoding: "string",
+            });
+            this.initialized = true;
+            logger.debug(`[PrefixKVStore] Initialized at ${dataPath}`);
+        } catch (error) {
+            logger.error("[PrefixKVStore] Failed to initialize LMDB", {
+                error: error instanceof Error ? error.message : String(error),
+                path: dataPath,
+            });
+            throw error;
+        }
+    }
+
+    /**
+     * Add an ID (event ID or pubkey) to the store.
+     * Extracts the 12-char prefix and stores the mapping.
+     * First write wins - if prefix already exists, this is a no-op.
+     */
+    async add(fullId: string): Promise<void> {
+        if (!this.db) {
+            throw new Error("[PrefixKVStore] Not initialized. Call initialize() first.");
+        }
+
+        if (!fullId || fullId.length !== FULL_ID_LENGTH) {
+            return; // Silently ignore invalid IDs
+        }
+
+        const prefix = fullId.substring(0, PREFIX_LENGTH);
+
+        // First write wins - only add if not exists
+        const existing = this.db.get(prefix);
+        if (existing) {
+            return;
+        }
+
+        await this.db.put(prefix, fullId);
+    }
+
+    /**
+     * Add multiple IDs in a batch operation.
+     * More efficient than calling add() multiple times.
+     */
+    async addBatch(fullIds: string[]): Promise<void> {
+        const db = this.db;
+        if (!db) {
+            throw new Error("[PrefixKVStore] Not initialized. Call initialize() first.");
+        }
+
+        const validIds = fullIds.filter((id) => id && id.length === FULL_ID_LENGTH);
+        if (validIds.length === 0) return;
+
+        await db.batch(() => {
+            for (const fullId of validIds) {
+                const prefix = fullId.substring(0, PREFIX_LENGTH);
+                const existing = db.get(prefix);
+                if (!existing) {
+                    db.put(prefix, fullId);
+                }
+            }
+        });
+    }
+
+    /**
+     * Look up a full ID by its prefix.
+     * Returns the full 64-char ID or null if not found.
+     *
+     * @param prefix - Must be exactly 12 hex characters. Returns null otherwise.
+     */
+    lookup(prefix: string): string | null {
+        if (!this.db) {
+            throw new Error("[PrefixKVStore] Not initialized. Call initialize() first.");
+        }
+
+        // Require exactly 12 characters - no padding or truncation
+        // This prevents confusing behavior where short prefixes would
+        // be zero-padded and almost never match anything
+        if (!prefix || prefix.length !== PREFIX_LENGTH) {
+            return null;
+        }
+
+        const result = this.db.get(prefix);
+        return result ?? null;
+    }
+
+    /**
+     * Check if a prefix exists in the store.
+     */
+    has(prefix: string): boolean {
+        return this.lookup(prefix) !== null;
+    }
+
+    /**
+     * Get statistics about the store.
+     */
+    async getStats(): Promise<{ count: number }> {
+        if (!this.db) {
+            throw new Error("[PrefixKVStore] Not initialized. Call initialize() first.");
+        }
+
+        let count = 0;
+        for (const _entry of this.db.getRange()) {
+            count++;
+        }
+
+        return { count };
+    }
+
+    /**
+     * Release a reference to the store.
+     * For per-project runtimes - decrements reference count but does NOT close the store.
+     * Use forceClose() for daemon shutdown.
+     */
+    async close(): Promise<void> {
+        if (this.referenceCount > 0) {
+            this.referenceCount--;
+            logger.debug(`[PrefixKVStore] Reference released, remaining: ${this.referenceCount}`);
+        }
+        // Note: We intentionally do NOT close the DB here.
+        // Per-project runtimes call this on stop, but the store should
+        // remain open for other active runtimes.
+    }
+
+    /**
+     * Force close the database connection.
+     * Should ONLY be called during full daemon shutdown, not per-project stop.
+     */
+    async forceClose(): Promise<void> {
+        if (this.db) {
+            await this.db.close();
+            this.db = null;
+            this.initialized = false;
+            this.referenceCount = 0;
+            logger.debug("[PrefixKVStore] Force closed");
+        }
+    }
+
+    /**
+     * Check if the store is initialized.
+     */
+    isInitialized(): boolean {
+        return this.initialized;
+    }
+}
+
+// Export singleton instance
+export const prefixKVStore = PrefixKVStore.getInstance();

package/src/services/storage/index.ts

@@ -0,0 +1 @@
+export { PrefixKVStore, prefixKVStore } from "./PrefixKVStore";

package/src/services/system-reminder/SystemReminderUtils.ts

@@ -0,0 +1,96 @@
+/**
+ * SystemReminderUtils - Utilities for wrapping and managing system reminder content
+ *
+ * This module provides shared utilities for creating consistent `<system-reminder>` XML tags
+ * that are used for behavioral nudges and context injections.
+ *
+ * The `<system-reminder>` format is used for:
+ * - Heuristic violations (todo nudge, delegation warnings, etc.)
+ * - Deferred injections (supervision messages for next turn)
+ * - Dynamic context (response context, todo state)
+ *
+ * NOT used for (these stay tool-bound):
+ * - AGENTS.md injections (remain in tool result output)
+ * - Pre-tool supervision blocks (remain in tool result)
+ */
+
+/**
+ * Wrap content in `<system-reminder>` tags.
+ *
+ * @param content - The content to wrap (can be multi-line)
+ * @returns Content wrapped in system-reminder tags
+ */
+export function wrapInSystemReminder(content: string): string {
+    if (!content || content.trim() === "") {
+        return "";
+    }
+    return `<system-reminder>\n${content.trim()}\n</system-reminder>`;
+}
+
+/**
+ * Combine multiple system reminder contents into a single wrapped block.
+ *
+ * @param contents - Array of content strings to combine
+ * @returns Single system-reminder block with all contents, or empty string if no content
+ */
+export function combineSystemReminders(contents: string[]): string {
+    const nonEmpty = contents.filter((c) => c && c.trim() !== "");
+    if (nonEmpty.length === 0) {
+        return "";
+    }
+    return wrapInSystemReminder(nonEmpty.join("\n\n"));
+}
+
+/**
+ * Append system reminder content to an existing message.
+ *
+ * NOTE: This is a simple utility that appends the reminder to the end of the
+ * existing content with double newline separation. It does NOT merge with
+ * existing system-reminder blocks. For that use case, use MessageCompiler's
+ * appendEphemeralMessagesToLastUserMessage method which handles extraction
+ * and recombination.
+ *
+ * @param existingContent - The existing message content
+ * @param reminderContent - The system reminder content to append (already wrapped or raw)
+ * @returns The combined content with reminder appended
+ */
+export function appendSystemReminderToMessage(
+    existingContent: string,
+    reminderContent: string
+): string {
+    if (!reminderContent || reminderContent.trim() === "") {
+        return existingContent;
+    }
+
+    // If reminderContent is not already wrapped, wrap it
+    const wrappedReminder = reminderContent.trim().startsWith("<system-reminder>")
+        ? reminderContent
+        : wrapInSystemReminder(reminderContent);
+
+    return `${existingContent}\n\n${wrappedReminder}`;
+}
+
+/**
+ * Check if a string contains system-reminder tags.
+ *
+ * @param content - The content to check
+ * @returns True if content contains system-reminder tags
+ */
+export function hasSystemReminder(content: string): boolean {
+    return content.includes("<system-reminder>") && content.includes("</system-reminder>");
+}
+
+/**
+ * Extract the content from within the first system-reminder tag block.
+ * Returns empty string if no valid system-reminder block found.
+ *
+ * NOTE: This only extracts the first block. For extracting all blocks,
+ * use MessageCompiler's extractAllSystemReminderContents method.
+ *
+ * @param content - The content potentially containing system-reminder tags
+ * @returns The content inside the first tags, or empty string
+ */
+export function extractSystemReminderContent(content: string): string {
+    const match = content.match(/<system-reminder>\n?([\s\S]*?)\n?<\/system-reminder>/);
+    return match ? match[1].trim() : "";
+}

package/src/services/system-reminder/index.ts

@@ -0,0 +1,7 @@
+export {
+    wrapInSystemReminder,
+    combineSystemReminders,
+    appendSystemReminderToMessage,
+    hasSystemReminder,
+    extractSystemReminderContent,
+} from "./SystemReminderUtils";

package/src/services/trust-pubkeys/TrustPubkeyService.ts

@@ -0,0 +1,325 @@
+import { config } from "@/services/ConfigService";
+import { projectContextStore } from "@/services/projects";
+import { logger } from "@/utils/logger";
+import type { Hexpubkey, NDKEvent } from "@nostr-dev-kit/ndk";
+
+/**
+ * Reason why a pubkey is trusted
+ */
+export type TrustReason = "whitelisted" | "backend" | "agent";
+
+/**
+ * Result of a trust check
+ */
+export interface TrustResult {
+    /** Whether the pubkey is trusted */
+    trusted: boolean;
+    /** Why the pubkey is trusted (only set if trusted is true) */
+    reason?: TrustReason;
+}
+
+/**
+ * TrustPubkeyService determines if a given pubkey should be heeded or ignored.
+ *
+ * A pubkey is trusted if it is:
+ * - In the whitelisted pubkeys from config
+ * - The backend's own pubkey
+ * - An agent in the system (registered in ProjectContext)
+ *
+ * Trust precedence (highest to lowest): whitelisted > backend > agent
+ */
+export class TrustPubkeyService {
+    private static instance: TrustPubkeyService;
+
+    /** Cached backend pubkey to avoid repeated async calls */
+    private cachedBackendPubkey?: Hexpubkey;
+
+    /** Cached whitelist Set for O(1) lookups */
+    private cachedWhitelistSet?: Set<Hexpubkey>;
+
+    private constructor() {}
+
+    /**
+     * Get singleton instance
+     */
+    static getInstance(): TrustPubkeyService {
+        if (!TrustPubkeyService.instance) {
+            TrustPubkeyService.instance = new TrustPubkeyService();
+        }
+        return TrustPubkeyService.instance;
+    }
+
+    /**
+     * Check if a pubkey is trusted.
+     * Returns a TrustResult with the trust status and reason.
+     *
+     * @param pubkey The pubkey to check (hex format)
+     * @returns TrustResult indicating if trusted and why
+     */
+    async isTrusted(pubkey: Hexpubkey): Promise<TrustResult> {
+        // 1. Check whitelisted pubkeys from config
+        if (this.isWhitelisted(pubkey)) {
+            logger.debug("[TRUST_PUBKEY] Pubkey trusted: whitelisted", {
+                pubkey: pubkey.substring(0, 12),
+            });
+            return { trusted: true, reason: "whitelisted" };
+        }
+
+        // 2. Check if it's the backend's own pubkey (uses cache)
+        const backendPubkey = await this.getBackendPubkey();
+        if (backendPubkey && pubkey === backendPubkey) {
+            logger.debug("[TRUST_PUBKEY] Pubkey trusted: backend", {
+                pubkey: pubkey.substring(0, 12),
+            });
+            return { trusted: true, reason: "backend" };
+        }
+
+        // 3. Check if it's an agent in the system
+        if (this.isAgentPubkey(pubkey)) {
+            logger.debug("[TRUST_PUBKEY] Pubkey trusted: agent", {
+                pubkey: pubkey.substring(0, 12),
+            });
+            return { trusted: true, reason: "agent" };
+        }
+
+        // Not trusted
+        logger.debug("[TRUST_PUBKEY] Pubkey not trusted", {
+            pubkey: pubkey.substring(0, 12),
+        });
+        return { trusted: false };
+    }
+
+    /**
+     * Check if an NDKEvent is from a trusted source.
+     * Extracts the pubkey from the event and uses the existing pubkey-based trust logic.
+     *
+     * @param event The NDKEvent to check
+     * @returns TrustResult indicating if the event's author is trusted and why
+     */
+    async isTrustedEvent(event: NDKEvent): Promise<TrustResult> {
+        const pubkey = this.getEventPubkey(event);
+
+        if (!pubkey) {
+            return { trusted: false };
+        }
+
+        return this.isTrusted(pubkey);
+    }
+
+    /**
+     * Synchronous version of isTrustedEvent - uses cached backend pubkey.
+     * Note: May return false negative for backend pubkey if cache is not initialized.
+     * Use initializeBackendPubkeyCache() first if you need sync checks.
+     *
+     * @param event The NDKEvent to check
+     * @returns TrustResult indicating if the event's author is trusted and why
+     */
+    isTrustedEventSync(event: NDKEvent): TrustResult {
+        const pubkey = this.getEventPubkey(event);
+
+        if (!pubkey) {
+            return { trusted: false };
+        }
+
+        return this.isTrustedSync(pubkey);
+    }
+
+    /**
+     * Synchronous version of isTrusted - uses cached backend pubkey.
+     * Note: May return false negative for backend pubkey if cache is not initialized.
+     * Use initializeBackendPubkeyCache() first if you need sync checks.
+     *
+     * @param pubkey The pubkey to check (hex format)
+     * @returns TrustResult indicating if trusted and why
+     */
+    isTrustedSync(pubkey: Hexpubkey): TrustResult {
+        // 1. Check whitelisted pubkeys from config
+        if (this.isWhitelisted(pubkey)) {
+            return { trusted: true, reason: "whitelisted" };
+        }
+
+        // 2. Check cached backend pubkey
+        if (this.cachedBackendPubkey && pubkey === this.cachedBackendPubkey) {
+            return { trusted: true, reason: "backend" };
+        }
+
+        // 3. Check if it's an agent in the system
+        if (this.isAgentPubkey(pubkey)) {
+            return { trusted: true, reason: "agent" };
+        }
+
+        return { trusted: false };
+    }
+
+    /**
+     * Initialize the backend pubkey cache for sync operations.
+     * Call this during startup if you need to use isTrustedSync.
+     */
+    async initializeBackendPubkeyCache(): Promise<void> {
+        const pubkey = await this.getBackendPubkey();
+        if (pubkey) {
+            logger.debug("[TRUST_PUBKEY] Backend pubkey cache initialized", {
+                pubkey: pubkey.substring(0, 12),
+            });
+        }
+        // Note: getBackendPubkey already logs debug message on failure
+    }
+
+    /**
+     * Get all currently trusted pubkeys.
+     * Useful for debugging or displaying trust status.
+     *
+     * De-duplicates entries and enforces precedence (whitelisted > backend > agent).
+     * If a pubkey appears in multiple trust sources, only the highest precedence reason is returned.
+     *
+     * @returns Array of trusted pubkeys with their trust reasons
+     */
+    async getAllTrustedPubkeys(): Promise<Array<{ pubkey: Hexpubkey; reason: TrustReason }>> {
+        // Use a Map to de-duplicate, storing by pubkey with highest precedence reason
+        const trustedMap = new Map<Hexpubkey, TrustReason>();
+
+        // Priority order: whitelisted (1) > backend (2) > agent (3)
+        // Lower number = higher priority, so we only set if not already present (first wins)
+
+        // 1. Add whitelisted pubkeys (highest priority)
+        const whitelisted = this.getWhitelistedPubkeys();
+        for (const pubkey of whitelisted) {
+            if (!trustedMap.has(pubkey)) {
+                trustedMap.set(pubkey, "whitelisted");
+            }
+        }
+
+        // 2. Add backend pubkey (second priority, uses cache)
+        const backendPubkey = await this.getBackendPubkey();
+        if (backendPubkey && !trustedMap.has(backendPubkey)) {
+            trustedMap.set(backendPubkey, "backend");
+        }
+
+        // 3. Add agent pubkeys (lowest priority)
+        const projectCtx = projectContextStore.getContext();
+        if (projectCtx) {
+            for (const [_slug, agent] of projectCtx.agents) {
+                if (agent.pubkey && !trustedMap.has(agent.pubkey)) {
+                    trustedMap.set(agent.pubkey, "agent");
+                }
+            }
+        }
+
+        // Convert map to array
+        return Array.from(trustedMap.entries()).map(([pubkey, reason]) => ({
+            pubkey,
+            reason,
+        }));
+    }
+
+    // =====================================================================================
+    // PRIVATE HELPERS
+    // =====================================================================================
+
+    /**
+     * Extract and validate pubkey from an NDKEvent.
+     * Returns undefined if the event has no pubkey or an empty pubkey.
+     *
+     * @param event The NDKEvent to extract pubkey from
+     * @returns The pubkey or undefined if not present/valid
+     */
+    private getEventPubkey(event: NDKEvent): Hexpubkey | undefined {
+        const pubkey = event.pubkey;
+
+        if (!pubkey) {
+            logger.debug("[TRUST_PUBKEY] Event has no pubkey", {
+                eventId: event.id?.substring(0, 12),
+            });
+            return undefined;
+        }
+
+        return pubkey;
+    }
+
+    /**
+     * Check if pubkey is in the whitelist using cached Set for O(1) lookups.
+     */
+    private isWhitelisted(pubkey: Hexpubkey): boolean {
+        return this.getWhitelistSet().has(pubkey);
+    }
+
+    /**
+     * Get the cached whitelist Set, building from config on first access.
+     * The set is cached until clearCache() is called; config changes
+     * are only reflected after an explicit cache clear.
+     */
+    private getWhitelistSet(): Set<Hexpubkey> {
+        if (!this.cachedWhitelistSet) {
+            this.cachedWhitelistSet = new Set(this.getWhitelistedPubkeys());
+        }
+        return this.cachedWhitelistSet;
+    }
+
+    /**
+     * Get whitelisted pubkeys from config
+     */
+    private getWhitelistedPubkeys(): string[] {
+        try {
+            return config.getWhitelistedPubkeys(undefined, config.getConfig());
+        } catch (error) {
+            logger.debug("[TRUST_PUBKEY] Failed to get whitelisted pubkeys from config", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return [];
+        }
+    }
+
+    /**
+     * Get backend pubkey, using cache if available.
+     * This method ensures we only fetch from config.getBackendSigner() once,
+     * then use the cached value for subsequent calls.
+     *
+     * @returns The backend pubkey or undefined if not available
+     */
+    private async getBackendPubkey(): Promise<Hexpubkey | undefined> {
+        // Return cached value if available
+        if (this.cachedBackendPubkey) {
+            return this.cachedBackendPubkey;
+        }
+
+        // Fetch and cache
+        try {
+            const signer = await config.getBackendSigner();
+            this.cachedBackendPubkey = signer.pubkey;
+            return this.cachedBackendPubkey;
+        } catch (error) {
+            logger.debug("[TRUST_PUBKEY] Failed to get backend signer", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return undefined;
+        }
+    }
+
+    /**
+     * Check if pubkey belongs to an agent in the system.
+     * Returns false if no project context is available (e.g., during daemon startup
+     * or when called outside of projectContextStore.run()).
+     */
+    private isAgentPubkey(pubkey: Hexpubkey): boolean {
+        const projectCtx = projectContextStore.getContext();
+        if (!projectCtx) {
+            return false;
+        }
+        return projectCtx.getAgentByPubkey(pubkey) !== undefined;
+    }
+
+    /**
+     * Clear all caches (useful for testing and config reloads)
+     */
+    clearCache(): void {
+        this.cachedBackendPubkey = undefined;
+        this.cachedWhitelistSet = undefined;
+        logger.debug("[TRUST_PUBKEY] Cache cleared");
+    }
+}
+
+/**
+ * Get the TrustPubkeyService singleton instance
+ */
+export const getTrustPubkeyService = (): TrustPubkeyService =>
+    TrustPubkeyService.getInstance();

package/src/services/trust-pubkeys/index.ts

@@ -0,0 +1,2 @@
+export { TrustPubkeyService, getTrustPubkeyService } from "./TrustPubkeyService";
+export type { TrustResult, TrustReason } from "./TrustPubkeyService";