@tenex-chat/backend 0.9.1

package/src/services/agents-md/AgentsMdService.ts

@@ -0,0 +1,184 @@
+/**
+ * AgentsMdService - Service for discovering and reading AGENTS.md files
+ *
+ * AGENTS.md files provide contextual guidelines for AI agents working in specific
+ * directories. These files are discovered hierarchically and injected as system
+ * reminders after relevant tool results (like fs_read).
+ *
+ * Key behaviors:
+ * - Finds all AGENTS.md files from a path up to the project root
+ * - Returns them in order from most specific to most general
+ * - Caches file contents to avoid repeated reads
+ */
+
+import { readFile, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { trace } from "@opentelemetry/api";
+
+export interface AgentsMdFile {
+    /** Absolute path to the AGENTS.md file */
+    path: string;
+    /** Directory containing the AGENTS.md file */
+    directory: string;
+    /** Content of the AGENTS.md file */
+    content: string;
+}
+
+/**
+ * Singleton service for AGENTS.md file discovery and caching
+ */
+class AgentsMdServiceImpl {
+    /** Cache of AGENTS.md file contents by absolute path */
+    private contentCache = new Map<string, string | null>();
+
+    /** Cache expiry time in milliseconds (5 minutes) */
+    private readonly CACHE_TTL = 5 * 60 * 1000;
+
+    /** Timestamps for cache entries */
+    private cacheTimestamps = new Map<string, number>();
+
+    /**
+     * Find all AGENTS.md files from the given path up to the project root.
+     *
+     * @param targetPath - The file or directory path being accessed
+     * @param projectRoot - The project root directory (stops search here)
+     * @returns Array of AGENTS.md files, ordered from most specific to most general
+     */
+    async findAgentsMdFiles(
+        targetPath: string,
+        projectRoot: string
+    ): Promise<AgentsMdFile[]> {
+        const absoluteTargetPath = resolve(targetPath);
+        const absoluteProjectRoot = resolve(projectRoot);
+
+        // Start from the directory containing the target
+        let currentDir = existsSync(absoluteTargetPath) && !absoluteTargetPath.endsWith("/")
+            ? (await this.isDirectory(absoluteTargetPath) ? absoluteTargetPath : dirname(absoluteTargetPath))
+            : dirname(absoluteTargetPath);
+
+        const results: AgentsMdFile[] = [];
+        const visited = new Set<string>();
+
+        // Walk up the directory tree until we reach the project root (inclusive)
+        // Note: startsWith handles equality case, so no need for explicit === check
+        while (currentDir.startsWith(absoluteProjectRoot)) {
+            // Avoid infinite loop
+            if (visited.has(currentDir)) break;
+            visited.add(currentDir);
+
+            const agentsMdPath = join(currentDir, "AGENTS.md");
+            const content = await this.readAgentsMd(agentsMdPath);
+
+            if (content !== null) {
+                results.push({
+                    path: agentsMdPath,
+                    directory: currentDir,
+                    content,
+                });
+            }
+
+            // Stop at project root
+            if (currentDir === absoluteProjectRoot) break;
+
+            // Move up one directory
+            const parent = dirname(currentDir);
+            if (parent === currentDir) break; // Reached filesystem root
+            currentDir = parent;
+        }
+
+        return results;
+    }
+
+    /**
+     * Check if the project root has an AGENTS.md file.
+     *
+     * @param projectRoot - The project root directory
+     * @returns true if AGENTS.md exists at the project root
+     */
+    async hasRootAgentsMd(projectRoot: string): Promise<boolean> {
+        const agentsMdPath = join(resolve(projectRoot), "AGENTS.md");
+        const content = await this.readAgentsMd(agentsMdPath);
+        return content !== null;
+    }
+
+    /**
+     * Get the content of the root AGENTS.md file.
+     *
+     * @param projectRoot - The project root directory
+     * @returns The content of the AGENTS.md file, or null if not found
+     */
+    async getRootAgentsMdContent(projectRoot: string): Promise<string | null> {
+        const agentsMdPath = join(resolve(projectRoot), "AGENTS.md");
+        return this.readAgentsMd(agentsMdPath);
+    }
+
+    /**
+     * Read an AGENTS.md file with caching.
+     */
+    private async readAgentsMd(absolutePath: string): Promise<string | null> {
+        const now = Date.now();
+        const cachedTimestamp = this.cacheTimestamps.get(absolutePath);
+
+        // Check if cache entry exists and is still valid
+        if (cachedTimestamp && now - cachedTimestamp < this.CACHE_TTL) {
+            const cached = this.contentCache.get(absolutePath);
+            if (cached !== undefined) {
+                return cached;
+            }
+        }
+
+        // Read from disk
+        try {
+            if (!existsSync(absolutePath)) {
+                this.contentCache.set(absolutePath, null);
+                this.cacheTimestamps.set(absolutePath, now);
+                return null;
+            }
+
+            const content = await readFile(absolutePath, "utf-8");
+            this.contentCache.set(absolutePath, content);
+            this.cacheTimestamps.set(absolutePath, now);
+            return content;
+        } catch (error) {
+            // Trace error for debugging (file not found after existsSync is unexpected)
+            trace.getActiveSpan?.()?.addEvent("agents_md.read_error", {
+                "agents_md.path": absolutePath,
+                "agents_md.error": error instanceof Error ? error.message : String(error),
+            });
+            this.contentCache.set(absolutePath, null);
+            this.cacheTimestamps.set(absolutePath, now);
+            return null;
+        }
+    }
+
+    /**
+     * Check if a path is a directory
+     */
+    private async isDirectory(path: string): Promise<boolean> {
+        try {
+            const stats = await stat(path);
+            return stats.isDirectory();
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * Clear the cache (useful for testing)
+     */
+    clearCache(): void {
+        this.contentCache.clear();
+        this.cacheTimestamps.clear();
+    }
+
+    /**
+     * Invalidate a specific path in the cache
+     */
+    invalidatePath(absolutePath: string): void {
+        this.contentCache.delete(absolutePath);
+        this.cacheTimestamps.delete(absolutePath);
+    }
+}
+
+export const agentsMdService = new AgentsMdServiceImpl();

package/src/services/agents-md/SystemReminderInjector.ts

@@ -0,0 +1,238 @@
+/**
+ * SystemReminderInjector - Injects AGENTS.md content as system reminders
+ *
+ * This module handles the injection of AGENTS.md content into tool results,
+ * following these rules:
+ *
+ * 1. When a file/directory is read, find all AGENTS.md files from that path
+ *    up to the project root
+ * 2. Inject system reminders after the tool output
+ * 3. Track which AGENTS.md files have already been shown (non-truncated)
+ *    to avoid duplication
+ * 4. Format multiple AGENTS.md files in a single system-reminder block
+ *    with clear path attribution
+ */
+
+import { resolve, relative } from "node:path";
+import { agentsMdService, type AgentsMdFile } from "./AgentsMdService";
+
+/**
+ * Tracker for which AGENTS.md files have been shown in the current context
+ */
+export interface AgentsMdVisibilityTracker {
+    /**
+     * Check if an AGENTS.md file has already been shown (is visible)
+     */
+    isVisible(agentsMdPath: string): boolean;
+
+    /**
+     * Mark an AGENTS.md file as visible (shown in a non-truncated tool result)
+     */
+    markVisible(agentsMdPath: string): void;
+
+    /**
+     * Get all visible AGENTS.md paths
+     */
+    getVisiblePaths(): Set<string>;
+}
+
+/**
+ * Create a visibility tracker for AGENTS.md files
+ */
+export function createAgentsMdVisibilityTracker(): AgentsMdVisibilityTracker {
+    const visiblePaths = new Set<string>();
+
+    return {
+        isVisible(agentsMdPath: string): boolean {
+            return visiblePaths.has(resolve(agentsMdPath));
+        },
+
+        markVisible(agentsMdPath: string): void {
+            visiblePaths.add(resolve(agentsMdPath));
+        },
+
+        getVisiblePaths(): Set<string> {
+            return visiblePaths;
+        },
+    };
+}
+
+/**
+ * Result from checking for relevant AGENTS.md system reminders
+ */
+export interface SystemReminderResult {
+    /** Whether any new system reminders need to be injected */
+    hasReminders: boolean;
+    /** The formatted system reminder content (empty if no reminders) */
+    content: string;
+    /** The AGENTS.md files that were included */
+    includedFiles: AgentsMdFile[];
+}
+
+/**
+ * Format AGENTS.md files into a system reminder block.
+ *
+ * The format groups multiple files with clear path attribution:
+ * ```
+ * <system-reminder>
+ * # AGENTS.md from /path/to/directory
+ *
+ * [content of AGENTS.md]
+ *
+ * # AGENTS.md from /parent/directory
+ *
+ * [content of parent AGENTS.md]
+ * </system-reminder>
+ * ```
+ */
+export function formatSystemReminder(
+    files: AgentsMdFile[],
+    projectRoot: string
+): string {
+    if (files.length === 0) {
+        return "";
+    }
+
+    const sections = files.map((file) => {
+        const relativePath = relative(projectRoot, file.directory);
+        const displayPath = relativePath || "(project root)";
+        return `# AGENTS.md from ${displayPath}\n\n${file.content.trim()}`;
+    });
+
+    return `\n<system-reminder>\n${sections.join("\n\n")}\n</system-reminder>`;
+}
+
+/**
+ * Get system reminders for a file read operation.
+ *
+ * This function:
+ * 1. Finds all AGENTS.md files from the target path up to project root
+ * 2. Filters out already-visible files (using the tracker)
+ * 3. Marks newly-found files as visible
+ * 4. Returns formatted system reminder content
+ *
+ * @param targetPath - The file/directory path being read
+ * @param projectRoot - The project root directory
+ * @param tracker - Visibility tracker for deduplication
+ * @param isTruncated - Whether the tool result is truncated (don't mark as visible if so)
+ * @returns System reminder result with content and metadata
+ */
+export async function getSystemRemindersForPath(
+    targetPath: string,
+    projectRoot: string,
+    tracker: AgentsMdVisibilityTracker,
+    isTruncated: boolean = false
+): Promise<SystemReminderResult> {
+    const absoluteProjectRoot = resolve(projectRoot);
+
+    // Find all AGENTS.md files from the target path up to project root
+    const allFiles = await agentsMdService.findAgentsMdFiles(targetPath, absoluteProjectRoot);
+
+    // Filter out already-visible files
+    const newFiles = allFiles.filter((file) => !tracker.isVisible(file.path));
+
+    if (newFiles.length === 0) {
+        return {
+            hasReminders: false,
+            content: "",
+            includedFiles: [],
+        };
+    }
+
+    // Only mark as visible if the tool result is NOT truncated
+    // (truncated results aren't really "visible" to the model)
+    if (!isTruncated) {
+        for (const file of newFiles) {
+            tracker.markVisible(file.path);
+        }
+    }
+
+    const content = formatSystemReminder(newFiles, absoluteProjectRoot);
+
+    return {
+        hasReminders: true,
+        content,
+        includedFiles: newFiles,
+    };
+}
+
+/**
+ * Check if a tool name is one that reads files/directories
+ * and should trigger AGENTS.md system reminder injection.
+ */
+export function shouldInjectForTool(toolName: string): boolean {
+    // Tools that read files/directories
+    const fileReadTools = [
+        "fs_read",
+        "Read",              // Claude Code's Read tool
+        "mcp__filesystem__read_file",
+        "mcp__filesystem__read_directory",
+        "mcp__filesystem__list_directory",
+        "mcp__filesystem__get_file_info",
+    ];
+
+    // Check for exact match or pattern match
+    return fileReadTools.includes(toolName) ||
+           toolName.startsWith("mcp__") && toolName.includes("read");
+}
+
+/**
+ * Extract the path from a tool's input arguments.
+ * Different tools use different parameter names for the path.
+ */
+export function extractPathFromToolInput(input: unknown): string | null {
+    if (!input || typeof input !== "object") {
+        return null;
+    }
+
+    const inputObj = input as Record<string, unknown>;
+
+    // fs_read and similar tools use 'path'
+    if ("path" in inputObj && typeof inputObj.path === "string") {
+        return inputObj.path;
+    }
+
+    // Some tools use 'file_path'
+    if ("file_path" in inputObj && typeof inputObj.file_path === "string") {
+        return inputObj.file_path;
+    }
+
+    // Some tools use 'directory'
+    if ("directory" in inputObj && typeof inputObj.directory === "string") {
+        return inputObj.directory;
+    }
+
+    return null;
+}
+
+/**
+ * Append system reminder content to a tool result output.
+ *
+ * @param output - The original tool result output
+ * @param reminderContent - The system reminder content to append
+ * @returns The modified output with system reminder appended
+ */
+export function appendSystemReminderToOutput(
+    output: unknown,
+    reminderContent: string
+): unknown {
+    if (typeof output === "string") {
+        return output + reminderContent;
+    }
+
+    if (output && typeof output === "object" && "value" in output) {
+        const existingOutput = output as { type?: string; value: unknown };
+        const valueStr = typeof existingOutput.value === "string"
+            ? existingOutput.value
+            : JSON.stringify(existingOutput.value);
+
+        return {
+            ...existingOutput,
+            value: valueStr + reminderContent,
+        };
+    }
+
+    // For other formats, try to stringify and append
+    const outputStr = typeof output === "string" ? output : JSON.stringify(output);
+    return outputStr + reminderContent;
+}

package/src/services/agents-md/index.ts

@@ -0,0 +1,11 @@
+export { agentsMdService, type AgentsMdFile } from "./AgentsMdService";
+export {
+    createAgentsMdVisibilityTracker,
+    formatSystemReminder,
+    getSystemRemindersForPath,
+    shouldInjectForTool,
+    extractPathFromToolInput,
+    appendSystemReminderToOutput,
+    type AgentsMdVisibilityTracker,
+    type SystemReminderResult,
+} from "./SystemReminderInjector";

package/src/services/apns/APNsClient.ts

@@ -0,0 +1,203 @@
+/**
+ * HTTP/2 client for Apple Push Notification service (APNs).
+ *
+ * Handles JWT token generation (ES256) and push delivery.
+ * Uses native fetch (Bun supports HTTP/2 via ALPN).
+ */
+
+import * as fs from "node:fs";
+import * as crypto from "node:crypto";
+import { logger } from "@/utils/logger";
+import type { APNsPayload, APNsSendResult } from "./types";
+
+const LOG_PREFIX = "[APNsClient]";
+
+/** JWT tokens are valid for up to 1 hour; we refresh at 50 minutes. */
+const JWT_REFRESH_INTERVAL_MS = 50 * 60 * 1000;
+
+/** APNs production endpoint */
+const APNS_PRODUCTION_HOST = "https://api.push.apple.com";
+
+/** APNs sandbox endpoint */
+const APNS_SANDBOX_HOST = "https://api.sandbox.push.apple.com";
+
+export interface APNsClientConfig {
+    keyPath: string;
+    keyId: string;
+    teamId: string;
+    bundleId: string;
+    production: boolean;
+}
+
+/**
+ * Base64url encode a buffer (no padding).
+ */
+function base64url(buf: Buffer): string {
+    return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+export class APNsClient {
+    private config: APNsClientConfig;
+    private signingKey: crypto.KeyObject | null = null;
+    private cachedJwt: string | null = null;
+    private jwtIssuedAt = 0;
+    private fetchFn: typeof fetch;
+
+    constructor(clientConfig: APNsClientConfig, fetchFn?: typeof fetch) {
+        this.config = clientConfig;
+        this.fetchFn = fetchFn ?? fetch;
+    }
+
+    /**
+     * Load the .p8 private key from disk.
+     * Called lazily on first send.
+     */
+    private loadSigningKey(): void {
+        const keyData = fs.readFileSync(this.config.keyPath, "utf-8");
+        this.signingKey = crypto.createPrivateKey(keyData);
+
+        logger.info(`${LOG_PREFIX} Loaded APNs signing key`, {
+            keyId: this.config.keyId,
+            teamId: this.config.teamId,
+        });
+    }
+
+    /**
+     * Generate a JWT for APNs authentication (ES256).
+     * Caches the token and refreshes before expiry.
+     */
+    private getJwt(): string {
+        const now = Math.floor(Date.now() / 1000);
+
+        // Return cached JWT if still fresh
+        if (this.cachedJwt && (now - this.jwtIssuedAt) * 1000 < JWT_REFRESH_INTERVAL_MS) {
+            return this.cachedJwt;
+        }
+
+        if (!this.signingKey) {
+            this.loadSigningKey();
+        }
+
+        // JWT Header
+        const header = base64url(
+            Buffer.from(JSON.stringify({ alg: "ES256", kid: this.config.keyId }))
+        );
+
+        // JWT Payload
+        const payload = base64url(
+            Buffer.from(JSON.stringify({ iss: this.config.teamId, iat: now }))
+        );
+
+        // Sign
+        if (!this.signingKey) {
+            throw new Error("Signing key not loaded");
+        }
+        const signingInput = `${header}.${payload}`;
+        const sign = crypto.createSign("SHA256");
+        sign.update(signingInput);
+        const derSignature = sign.sign(this.signingKey);
+
+        // Convert DER signature to raw r||s (64 bytes) for ES256
+        const rawSignature = derToRaw(derSignature);
+        const signature = base64url(rawSignature);
+
+        this.cachedJwt = `${signingInput}.${signature}`;
+        this.jwtIssuedAt = now;
+
+        logger.debug(`${LOG_PREFIX} Generated new JWT`, { iat: now });
+
+        return this.cachedJwt;
+    }
+
+    /**
+     * Send a push notification to a single device token.
+     */
+    async send(deviceToken: string, payload: APNsPayload): Promise<APNsSendResult> {
+        const host = this.config.production ? APNS_PRODUCTION_HOST : APNS_SANDBOX_HOST;
+        const url = `${host}/3/device/${deviceToken}`;
+        const body = JSON.stringify(payload);
+
+        try {
+            const jwt = this.getJwt();
+            const response = await this.fetchFn(url, {
+                method: "POST",
+                headers: {
+                    "authorization": `bearer ${jwt}`,
+                    "apns-topic": this.config.bundleId,
+                    "apns-push-type": "alert",
+                    "apns-priority": "10",
+                    "content-type": "application/json",
+                },
+                body,
+            });
+
+            const statusCode = response.status;
+
+            if (statusCode === 200) {
+                return { success: true, statusCode };
+            }
+
+            // Parse error response
+            const errorBody = await response.json().catch(() => ({})) as Record<string, unknown>;
+            const reason = (errorBody.reason as string) ?? "unknown";
+
+            logger.warn(`${LOG_PREFIX} APNs rejected push`, {
+                statusCode,
+                reason,
+                deviceToken: deviceToken.substring(0, 8),
+            });
+
+            const result: APNsSendResult = { success: false, statusCode, reason };
+
+            // 410 Gone means the token is no longer valid
+            if (statusCode === 410 && typeof errorBody.timestamp === "number") {
+                result.timestampMs = errorBody.timestamp as number;
+            }
+
+            return result;
+        } catch (error) {
+            logger.error(`${LOG_PREFIX} Failed to send push notification`, {
+                error: error instanceof Error ? error.message : String(error),
+                deviceToken: deviceToken.substring(0, 8),
+            });
+
+            return { success: false, statusCode: 0, reason: "network_error" };
+        }
+    }
+}
+
+/**
+ * Convert a DER-encoded ECDSA signature to raw r||s format (64 bytes for P-256).
+ * DER format: 0x30 <total_len> 0x02 <r_len> <r> 0x02 <s_len> <s>
+ */
+function derToRaw(der: Buffer): Buffer {
+    const raw = Buffer.alloc(64);
+
+    // Parse DER structure
+    let offset = 2; // skip 0x30 and total length
+
+    // Read r
+    offset += 1; // skip 0x02
+    const rLen = der[offset] ?? 0;
+    offset += 1;
+    const rBytes = der.subarray(offset, offset + rLen);
+    offset += rLen;
+
+    // Read s
+    offset += 1; // skip 0x02
+    const sLen = der[offset] ?? 0;
+    offset += 1;
+    const sBytes = der.subarray(offset, offset + sLen);
+
+    // Copy r (right-aligned, strip leading zero if present)
+    const rStart = rBytes[0] === 0 ? 1 : 0;
+    const rActual = rBytes.subarray(rStart);
+    rActual.copy(raw, 32 - rActual.length);
+
+    // Copy s (right-aligned, strip leading zero if present)
+    const sStart = sBytes[0] === 0 ? 1 : 0;
+    const sActual = sBytes.subarray(sStart);
+    sActual.copy(raw, 64 - sActual.length);
+
+    return raw;
+}