@tenex-chat/backend 0.9.1

package/src/daemon/types.ts

@@ -0,0 +1,150 @@
+import type { Hexpubkey } from "@nostr-dev-kit/ndk";
+
+/**
+ * Branded type for Project IDs
+ * Format: "31933:authorPubkey:dTag"
+ *
+ * Using branded types provides compile-time safety to prevent
+ * mixing up regular strings with project IDs.
+ */
+export type ProjectId = string & { __brand: "ProjectId" };
+
+/**
+ * Event classification for daemon routing decisions
+ */
+export type EventClassification =
+    | "never_route" // Events that should never be routed (status, streaming, etc.)
+    | "project" // Project creation/update events (kind 31933)
+    | "lesson" // Agent lesson events (kind 4129)
+    | "conversation" // Reply and thread events
+    | "unknown"; // Unclassified events
+
+/**
+ * Routing decision for an event
+ * This is a discriminated union for type-safe routing handling
+ */
+export type RoutingDecision =
+    | {
+          type: "route_to_project";
+          projectId: ProjectId;
+          method: "a_tag" | "p_tag_agent";
+          matchedTags: string[];
+      }
+    | {
+          type: "dropped";
+          reason: string;
+      }
+    | {
+          type: "lesson_hydration";
+          targetProjects: ProjectId[];
+          agentDefinitionId: string;
+      }
+    | {
+          type: "project_event";
+          projectId: ProjectId;
+          isUpdate: boolean;
+      };
+
+/**
+ * Runtime action performed when routing an event
+ */
+export type RuntimeAction = "existing" | "started" | "crashed";
+
+/**
+ * Routing context containing all data needed for routing decisions
+ */
+export interface RoutingContext {
+    /** Known project IDs mapped to their NDKProject instances */
+    knownProjects: Map<ProjectId, unknown>; // Using unknown to avoid circular deps
+    /** Map of agent pubkeys to their project IDs */
+    agentPubkeyToProjects: Map<Hexpubkey, Set<ProjectId>>;
+    /** Whitelisted user pubkeys */
+    whitelistedPubkeys: Hexpubkey[];
+    /** Currently active runtime project IDs */
+    activeProjectIds: Set<ProjectId>;
+}
+
+/**
+ * Event routing result with telemetry metadata
+ */
+export interface EventRoutingResult {
+    decision: RoutingDecision;
+    timestamp: number;
+    eventId: string;
+    eventKind: number | undefined;
+    processingTimeMs?: number;
+}
+
+/**
+ * Runtime status for monitoring
+ */
+export interface RuntimeStatus {
+    projectId: ProjectId;
+    isRunning: boolean;
+    title: string;
+    startTime: Date | null;
+    lastEventTime: Date | null;
+    eventCount: number;
+    agentCount: number;
+    hasError?: boolean;
+    errorMessage?: string;
+}
+
+/**
+ * Daemon status for monitoring
+ */
+export interface DaemonStatus {
+    running: boolean;
+    knownProjects: number;
+    activeProjects: number;
+    startingProjects: number;
+    totalAgents: number;
+    uptime: number;
+    memoryUsage: NodeJS.MemoryUsage;
+}
+
+/**
+ * Subscription state for filter building
+ */
+export interface SubscriptionState {
+    whitelistedPubkeys: Set<Hexpubkey>;
+    knownProjects: Set<ProjectId>;
+    agentPubkeys: Set<Hexpubkey>;
+    agentDefinitionIds: Set<string>;
+    lastUpdate: Date;
+    restartPending: boolean;
+}
+
+/**
+ * Agent index entry for routing
+ */
+export interface AgentIndexEntry {
+    pubkey: Hexpubkey;
+    projectId: ProjectId;
+    name: string;
+    slug: string;
+}
+
+/**
+ * Event processing error types
+ */
+export enum EventProcessingError {
+    UnknownProject = "UNKNOWN_PROJECT",
+    NoRoutingMatch = "NO_ROUTING_MATCH",
+    RuntimeCrash = "RUNTIME_CRASH",
+    RuntimeStartupFailed = "RUNTIME_STARTUP_FAILED",
+    InvalidEvent = "INVALID_EVENT",
+}
+
+/**
+ * Lifecycle event types for telemetry
+ */
+export enum LifecycleEvent {
+    DaemonStart = "daemon.start",
+    DaemonStop = "daemon.stop",
+    RuntimeStart = "runtime.start",
+    RuntimeStop = "runtime.stop",
+    RuntimeCrash = "runtime.crash",
+    SubscriptionRestart = "subscription.restart",
+}
+

package/src/daemon/utils/routing-log.ts

@@ -0,0 +1,76 @@
+import type { NDKEvent } from "@nostr-dev-kit/ndk";
+import type { EventRoutingLogger } from "@/logging/EventRoutingLogger";
+import type { RoutingDecision } from "@/daemon/types";
+import { logger } from "@/utils/logger";
+
+/**
+ * Consolidated routing logging utilities to reduce verbosity
+ */
+
+export function logRoutingDecision(
+    routingLogger: EventRoutingLogger,
+    event: NDKEvent,
+    routingDecision: RoutingDecision,
+    targetProjectId: string | null,
+    routingMethod: "a_tag" | "p_tag_agent" | "none" = "none",
+    matchedTags: string[] = [],
+    reason?: string
+): Promise<void> {
+    // Convert complex RoutingDecision to simple string type for logger
+    const loggerDecision = routingDecision.type === "route_to_project" ? "routed" : routingDecision.type;
+
+    return routingLogger.logRoutingDecision({
+        event,
+        routingDecision: loggerDecision as "routed" | "dropped" | "project_event",
+        targetProjectId,
+        routingMethod,
+        matchedTags,
+        reason,
+    });
+}
+
+export function logDropped(
+    routingLogger: EventRoutingLogger,
+    event: NDKEvent,
+    reason: string
+): Promise<void> {
+    logger.debug(`Event dropped: ${reason}`, {
+        eventId: event.id?.slice(0, 8),
+        eventKind: event.kind,
+        reason,
+    });
+    const routingDecision: RoutingDecision = {
+        type: "dropped",
+        reason,
+    };
+    return logRoutingDecision(routingLogger, event, routingDecision, null, "none", [], reason);
+}
+
+export function logRouted(
+    routingLogger: EventRoutingLogger,
+    event: NDKEvent,
+    projectId: string,
+    method: "a_tag" | "p_tag_agent",
+    matchedTags: string[]
+): Promise<void> {
+    logger.debug("Routing event to project", {
+        eventId: event.id?.slice(0, 8),
+        projectId: projectId.slice(0, 16),
+        method,
+    });
+    const routingDecision: RoutingDecision = {
+        type: "route_to_project",
+        projectId: projectId as import("@/daemon/types").ProjectId,
+        method,
+        matchedTags,
+    };
+    return logRoutingDecision(
+        routingLogger,
+        event,
+        routingDecision,
+        projectId,
+        method,
+        matchedTags,
+        `Routed via ${method}`
+    );
+}

package/src/daemon/utils/telemetry.ts

@@ -0,0 +1,173 @@
+import type { NDKEvent } from "@nostr-dev-kit/ndk";
+import {
+    ROOT_CONTEXT,
+    SpanStatusCode,
+    propagation,
+    trace,
+    TraceFlags,
+    type Context,
+    type Span,
+    type SpanContext,
+} from "@opentelemetry/api";
+import { shortenConversationId } from "@/utils/conversation-id";
+import { AgentEventDecoder } from "@/nostr/AgentEventDecoder";
+import { TagExtractor } from "@/nostr/TagExtractor";
+import { getConversationSpanManager } from "@/telemetry/ConversationSpanManager";
+
+/**
+ * Convert a Nostr hex ID to OpenTelemetry traceID (32 hex chars)
+ * Uses shortened 12-char conversation ID and pads to 32 chars for OTEL format.
+ * This makes Jaeger trace URLs readable: /trace/83f83677f9c7 instead of /trace/83f83677f9c7211e1dcbcbf934e3884f
+ */
+function nostrIdToTraceId(nostrId: string): string {
+    // Use shortened 12-char ID (consistent with span attributes)
+    const shortId = shortenConversationId(nostrId);
+    // Pad to 32 chars with zeros (OTEL requirement)
+    return shortId.padEnd(32, "0");
+}
+
+/**
+ * Convert a Nostr hex ID to OpenTelemetry spanID (16 hex chars)
+ */
+function nostrIdToSpanId(nostrId: string): string {
+    return nostrId.substring(0, 16);
+}
+
+/**
+ * Create a trace context from Nostr event threading.
+ *
+ * This derives traceID from the conversation root (E tag) and parentSpanId
+ * from the reply-to event (e tag), enabling proper trace hierarchies based
+ * on Nostr's natural threading model.
+ */
+function createContextFromNostrEvent(event: NDKEvent): {
+    context: typeof ROOT_CONTEXT;
+    parentSpanId: string | undefined;
+    traceId: string;
+} {
+    // 1. Determine conversationId (becomes traceID)
+    // For root events (no e tag), use the event's own ID as conversation root
+    const conversationId = AgentEventDecoder.getReplyTarget(event) || event.id;
+    if (!conversationId) {
+        return { context: ROOT_CONTEXT, parentSpanId: undefined, traceId: "" };
+    }
+
+    const traceId = nostrIdToTraceId(conversationId);
+
+    // 2. Determine parent event ID from e-tag (the event this is replying to)
+    const parentEventId = TagExtractor.getFirstETag(event);
+    const parentSpanId = parentEventId ? nostrIdToSpanId(parentEventId) : undefined;
+
+    // 3. Create span context - if we have a parent, use its spanId; otherwise this is root
+    const spanContext: SpanContext = {
+        traceId,
+        // Use parent's span ID if this is a reply, otherwise use conversation root as the span
+        spanId: parentSpanId || nostrIdToSpanId(conversationId),
+        traceFlags: TraceFlags.SAMPLED,
+        isRemote: true,
+    };
+
+    // 4. Create context with this span context as parent
+    const parentContext = trace.setSpanContext(ROOT_CONTEXT, spanContext);
+
+    return { context: parentContext, parentSpanId, traceId };
+}
+
+/**
+ * Create a telemetry span for event processing with conversation-aware trace context.
+ *
+ * This function derives OpenTelemetry trace/span IDs from Nostr event threading:
+ * - traceID = first 32 chars of conversation root ID (all messages in a conversation share this)
+ * - parentSpanId = first 16 chars of reply-to event ID (creates parent-child hierarchy)
+ * - spanID = first 16 chars of this event's ID (unique per event)
+ *
+ * This enables viewing entire conversations as single traces in Jaeger with proper
+ * hierarchical relationships based on Nostr's e-tag threading.
+ */
+export function createEventSpan(event: NDKEvent): Span {
+    // First check for explicit trace_context tag (backwards compat with delegations)
+    const traceContextTag = event.tags.find((t) => t[0] === "trace_context");
+
+    let conversationId = AgentEventDecoder.getReplyTarget(event);
+    let derivedTraceId: string | undefined;
+
+    let parentContext: Context;
+    if (traceContextTag) {
+        // Use explicit W3C trace context if provided (delegation events)
+        const carrier = { traceparent: traceContextTag[1] };
+        parentContext = propagation.extract(ROOT_CONTEXT, carrier);
+    } else {
+        // Derive trace context from Nostr event threading
+        const derived = createContextFromNostrEvent(event);
+        parentContext = derived.context;
+        derivedTraceId = derived.traceId;
+    }
+
+    if (!conversationId && event.id) {
+        conversationId = event.id;
+    }
+
+    // Get reply-to event for attribute logging
+    const replyToEventId = TagExtractor.getFirstETag(event);
+
+    // Create span with conversation-aware context
+    const span = trace.getTracer("tenex.daemon").startSpan(
+        "tenex.event.process",
+        {
+            attributes: {
+                "event.id": event.id,
+                "event.kind": event.kind || 0,
+                "event.pubkey": event.pubkey,
+                "event.created_at": event.created_at || 0,
+                // Truncate content to avoid huge spans
+                "event.content": event.content.substring(0, 500),
+                "event.content_length": event.content.length,
+                "event.tag_count": event.tags.length,
+                "event.has_trace_context": !!traceContextTag,
+                "event.reply_to": replyToEventId || "",
+                "conversation.id": conversationId ? shortenConversationId(conversationId) : "unknown",
+                "conversation.is_root": !AgentEventDecoder.getReplyTarget(event),
+                "trace.derived_from_nostr": !traceContextTag && !!derivedTraceId,
+            },
+        },
+        parentContext
+    );
+
+    // Track message sequence
+    if (conversationId) {
+        getConversationSpanManager().incrementMessageCount(conversationId, span);
+    }
+
+    return span;
+}
+
+/**
+ * End span with success status
+ */
+export function endSpanSuccess(span: Span): void {
+    span.setStatus({ code: SpanStatusCode.OK });
+    span.end();
+}
+
+/**
+ * End span with error status
+ */
+export function endSpanError(span: Span, error: unknown): void {
+    span.recordException(error instanceof Error ? error : new Error(String(error)));
+    span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: error instanceof Error ? error.message : String(error),
+    });
+    span.end();
+}
+
+/**
+ * Add routing decision event to span
+ */
+export function addRoutingEvent(
+    span: Span,
+    decision: string,
+    details: Record<string, unknown>
+): void {
+    span.addEvent("routing_decision", { decision, ...details });
+}