/** Minimal trace store contract for RelayCore to record delivery spans. */
export interface TraceStoreLike {
  insertSpan(span: {
    messageId: string;
    traceId: string;
    subject: string;
    status?: string;
    metadata?: Record<string, unknown>;
  }): void;
}

// 9. Record trace span for delivery tracking
if (this.traceStore) {
  try {
    this.traceStore.insertSpan({
      messageId,
      traceId: messageId,
      subject,
      status: deliveredTo > 0 ? 'delivered' : 'failed',
      metadata: {
        deliveredTo,
        rejectedCount: rejected.length,
        hasAdapterResult: !!adapterResult,
        durationMs: Date.now() - new Date(envelope.createdAt).getTime(),
      },
    });
  } catch {
    // Trace insertion is best-effort — never fail a publish for tracing
  }
}

it('records trace span when traceStore is provided', async () => {
  const mockTraceStore = { insertSpan: vi.fn() };
  const core = createRelayCore({ traceStore: mockTraceStore });
  // register an endpoint so delivery succeeds
  await core.registerEndpoint('relay.test.subject');
  await core.publish('relay.test.subject', { content: 'hello' }, {
    from: 'relay.test.sender',
    replyTo: 'relay.test.sender',
  });
  expect(mockTraceStore.insertSpan).toHaveBeenCalledWith(
    expect.objectContaining({
      subject: 'relay.test.subject',
      status: 'delivered',
    }),
  );
});

it('records failed trace span for dead-lettered messages', async () => {
  const mockTraceStore = { insertSpan: vi.fn() };
  const core = createRelayCore({ traceStore: mockTraceStore });
  await core.publish('relay.nowhere.subject', { content: 'lost' }, {
    from: 'relay.test.sender',
    replyTo: 'relay.test.sender',
  });
  expect(mockTraceStore.insertSpan).toHaveBeenCalledWith(
    expect.objectContaining({
      status: 'failed',
    }),
  );
});

git add packages/relay/src/types.ts packages/relay/src/relay-core.ts packages/relay/src/__tests__/relay-core.test.ts apps/server/src/
git commit -m "fix(relay): wire trace store into publish pipeline for delivery tracking"

import { describe, it, expect, vi } from 'vitest';
import { resolveSubjectLabel, type SubjectLabel } from '../subject-resolver.js';

describe('resolveSubjectLabel', () => {
  it('resolves relay.human.console.* to "You"', async () => {
    const result = await resolveSubjectLabel('relay.human.console.abc-123', {});
    expect(result).toEqual({ label: 'You', raw: 'relay.human.console.abc-123' });
  });

  it('resolves relay.system.console to "System Console"', async () => {
    const result = await resolveSubjectLabel('relay.system.console', {});
    expect(result).toEqual({ label: 'System Console', raw: 'relay.system.console' });
  });

  it('resolves relay.system.pulse.* to "Pulse Scheduler"', async () => {
    const result = await resolveSubjectLabel('relay.system.pulse.sched-1', {});
    expect(result).toEqual({ label: 'Pulse Scheduler', raw: 'relay.system.pulse.sched-1' });
  });

  it('resolves relay.agent.{sessionId} to agent name when available', async () => {
    const mockGetSession = vi.fn().mockResolvedValue({ cwd: '/path/to/project' });
    const mockReadManifest = vi.fn().mockResolvedValue({ name: 'Obsidian Repo' });
    const result = await resolveSubjectLabel('relay.agent.abc-123-def', {
      getSession: mockGetSession,
      readManifest: mockReadManifest,
    });
    expect(result).toEqual({ label: 'Obsidian Repo', raw: 'relay.agent.abc-123-def' });
  });

  it('falls back to truncated session ID when agent not found', async () => {
    const mockGetSession = vi.fn().mockResolvedValue({ cwd: '/path' });
    const mockReadManifest = vi.fn().mockResolvedValue(null);
    const result = await resolveSubjectLabel('relay.agent.abc-123-def', {
      getSession: mockGetSession,
      readManifest: mockReadManifest,
    });
    expect(result).toEqual({ label: 'Agent (abc-123)', raw: 'relay.agent.abc-123-def' });
  });

  it('falls back gracefully when session lookup fails', async () => {
    const mockGetSession = vi.fn().mockRejectedValue(new Error('not found'));
    const result = await resolveSubjectLabel('relay.agent.abc-123-def', {
      getSession: mockGetSession,
    });
    expect(result).toEqual({ label: 'Agent (abc-123)', raw: 'relay.agent.abc-123-def' });
  });
});

/**
 * Resolve relay subject strings into human-readable labels.
 *
 * @module services/relay/subject-resolver
 */

export interface SubjectLabel {
  label: string;
  raw: string;
}

interface ResolverDeps {
  getSession?: (sessionId: string) => Promise<{ cwd?: string } | null>;
  readManifest?: (cwd: string) => Promise<{ name?: string } | null>;
}

const SESSION_ID_PREVIEW_LENGTH = 7;

/**
 * Resolve a relay subject string into a human-readable label.
 *
 * @param subject - Raw relay subject string
 * @param deps - Optional dependency injection for session/manifest lookup
 */
export async function resolveSubjectLabel(
  subject: string,
  deps: ResolverDeps,
): Promise<SubjectLabel> {
  const raw = subject;

  // Static patterns
  if (subject === 'relay.system.console') {
    return { label: 'System Console', raw };
  }
  if (subject.startsWith('relay.system.pulse.')) {
    return { label: 'Pulse Scheduler', raw };
  }
  if (subject.startsWith('relay.human.console.')) {
    return { label: 'You', raw };
  }

  // Agent pattern — resolve name from manifest
  if (subject.startsWith('relay.agent.')) {
    const sessionId = subject.slice('relay.agent.'.length);
    const shortId = sessionId.slice(0, SESSION_ID_PREVIEW_LENGTH);
    const fallback: SubjectLabel = { label: `Agent (${shortId})`, raw };

    if (!deps.getSession) return fallback;

    try {
      const session = await deps.getSession(sessionId);
      if (!session?.cwd || !deps.readManifest) return fallback;

      const manifest = await deps.readManifest(session.cwd);
      if (!manifest?.name) return fallback;

      return { label: manifest.name, raw };
    } catch {
      return fallback;
    }
  }

  // Unknown pattern
  return { label: subject, raw };
}

/**
 * Batch-resolve multiple subjects, deduplicating lookups.
 *
 * @param subjects - Array of raw subject strings
 * @param deps - Dependency injection for session/manifest lookup
 */
export async function resolveSubjectLabels(
  subjects: string[],
  deps: ResolverDeps,
): Promise<Map<string, SubjectLabel>> {
  const unique = [...new Set(subjects)];
  const results = await Promise.all(
    unique.map(async (s) => [s, await resolveSubjectLabel(s, deps)] as const),
  );
  return new Map(results);
}

git add apps/server/src/services/relay/subject-resolver.ts apps/server/src/services/relay/__tests__/subject-resolver.test.ts
git commit -m "feat(relay): add subject label resolver for human-readable names"

export const SubjectLabelSchema = z.object({
  label: z.string(),
  raw: z.string(),
});

export const RelayConversationSchema = z.object({
  id: z.string(),
  direction: z.enum(['outbound', 'inbound']),
  status: z.enum(['delivered', 'failed', 'pending']),
  from: SubjectLabelSchema,
  to: SubjectLabelSchema,
  preview: z.string(),
  payload: z.unknown().optional(),
  responseCount: z.number(),
  sentAt: z.string(),
  completedAt: z.string().optional(),
  durationMs: z.number().optional(),
  subject: z.string(),
  sessionId: z.string().optional(),
  clientId: z.string().optional(),
  traceId: z.string().optional(),
  failureReason: z.string().optional(),
});

export type RelayConversation = z.infer<typeof RelayConversationSchema>;

/** List relay conversations (grouped request/response exchanges). */
listRelayConversations(): Promise<{ conversations: RelayConversation[] }>;

async listRelayConversations() {
  const res = await this.fetch('/api/relay/conversations');
  return res.json();
},

// GET /conversations — Grouped request/response exchanges with human labels
router.get('/conversations', async (_req, res) => {
  try {
    const messages = relayCore.listMessages({});
    const deadLetters = relayCore.getDeadLetters();

    // Import resolver
    const { resolveSubjectLabels } = await import(
      '../services/relay/subject-resolver.js'
    );
    const { transcriptReader } = await import(
      '../services/core/transcript-reader.js'
    );
    const { readManifest } = await import('@dorkos/shared/manifest');

    // Collect all unique subjects
    const allSubjects = [
      ...messages.messages.map((m: { subject: string }) => m.subject),
    ];
    const resolverDeps = {
      getSession: async (id: string) => transcriptReader.getSession(id),
      readManifest: async (cwd: string) => readManifest(cwd),
    };
    const labelMap = await resolveSubjectLabels(allSubjects, resolverDeps);

    // Separate requests (relay.agent.*) from response chunks (relay.human.console.*)
    const requests: Array<Record<string, unknown>> = [];
    const responseChunksBySubject = new Map<string, Array<Record<string, unknown>>>();

    for (const msg of messages.messages as Array<Record<string, unknown>>) {
      const subject = msg.subject as string;
      if (subject.startsWith('relay.agent.') || subject.startsWith('relay.system.')) {
        requests.push(msg);
      } else if (subject.startsWith('relay.human.console.')) {
        const existing = responseChunksBySubject.get(subject) ?? [];
        existing.push(msg);
        responseChunksBySubject.set(subject, existing);
      }
    }

    // Build conversations from requests
    const conversations = requests.map((req) => {
      const subject = req.subject as string;
      const messageId = req.id as string;
      const status = req.status as string;
      const createdAt = req.createdAt as string;

      // Extract session ID from subject
      const sessionId = subject.startsWith('relay.agent.')
        ? subject.slice('relay.agent.'.length)
        : undefined;

      // Find response chunks (matched by the request's from field being the response subject)
      // For now, use the most recent relay.human.console.* group
      const fromSubject = req.from as string | undefined;
      const responseChunks = fromSubject
        ? (responseChunksBySubject.get(fromSubject) ?? [])
        : [];
      const lastChunk = responseChunks[0]; // messages are sorted newest-first

      // Resolve dead letter info
      const deadLetter = deadLetters.find(
        (dl: { messageId: string }) => dl.messageId === messageId,
      );

      // Build preview from dead letter envelope (has full payload) or from the message
      let preview = '';
      let payload: unknown = undefined;
      if (deadLetter?.envelope?.payload) {
        payload = deadLetter.envelope.payload;
        const p = payload as Record<string, unknown>;
        const text = p?.content ?? p?.text ?? p?.message;
        preview = typeof text === 'string' ? text.slice(0, 120) : JSON.stringify(payload).slice(0, 120);
      }

      const fromLabel = labelMap.get(fromSubject ?? '') ?? { label: 'Unknown', raw: fromSubject ?? '' };
      const toLabel = labelMap.get(subject) ?? { label: subject, raw: subject };

      return {
        id: messageId,
        direction: 'outbound' as const,
        status: status === 'cur' || status === 'delivered' ? 'delivered' as const
          : status === 'failed' ? 'failed' as const
          : 'pending' as const,
        from: fromLabel,
        to: toLabel,
        preview,
        payload,
        responseCount: responseChunks.length,
        sentAt: createdAt,
        completedAt: lastChunk?.createdAt as string | undefined,
        durationMs: lastChunk
          ? new Date(lastChunk.createdAt as string).getTime() - new Date(createdAt).getTime()
          : undefined,
        subject,
        sessionId,
        traceId: messageId,
        failureReason: deadLetter?.reason as string | undefined,
      };
    });

    return res.json({ conversations });
  } catch (err) {
    const message = err instanceof Error ? err.message : 'Failed to build conversations';
    return res.status(500).json({ error: message });
  }
});

import { useQuery } from '@tanstack/react-query';
import { useTransport } from '@/layers/shared/model';
import type { RelayConversation } from '@dorkos/shared/relay-schemas';

export const RELAY_CONVERSATIONS_KEY = ['relay', 'conversations'] as const;

/** Fetch grouped relay conversations with human-readable labels. */
export function useRelayConversations(enabled = true) {
  const transport = useTransport();
  return useQuery<{ conversations: RelayConversation[] }>({
    queryKey: [...RELAY_CONVERSATIONS_KEY],
    queryFn: () => transport.listRelayConversations(),
    enabled,
    refetchInterval: 5000,
  });
}

export { useRelayConversations } from './model/use-relay-conversations';

git add packages/shared/src/relay-schemas.ts packages/shared/src/transport.ts apps/client/src/layers/shared/lib/http-transport.ts apps/server/src/routes/relay.ts apps/client/src/layers/entities/relay/
git commit -m "feat(relay): add conversations endpoint with grouped messages and human labels"

import { useState } from 'react';
import { motion, AnimatePresence } from 'motion/react';
import {
  Check,
  AlertTriangle,
  Clock,
  ChevronDown,
  ChevronRight,
} from 'lucide-react';
import { Badge } from '@/layers/shared/ui';
import { cn } from '@/layers/shared/lib';
import { MessageTrace } from './MessageTrace';
import { getStatusBorderColor } from '../lib/status-colors';
import type { RelayConversation } from '@dorkos/shared/relay-schemas';

interface ConversationRowProps {
  conversation: RelayConversation;
}

const STATUS_CONFIG = {
  delivered: { icon: Check, className: 'text-green-600 dark:text-green-400', label: 'Delivered', dot: 'bg-green-500' },
  failed: { icon: AlertTriangle, className: 'text-destructive', label: 'Failed', dot: 'bg-red-500' },
  pending: { icon: Clock, className: 'text-muted-foreground', label: 'Pending', dot: 'bg-blue-500' },
} as const;

function formatTimeAgo(dateStr: string): string {
  const diff = Date.now() - new Date(dateStr).getTime();
  const seconds = Math.floor(diff / 1000);
  if (seconds < 60) return `${seconds}s ago`;
  const minutes = Math.floor(seconds / 60);
  if (minutes < 60) return `${minutes}m ago`;
  const hours = Math.floor(minutes / 60);
  if (hours < 24) return `${hours}h ago`;
  return `${Math.floor(hours / 24)}d ago`;
}

function formatTime(dateStr: string): string {
  return new Date(dateStr).toLocaleTimeString([], { hour: 'numeric', minute: '2-digit', second: '2-digit' });
}

function formatDuration(ms: number): string {
  if (ms < 1000) return `${ms}ms`;
  return `${(ms / 1000).toFixed(1)}s`;
}

/** Conversation card with progressive disclosure: human labels → payload → technical details. */
export function ConversationRow({ conversation }: ConversationRowProps) {
  const [expanded, setExpanded] = useState(false);
  const [showTechnical, setShowTechnical] = useState(false);
  const [showTrace, setShowTrace] = useState(false);

  const config = STATUS_CONFIG[conversation.status];
  const borderColor = getStatusBorderColor(conversation.status);

  const outcome = conversation.status === 'delivered'
    ? conversation.responseCount > 0
      ? `delivered · ${conversation.responseCount} chunks`
      : 'delivered'
    : conversation.failureReason ?? config.label.toLowerCase();

  return (
    <div
      className={cn(
        'w-full rounded-lg border border-l-2 text-left transition-colors hover:bg-muted/50 hover:shadow-sm',
        borderColor,
        expanded && 'bg-muted/30',
      )}
    >
      {/* Collapsed view — human-readable only */}
      <button
        type="button"
        onClick={() => setExpanded(!expanded)}
        className="w-full p-3"
      >
        <div className="flex items-center gap-2">
          <span className={cn('size-2 shrink-0 rounded-full', config.dot)} />
          <span className="min-w-0 flex-1 truncate text-sm font-medium">
            {conversation.from.label}
            <span className="mx-1.5 text-muted-foreground">→</span>
            {conversation.to.label}
          </span>
          <span className="shrink-0 text-xs text-muted-foreground">
            {formatTimeAgo(conversation.sentAt)}
          </span>
        </div>
        <div className="mt-1 flex items-center gap-2">
          {conversation.preview && (
            <span className="min-w-0 flex-1 truncate text-sm text-muted-foreground">
              "{conversation.preview}"
            </span>
          )}
          <span className={cn('shrink-0 text-xs', config.className)}>
            {outcome}
          </span>
        </div>
      </button>

      {/* Expanded view — payload + delivery details */}
      <AnimatePresence initial={false}>
        {expanded && (
          <motion.div
            initial={{ height: 0, opacity: 0 }}
            animate={{ height: 'auto', opacity: 1 }}
            exit={{ height: 0, opacity: 0 }}
            transition={{ duration: 0.2, ease: 'easeOut' }}
            className="overflow-hidden"
          >
            <div className="space-y-3 border-t px-3 pb-3 pt-3">
              {/* Payload */}
              {conversation.payload != null && (
                <div>
                  <span className="text-xs font-medium text-muted-foreground">Payload</span>
                  <pre className="mt-1 max-h-40 overflow-auto rounded bg-muted p-2 font-mono text-xs">
                    {JSON.stringify(conversation.payload, null, 2)}
                  </pre>
                </div>
              )}

              {/* Delivery timing */}
              <div className="text-xs text-muted-foreground">
                <span>Sent {formatTime(conversation.sentAt)}</span>
                {conversation.completedAt && (
                  <span> · Completed {formatTime(conversation.completedAt)}</span>
                )}
                {conversation.durationMs != null && (
                  <span> · Duration: {formatDuration(conversation.durationMs)}</span>
                )}
                {conversation.responseCount > 0 && (
                  <span> · {conversation.responseCount} response chunks</span>
                )}
              </div>

              {/* Failure reason */}
              {conversation.failureReason && (
                <div className="rounded bg-destructive/10 px-2 py-1 text-xs text-destructive">
                  {conversation.failureReason}
                </div>
              )}

              {/* Technical Details accordion */}
              <button
                type="button"
                onClick={(e) => { e.stopPropagation(); setShowTechnical(!showTechnical); }}
                className="flex items-center gap-1.5 text-xs text-muted-foreground hover:text-foreground"
              >
                {showTechnical ? <ChevronDown className="size-3.5" /> : <ChevronRight className="size-3.5" />}
                Technical Details
              </button>
              <AnimatePresence initial={false}>
                {showTechnical && (
                  <motion.div
                    initial={{ height: 0, opacity: 0 }}
                    animate={{ height: 'auto', opacity: 1 }}
                    exit={{ height: 0, opacity: 0 }}
                    transition={{ duration: 0.15 }}
                    className="overflow-hidden"
                  >
                    <dl className="grid grid-cols-[auto_1fr] gap-x-3 gap-y-1 text-xs">
                      <dt className="text-muted-foreground">Subject</dt>
                      <dd className="truncate font-mono">{conversation.subject}</dd>
                      {conversation.sessionId && (
                        <>
                          <dt className="text-muted-foreground">Session</dt>
                          <dd className="font-mono">{conversation.sessionId.slice(0, 8)}</dd>
                        </>
                      )}
                      {conversation.traceId && (
                        <>
                          <dt className="text-muted-foreground">Trace ID</dt>
                          <dd className="font-mono">{conversation.traceId.slice(0, 12)}…</dd>
                        </>
                      )}
                      <dt className="text-muted-foreground">From (raw)</dt>
                      <dd className="truncate font-mono">{conversation.from.raw}</dd>
                      <dt className="text-muted-foreground">To (raw)</dt>
                      <dd className="truncate font-mono">{conversation.to.raw}</dd>
                    </dl>
                  </motion.div>
                )}
              </AnimatePresence>

              {/* Trace Timeline accordion */}
              {conversation.traceId && (
                <>
                  <button
                    type="button"
                    onClick={(e) => { e.stopPropagation(); setShowTrace(!showTrace); }}
                    className="flex items-center gap-1.5 text-xs text-muted-foreground hover:text-foreground"
                  >
                    {showTrace ? <ChevronDown className="size-3.5" /> : <ChevronRight className="size-3.5" />}
                    Trace Timeline
                  </button>
                  <AnimatePresence initial={false}>
                    {showTrace && (
                      <motion.div
                        initial={{ height: 0, opacity: 0 }}
                        animate={{ height: 'auto', opacity: 1 }}
                        exit={{ height: 0, opacity: 0 }}
                        transition={{ duration: 0.15 }}
                        className="overflow-hidden"
                      >
                        <MessageTrace messageId={conversation.traceId} onClose={() => setShowTrace(false)} />
                      </motion.div>
                    )}
                  </AnimatePresence>
                </>
              )}
            </div>
          </motion.div>
        )}
      </AnimatePresence>
    </div>
  );
}

git add apps/client/src/layers/features/relay/ui/ConversationRow.tsx apps/client/src/layers/features/relay/ui/ActivityFeed.tsx
git commit -m "feat(relay): replace MessageRow with ConversationRow for human-readable activity feed"

"hello" → Agent (a6010b)    No matching endpoints    4h ago

01KJG7Z6ZQAFXRTMB1WQKS1MQM    Unknown    4h ago

git add apps/client/src/layers/features/relay/ui/DeadLetterSection.tsx
git commit -m "feat(relay): show human-readable labels and message preview in dead letters"

/** Resolve a relay subject to a human-friendly label (client-side, no server calls). */
export function resolveSubjectLabelLocal(subject: string): string {
  if (subject === 'relay.system.console') return 'System Console';
  if (subject.startsWith('relay.system.pulse.')) return 'Pulse Scheduler';
  if (subject.startsWith('relay.human.console.')) return 'Your Browser Session';
  if (subject.startsWith('relay.agent.')) {
    const id = subject.slice('relay.agent.'.length);
    return `Agent (${id.slice(0, 7)})`;
  }
  return subject;
}

git add apps/client/src/layers/features/relay/lib/resolve-label.ts apps/client/src/layers/features/relay/ui/EndpointList.tsx apps/client/src/layers/features/relay/ui/AdapterCard.tsx
git commit -m "feat(relay): add human-readable labels to endpoints and adapter descriptions"

git add apps/client/src/layers/features/relay/ui/ActivityFeed.tsx
git commit -m "feat(relay): rename filter labels to human-friendly terms"

git add -A
git commit -m "feat(relay): complete conversation view with human labels, payload display, and trace fixes"