@tenex-chat/backend 0.9.1

package/src/services/ral/index.ts

@@ -0,0 +1,4 @@
+export { RALRegistry } from "./RALRegistry";
+export type { RALRegistryEvents } from "./RALRegistry";
+export { PendingDelegationsRegistry } from "./PendingDelegationsRegistry";
+export * from "./types";

package/src/services/ral/types.ts

@@ -0,0 +1,292 @@
+/** Role types that can be used for message injection */
+export type InjectionRole = "user" | "system";
+
+/** Result of injecting a message into an active RAL */
+export interface InjectionResult {
+  /** The active RAL entry, if found */
+  activeRal?: RALRegistryEntry;
+  /** Whether the message was queued for injection */
+  queued: boolean;
+  /** Whether an active streaming run was aborted */
+  aborted: boolean;
+}
+
+// ============================================================================
+// Todo Types
+// ============================================================================
+
+export type TodoStatus = "pending" | "in_progress" | "done" | "skipped";
+
+export interface TodoItem {
+  /** Unique identifier - can be custom or auto-generated from title */
+  id: string;
+  /** Human-readable title */
+  title: string;
+  /** Detailed description of what needs to be done */
+  description: string;
+  /** Current status of the todo item */
+  status: TodoStatus;
+  /** Required when status='skipped' - explains why item was skipped */
+  skipReason?: string;
+  /** Timestamp when item was created */
+  createdAt: number;
+  /** Timestamp of last status change */
+  updatedAt: number;
+}
+
+interface BasePendingDelegation {
+  delegationConversationId: string;
+  recipientPubkey: string;
+  senderPubkey: string;
+  prompt: string;
+  /** Which RAL created this delegation (for provenance tracking) */
+  ralNumber: number;
+  /**
+   * If true, this delegation has been killed via the kill tool.
+   * Completion events for killed delegations should be ignored.
+   * This prevents the race condition where a delegation completes
+   * after being killed but before the abort fully propagates.
+   */
+  killed?: boolean;
+  /** Timestamp when delegation was killed (for debugging) */
+  killedAt?: number;
+}
+
+interface StandardDelegation extends BasePendingDelegation {
+  type?: "standard";
+}
+
+interface FollowupDelegation extends BasePendingDelegation {
+  type: "followup";
+  /** The event ID of the followup message (needed for routing responses) */
+  followupEventId?: string;
+}
+
+interface ExternalDelegation extends BasePendingDelegation {
+  type: "external";
+  projectId?: string;
+}
+
+interface AskDelegation extends BasePendingDelegation {
+  type: "ask";
+  suggestions?: string[];
+}
+
+export type PendingDelegation =
+  | StandardDelegation
+  | FollowupDelegation
+  | ExternalDelegation
+  | AskDelegation;
+
+export interface DelegationMessage {
+  senderPubkey: string;
+  recipientPubkey: string;
+  content: string;
+  timestamp: number;
+}
+
+/**
+ * Discriminated union for completed delegations.
+ * Either successfully completed or aborted with a reason.
+ */
+export type CompletedDelegation =
+  | {
+      delegationConversationId: string;
+      recipientPubkey: string;
+      senderPubkey: string;
+      transcript: DelegationMessage[];
+      completedAt: number;
+      /** Which RAL created this delegation (for provenance tracking) */
+      ralNumber: number;
+      status: "completed";
+    }
+  | {
+      delegationConversationId: string;
+      recipientPubkey: string;
+      senderPubkey: string;
+      transcript: DelegationMessage[];
+      completedAt: number;
+      /** Which RAL created this delegation (for provenance tracking) */
+      ralNumber: number;
+      status: "aborted";
+      abortReason: string;
+    };
+
+export interface QueuedInjection {
+  role: InjectionRole;
+  content: string;
+  queuedAt: number;
+  /** If true, message is included in LLM context but NOT persisted to ConversationStore */
+  ephemeral?: boolean;
+  /** Original sender pubkey (for message attribution when sender differs from expected) */
+  senderPubkey?: string;
+  /** Original Nostr event ID (for deduplication - prevents double-insertion via both addEvent and injection paths) */
+  eventId?: string;
+}
+
+export interface RALRegistryEntry {
+  id: string;
+  /** Sequential number for this RAL within the conversation (1, 2, 3...) */
+  ralNumber: number;
+  agentPubkey: string;
+  /** The project this RAL belongs to - required for multi-project isolation in daemon mode */
+  projectId: string;
+  /** The conversation this RAL belongs to - RAL is scoped per agent+conversation */
+  conversationId: string;
+  queuedInjections: QueuedInjection[];
+  /** Whether the agent is currently streaming a response */
+  isStreaming: boolean;
+  /**
+   * Map of currently executing tool call IDs to their tool info.
+   * Multiple tools can execute concurrently. ACTING state is derived from activeTools.size > 0.
+   * Keyed by toolCallId (not toolName) to properly track concurrent calls of the same tool.
+   * Value contains tool name (for display) and startedAt timestamp (for duration tracking).
+   */
+  activeTools: Map<string, { name: string; startedAt: number }>;
+  /** Most recently started tool name (derived from activeTools, for display only) */
+  currentTool?: string;
+  /** Start time of the most recently started tool (derived from activeTools, for display only) */
+  toolStartedAt?: number;
+  createdAt: number;
+  lastActivityAt: number;
+  /** The original event that triggered this RAL - used for proper tagging on resumption */
+  originalTriggeringEventId?: string;
+  /** OTEL trace ID for correlating stop events with the agent execution */
+  traceId?: string;
+  /** OTEL span ID of the agent execution span - used as parent for stop spans */
+  executionSpanId?: string;
+  /** Accumulated LLM runtime in milliseconds across all streaming sessions */
+  accumulatedRuntime: number;
+  /** Last reported runtime in milliseconds - used to calculate incremental runtime */
+  lastReportedRuntime: number;
+  /** Timestamp when current LLM stream started (for calculating duration) - immutable for stream lifetime */
+  llmStreamStartTime?: number;
+  /** Checkpoint timestamp for incremental runtime reporting mid-stream (resets on each consume) */
+  lastRuntimeCheckpointAt?: number;
+  /** Heuristic state - namespaced under 'heuristics' */
+  heuristics?: {
+    /** Pending violations waiting to be injected */
+    pendingViolations: Array<{
+      id: string;
+      title: string;
+      message: string;
+      severity: "warning" | "error";
+      timestamp: number;
+      heuristicId: string;
+    }>;
+    /** Set of violation IDs shown in this RAL (for deduplication) */
+    shownViolationIds: Set<string>;
+    /** O(1) precomputed summary for heuristic evaluation */
+    summary?: {
+      /** Tool call history (bounded to last N tools) */
+      recentTools: Array<{ name: string; timestamp: number }>;
+      /** Flags for quick checks */
+      flags: {
+        hasTodoWrite: boolean;
+        hasDelegation: boolean;
+        hasVerification: boolean;
+        hasGitAgentCommit: boolean;
+      };
+      /** Pending delegation count for this RAL (O(1) counter) */
+      pendingDelegationCount: number;
+    };
+    /** Tool args storage: toolCallId -> args (for passing to heuristics) */
+    toolArgs?: Map<string, unknown>;
+  };
+}
+
+export interface StopExecutionSignal {
+  __stopExecution: true;
+  pendingDelegations: PendingDelegation[];
+}
+
+/**
+ * Check if value is a direct (unwrapped) StopExecutionSignal
+ */
+function isDirectStopExecutionSignal(value: unknown): value is StopExecutionSignal {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "__stopExecution" in value &&
+    (value as StopExecutionSignal).__stopExecution === true
+  );
+}
+
+/**
+ * Try to extract a StopExecutionSignal from an MCP-wrapped response.
+ *
+ * Claude Code SDK wraps tool results in MCP format:
+ * - Array format: [{ type: "text", text: '{"__stopExecution":true,...}' }]
+ * - Object format: { content: [{ type: "text", text: "..." }] }
+ *
+ * Returns the parsed StopExecutionSignal if found, null otherwise.
+ */
+function extractFromMCPWrapped(value: unknown): StopExecutionSignal | null {
+  // Handle both array format and { content: [...] } format
+  const content = Array.isArray(value)
+    ? value
+    : (typeof value === "object" && value !== null && "content" in value)
+      ? (value as { content: unknown[] }).content
+      : null;
+
+  if (!Array.isArray(content)) return null;
+
+  // Find the text item in the content array
+  const textItem = content.find((c: unknown) =>
+    typeof c === "object" &&
+    c !== null &&
+    (c as { type?: string }).type === "text"
+  ) as { text?: string } | undefined;
+
+  if (!textItem?.text) return null;
+
+  try {
+    const parsed = JSON.parse(textItem.text);
+    if (isDirectStopExecutionSignal(parsed)) {
+      return parsed;
+    }
+  } catch {
+    // Not valid JSON, not a stop signal
+  }
+
+  return null;
+}
+
+/**
+ * Type guard for StopExecutionSignal.
+ *
+ * Handles both:
+ * 1. Direct StopExecutionSignal objects (from standard AI SDK providers)
+ * 2. MCP-wrapped responses (from Claude Code SDK where tool results get
+ *    wrapped in [{ type: "text", text: "..." }] format)
+ */
+export function isStopExecutionSignal(value: unknown): value is StopExecutionSignal {
+  // Check direct format first (most common case)
+  if (isDirectStopExecutionSignal(value)) {
+    return true;
+  }
+
+  // Check MCP-wrapped format (Claude Code SDK)
+  return extractFromMCPWrapped(value) !== null;
+}
+
+/**
+ * Extract the pending delegations from a StopExecutionSignal.
+ *
+ * Works with both direct and MCP-wrapped formats.
+ * Returns null if value is not a StopExecutionSignal.
+ */
+export function extractPendingDelegations(value: unknown): PendingDelegation[] | null {
+  // Check direct format first
+  if (isDirectStopExecutionSignal(value)) {
+    return value.pendingDelegations;
+  }
+
+  // Check MCP-wrapped format
+  const extracted = extractFromMCPWrapped(value);
+  if (extracted) {
+    return extracted.pendingDelegations;
+  }
+
+  return null;
+}

package/src/services/reports/LocalReportStore.ts

@@ -0,0 +1,380 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, resolve, relative, basename, dirname } from "node:path";
+import { isPathWithinDirectory } from "@/lib/agent-home";
+import { logger } from "@/utils/logger";
+import { getProjectContext } from "@/services/projects/ProjectContext";
+
+/**
+ * Error thrown when a slug fails validation
+ */
+export class InvalidSlugError extends Error {
+    constructor(slug: string, reason: string) {
+        super(`Invalid report slug "${slug}": ${reason}`);
+        this.name = "InvalidSlugError";
+    }
+}
+
+/**
+ * Metadata stored alongside each local report to track its Nostr origin
+ */
+export interface LocalReportMetadata {
+    /** Addressable reference in NIP-33 format (kind:pubkey:identifier) */
+    addressableRef: string;
+    /** Unix timestamp when the report was created/published */
+    createdAt: number;
+    /** The slug (d-tag) of the report */
+    slug: string;
+}
+
+
+/**
+ * LocalReportStore manages local file storage for reports.
+ *
+ * Reports are stored at: $TENEX_BASE_DIR/projects/<projectDTag>/reports/<slug>.md
+ * Metadata is stored at: $TENEX_BASE_DIR/projects/<projectDTag>/reports/.metadata/<slug>.json
+ *
+ * This provides:
+ * - Fast local reads without Nostr lookups
+ * - Single source of truth for multi-agent collaboration
+ * - Backwards compatibility via subscription hydration
+ * - Project isolation to prevent d-tag conflicts across projects
+ */
+export class LocalReportStore {
+    private _basePath: string | null = null;
+    private _projectId: string | null = null;
+
+    /**
+     * Initialize the store for a project.
+     * Must be called once at startup before using any methods.
+     * @param metadataPath The project metadata path (e.g., ~/.tenex/projects/<dTag>)
+     */
+    initialize(metadataPath: string): void {
+        this._basePath = dirname(metadataPath);  // ~/.tenex/projects
+        this._projectId = basename(metadataPath); // <dTag>
+        logger.info(`[LocalReportStore] Initialized for project ${this._projectId}`, {
+            basePath: this._basePath,
+            projectId: this._projectId,
+        });
+    }
+
+    /**
+     * Check if the store has been initialized
+     */
+    isInitialized(): boolean {
+        return this._projectId !== null && this._basePath !== null;
+    }
+
+    /**
+     * Get the project ID (d-tag)
+     */
+    get projectId(): string | null {
+        return this._projectId;
+    }
+
+    /**
+     * Get the path to the reports directory
+     * Requires initialization with a project context
+     */
+    getReportsDir(): string {
+        if (!this._basePath || !this._projectId) {
+            throw new Error("LocalReportStore.initialize() must be called before getReportsDir()");
+        }
+        return join(this._basePath, this._projectId, "reports");
+    }
+
+    /**
+     * Get the path to the metadata directory
+     */
+    private getMetadataDir(): string {
+        if (!this._basePath || !this._projectId) {
+            throw new Error("LocalReportStore.initialize() must be called before getMetadataDir()");
+        }
+        return join(this._basePath, this._projectId, "reports", ".metadata");
+    }
+
+    /**
+     * Validate a slug to prevent path traversal attacks.
+     * Slugs must:
+     * - Not be empty
+     * - Not contain path separators (/, \)
+     * - Not contain parent directory references (..)
+     * - Not start or end with dots
+     * - Only contain alphanumeric characters, hyphens, underscores
+     *
+     * @param slug The slug to validate
+     * @throws InvalidSlugError if the slug is invalid
+     */
+    validateSlug(slug: string): void {
+        if (!slug || slug.trim() === "") {
+            throw new InvalidSlugError(slug, "slug cannot be empty");
+        }
+
+        // Check for path separators
+        if (slug.includes("/") || slug.includes("\\")) {
+            throw new InvalidSlugError(slug, "slug cannot contain path separators (/ or \\)");
+        }
+
+        // Check for parent directory references
+        if (slug.includes("..")) {
+            throw new InvalidSlugError(slug, "slug cannot contain parent directory references (..)");
+        }
+
+        // Check for leading/trailing dots (could be hidden files or special dirs)
+        if (slug.startsWith(".") || slug.endsWith(".")) {
+            throw new InvalidSlugError(slug, "slug cannot start or end with a dot");
+        }
+
+        // Only allow safe characters: alphanumeric, hyphens, underscores
+        const safeSlugPattern = /^[a-zA-Z0-9_-]+$/;
+        if (!safeSlugPattern.test(slug)) {
+            throw new InvalidSlugError(
+                slug,
+                "slug can only contain alphanumeric characters, hyphens (-), and underscores (_)"
+            );
+        }
+    }
+
+    /**
+     * Get a safe, validated path for a report file.
+     * Validates the slug and ensures the resulting path is within the reports directory.
+     *
+     * @param slug The report slug
+     * @param extension The file extension (default: "md")
+     * @returns The validated file path
+     * @throws InvalidSlugError if the slug is invalid or path escapes the reports directory
+     */
+    private getSafePath(slug: string, extension: "md" | "json" = "md"): string {
+        this.validateSlug(slug);
+
+        const baseDir = extension === "md" ? this.getReportsDir() : this.getMetadataDir();
+        const filePath = resolve(join(baseDir, `${slug}.${extension}`));
+
+        // Double-check: ensure resolved path is still within the base directory
+        const relativePath = relative(baseDir, filePath);
+        if (relativePath.startsWith("..") || relativePath.includes("..")) {
+            throw new InvalidSlugError(slug, "resolved path escapes the reports directory");
+        }
+
+        return filePath;
+    }
+
+    /**
+     * Ensure the reports and metadata directories exist
+     */
+    async ensureDirectories(): Promise<void> {
+        await mkdir(this.getReportsDir(), { recursive: true });
+        await mkdir(this.getMetadataDir(), { recursive: true });
+    }
+
+    /**
+     * Get the file path for a report's content
+     * @throws InvalidSlugError if the slug is invalid
+     */
+    getReportPath(slug: string): string {
+        return this.getSafePath(slug, "md");
+    }
+
+    /**
+     * Get the file path for a report's metadata
+     * @throws InvalidSlugError if the slug is invalid
+     */
+    private getMetadataPath(slug: string): string {
+        return this.getSafePath(slug, "json");
+    }
+
+    /**
+     * Write a report to local storage with its metadata
+     * @param slug The report slug (d-tag)
+     * @param content The markdown content
+     * @param metadata The Nostr event metadata
+     */
+    async writeReport(slug: string, content: string, metadata: LocalReportMetadata): Promise<void> {
+        await this.ensureDirectories();
+
+        const reportPath = this.getReportPath(slug);
+        const metadataPath = this.getMetadataPath(slug);
+
+        // Write content file
+        await writeFile(reportPath, content, "utf-8");
+
+        // Write metadata file
+        await writeFile(metadataPath, JSON.stringify(metadata, null, 2), "utf-8");
+
+        logger.debug("📁 Saved report to local storage", {
+            slug,
+            path: reportPath,
+            contentLength: content.length,
+            addressableRef: metadata.addressableRef.substring(0, 20),
+        });
+    }
+
+    /**
+     * Read a report's content from local storage
+     * @param slug The report slug (d-tag)
+     * @returns The report content or null if not found
+     */
+    async readReport(slug: string): Promise<string | null> {
+        const reportPath = this.getReportPath(slug);
+
+        if (!existsSync(reportPath)) {
+            return null;
+        }
+
+        try {
+            const content = await readFile(reportPath, "utf-8");
+            return content;
+        } catch (error) {
+            logger.warn("📁 Failed to read local report", {
+                slug,
+                path: reportPath,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }
+
+    /**
+     * Read a report's metadata from local storage
+     * @param slug The report slug (d-tag)
+     * @returns The metadata or null if not found
+     */
+    async readMetadata(slug: string): Promise<LocalReportMetadata | null> {
+        const metadataPath = this.getMetadataPath(slug);
+
+        if (!existsSync(metadataPath)) {
+            return null;
+        }
+
+        try {
+            const content = await readFile(metadataPath, "utf-8");
+            return JSON.parse(content) as LocalReportMetadata;
+        } catch (error) {
+            logger.warn("📁 Failed to read local report metadata", {
+                slug,
+                path: metadataPath,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }
+
+    /**
+     * Check if a report exists locally
+     * @param slug The report slug (d-tag)
+     */
+    exists(slug: string): boolean {
+        return existsSync(this.getReportPath(slug));
+    }
+
+    /**
+     * Check if a Nostr event is newer than the local copy
+     * Used for hydration from subscription
+     * @param slug The report slug (d-tag)
+     * @param eventCreatedAt The Nostr event's created_at timestamp
+     * @returns true if the event is newer and should update the local copy
+     */
+    async isNewerThanLocal(slug: string, eventCreatedAt: number): Promise<boolean> {
+        const metadata = await this.readMetadata(slug);
+
+        if (!metadata) {
+            // No local copy exists, so the event is "newer"
+            return true;
+        }
+
+        // Compare timestamps
+        return eventCreatedAt > metadata.createdAt;
+    }
+
+    /**
+     * Hydrate local storage from a Nostr event if it's newer
+     * @param slug The report slug (d-tag)
+     * @param content The report content
+     * @param addressableRef The addressable reference in NIP-33 format (kind:pubkey:identifier)
+     * @param createdAt The Nostr event's created_at timestamp
+     * @returns true if the local copy was updated
+     */
+    async hydrateFromNostr(
+        slug: string,
+        content: string,
+        addressableRef: string,
+        createdAt: number
+    ): Promise<boolean> {
+        const isNewer = await this.isNewerThanLocal(slug, createdAt);
+
+        if (!isNewer) {
+            logger.debug("📁 Skipping hydration - local copy is current or newer", {
+                slug,
+                eventCreatedAt: createdAt,
+            });
+            return false;
+        }
+
+        await this.writeReport(slug, content, {
+            addressableRef,
+            createdAt,
+            slug,
+        });
+
+        logger.info("📁 Hydrated local report from Nostr", {
+            slug,
+            addressableRef: addressableRef.substring(0, 20),
+            createdAt,
+        });
+
+        return true;
+    }
+
+    /**
+     * Check if a path is within the reports directory
+     * Used to block direct writes via fs_write
+     * Uses secure path normalization to prevent path traversal attacks.
+     * @param path The path to check
+     * @throws Error if the store has not been initialized
+     */
+    isPathInReportsDir(path: string): boolean {
+        // CRITICAL: Throw if not initialized to prevent silent bypass of protection
+        if (!this.isInitialized()) {
+            throw new Error(
+                "LocalReportStore.isPathInReportsDir() called before initialization. " +
+                "This indicates a bug - the store must be initialized during project startup."
+            );
+        }
+
+        // Use secure path containment check that handles .., symlinks, case differences
+        return isPathWithinDirectory(path, this.getReportsDir());
+    }
+
+    /**
+     * Reset the store (for testing purposes)
+     */
+    reset(): void {
+        this._basePath = null;
+        this._projectId = null;
+    }
+}
+
+/**
+ * Create a new LocalReportStore instance.
+ * Each project should have its own instance managed by ProjectContext.
+ */
+export function createLocalReportStore(): LocalReportStore {
+    return new LocalReportStore();
+}
+
+/**
+ * Get the LocalReportStore for the current project context.
+ * This is a convenience function that gets the store from ProjectContext.
+ *
+ * @throws Error if called outside of a project context
+ */
+export function getLocalReportStore(): LocalReportStore {
+    const context = getProjectContext();
+    if (!context.localReportStore) {
+        throw new Error(
+            "LocalReportStore not available in project context. " +
+            "This indicates a bug - the store should be initialized during project startup."
+        );
+    }
+    return context.localReportStore;
+}