proteum 2.1.0-2 → 2.1.0-3

package/agents/project/tests/AGENTS.md

@@ -1,9 +1,12 @@
-# Codex guidance for writing E2E tests
+# E2E Tests
 
-- Understand the typical user flow and the main feature branches
-- Favor as many tests as possible to cover real usage
-- Always locate elements via their `data-testid` attribute
-- Add `data-testid` where needed
-- Keep test files clean, organized and structured
-- Test the current controller/page runtime model, not legacy `@Route` or `api.fetch` behavior
-- Reuse root catalog files from `/client/catalogs/**`, `/server/catalogs/**`, or `/common/catalogs/**` instead of duplicating catalog constants inside tests
+This file adds test-area local rules on top of the canonical framework contract:
+
+- framework repo: `agents/framework/AGENTS.md`
+- installed app: `./node_modules/proteum/agents/framework/AGENTS.md`
+
+- Understand the real user flow and the main feature branches before writing tests.
+- Test the current controller/page runtime model, not legacy `@Route` or `api.fetch` behavior.
+- Locate elements with `data-testid`.
+- Add `data-testid` where needed instead of relying on brittle selectors.
+- Reuse root catalog files from `/client/catalogs/**`, `/server/catalogs/**`, or `/common/catalogs/**` instead of duplicating catalog constants in tests.

package/cli/commands/dev.ts

@@ -155,6 +155,7 @@ async function startApp(app: App) {
                         await renderServerReadyBanner({
                             appName: getDevAppName(app),
                             publicUrl: message.publicUrl,
+                            routerPort: app.env.router.port,
                         }),
                     );
                 })();

package/cli/commands/trace.ts

@@ -0,0 +1,210 @@
+import fs from 'fs-extra';
+import got from 'got';
+import path from 'path';
+import yaml from 'yaml';
+import { UsageError } from 'clipanion';
+
+import cli from '..';
+import type {
+    TRequestTrace,
+    TRequestTraceArmResponse,
+    TRequestTraceErrorResponse,
+    TRequestTraceListItem,
+    TRequestTraceListResponse,
+    TRequestTraceResponse,
+} from '@common/dev/requestTrace';
+
+type TTraceAction = 'latest' | 'show' | 'requests' | 'arm' | 'export';
+
+const allowedActions = new Set<TTraceAction>(['latest', 'show', 'requests', 'arm', 'export']);
+
+class TraceResponseError extends UsageError {}
+
+const getAction = () => {
+    const action = typeof cli.args.action === 'string' && cli.args.action ? cli.args.action : 'latest';
+    if (!allowedActions.has(action as TTraceAction)) {
+        throw new UsageError(`Unsupported trace action "${action}". Expected one of: ${[...allowedActions].join(', ')}.`);
+    }
+
+    return action as TTraceAction;
+};
+
+const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '');
+
+const getRouterPort = () => {
+    const overridePort = typeof cli.args.port === 'string' && cli.args.port ? cli.args.port : '';
+    if (overridePort) return overridePort;
+
+    const envFilepath = path.join(cli.args.workdir as string, 'env.yaml');
+    if (!fs.existsSync(envFilepath)) {
+        throw new UsageError(`Could not find env.yaml in ${cli.args.workdir as string}. Pass --port or --url explicitly.`);
+    }
+
+    const envFile = yaml.parse(fs.readFileSync(envFilepath, 'utf8')) as { router?: { port?: number } };
+    const port = envFile.router?.port;
+    if (!port) {
+        throw new UsageError(`Could not determine the router port from ${envFilepath}. Pass --port or --url explicitly.`);
+    }
+
+    return String(port);
+};
+
+const getRouterBaseUrls = () => {
+    const explicitUrl = typeof cli.args.url === 'string' && cli.args.url ? cli.args.url.trim() : '';
+    if (explicitUrl) return [normalizeBaseUrl(explicitUrl)];
+
+    const port = getRouterPort();
+    return [...new Set([`http://127.0.0.1:${port}`, `http://localhost:${port}`, `http://[::1]:${port}`])];
+};
+
+const getTraceErrorMessage = (body: TRequestTraceErrorResponse | object | string | undefined, statusCode: number) => {
+    if (typeof body === 'object' && body !== null && 'error' in body && typeof body.error === 'string') {
+        return body.error;
+    }
+
+    return `Trace request failed with status ${statusCode}.`;
+};
+
+const requestJson = async <TResponse>(pathname: string, options?: { method?: 'GET' | 'POST'; json?: object }) => {
+    const attempts: string[] = [];
+
+    for (const baseUrl of getRouterBaseUrls()) {
+        try {
+            const response = await got(`${baseUrl}${pathname}`, {
+                method: options?.method || 'GET',
+                json: options?.json,
+                responseType: 'json',
+                throwHttpErrors: false,
+                retry: { limit: 0 },
+            });
+
+            if (response.statusCode >= 400) {
+                throw new TraceResponseError(
+                    getTraceErrorMessage(response.body as TRequestTraceErrorResponse | object | string | undefined, response.statusCode),
+                );
+            }
+
+            return response.body as TResponse;
+        } catch (error) {
+            if (error instanceof TraceResponseError) throw error;
+
+            const message = error instanceof Error ? error.message : String(error);
+            attempts.push(`${baseUrl}${pathname}: ${message}`);
+        }
+    }
+
+    throw new UsageError(
+        [
+            'Could not reach the Proteum trace server.',
+            ...attempts.map((attempt) => `- ${attempt}`),
+            'Make sure the app is running with `proteum dev`, or pass `--url http://host:port` if it is bound elsewhere.',
+        ].join('\n'),
+    );
+};
+
+const renderTraceSummary = (request: TRequestTraceListItem) =>
+    [
+        `${request.id} ${request.method} ${request.path}`,
+        `status=${request.statusCode ?? 'pending'}`,
+        `capture=${request.capture}`,
+        `events=${request.eventCount}`,
+        request.user ? `user=${request.user}` : '',
+        request.errorMessage ? `error=${request.errorMessage}` : '',
+    ]
+        .filter(Boolean)
+        .join(' | ');
+
+const renderTrace = (request: TRequestTrace) =>
+    [
+        `Request ${request.id}`,
+        `- ${request.method} ${request.path} status=${request.statusCode ?? 'pending'} capture=${request.capture}`,
+        `- started=${request.startedAt} durationMs=${request.durationMs ?? 'pending'} events=${request.events.length} dropped=${request.droppedEvents}`,
+        ...(request.user ? [`- user=${request.user}`] : []),
+        ...(request.persistedFilepath ? [`- persisted=${request.persistedFilepath}`] : []),
+        'Events',
+        ...request.events.map(
+            (event) =>
+                `- [${event.elapsedMs}ms] ${event.type} ${Object.entries(event.details)
+                    .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
+                    .join(' ')}`,
+        ),
+    ].join('\n');
+
+const printJson = (value: object) => {
+    console.log(JSON.stringify(value, null, 2));
+};
+
+export const run = async () => {
+    const action = getAction();
+    const requestId = typeof cli.args.id === 'string' ? cli.args.id : '';
+    const shouldPrintJson = cli.args.json === true;
+
+    if (action === 'requests') {
+        const response = await requestJson<TRequestTraceListResponse>('/__proteum/trace/requests');
+        if (shouldPrintJson) {
+            printJson(response);
+            return;
+        }
+
+        console.log(['Proteum trace', ...response.requests.map(renderTraceSummary)].join('\n'));
+        return;
+    }
+
+    if (action === 'arm') {
+        const capture = typeof cli.args.capture === 'string' && cli.args.capture ? cli.args.capture : 'deep';
+        const response = await requestJson<TRequestTraceArmResponse>('/__proteum/trace/arm', {
+            method: 'POST',
+            json: { capture },
+        });
+
+        if (shouldPrintJson) {
+            printJson(response);
+            return;
+        }
+
+        console.log(`Armed next request trace with capture=${response.capture}.`);
+        return;
+    }
+
+    if (action === 'latest') {
+        const response = await requestJson<TRequestTraceResponse>('/__proteum/trace/latest');
+        if (shouldPrintJson) {
+            printJson(response);
+            return;
+        }
+
+        console.log(renderTrace(response.request));
+        return;
+    }
+
+    if (!requestId) {
+        throw new UsageError(`Trace action "${action}" requires a request id.`);
+    }
+
+    const response = await requestJson<TRequestTraceResponse>(`/__proteum/trace/requests/${requestId}`);
+
+    if (action === 'show') {
+        if (shouldPrintJson) {
+            printJson(response);
+            return;
+        }
+
+        console.log(renderTrace(response.request));
+        return;
+    }
+
+    const output =
+        typeof cli.args.output === 'string' && cli.args.output
+            ? cli.args.output
+            : path.join(cli.args.workdir as string, 'var', 'traces', 'exports', `${response.request.id}.json`);
+
+    fs.ensureDirSync(path.dirname(output));
+    fs.writeJSONSync(output, response.request, { spaces: 2 });
+
+    if (shouldPrintJson) {
+        printJson({ output, request: response.request });
+        return;
+    }
+
+    console.log(`Exported trace ${response.request.id} to ${output}`);
+};

package/cli/compiler/client/index.ts

@@ -27,6 +27,24 @@ const hmrClientEntry = path.join(cli.paths.core.root, 'client', 'dev', 'hmr.ts')
 const normalizeModulePath = (value?: string) => (value || '').replace(/\\/g, '/');
 const resolveFromAppOrCore = (app: App, request: string) =>
     require.resolve(request, { paths: [app.paths.root, cli.paths.core.root] });
+const rewriteFrameworkAliasTargets = (app: App, aliases: Record<string, string | string[]>) => {
+    const installedCoreRoot = normalizeModulePath(path.join(app.paths.root, 'node_modules', 'proteum'));
+    const activeCoreRoot = normalizeModulePath(cli.paths.core.root);
+
+    if (installedCoreRoot === activeCoreRoot) return aliases;
+
+    const rewriteCandidate = (candidate: string) =>
+        normalizeModulePath(candidate).startsWith(installedCoreRoot + '/')
+            ? activeCoreRoot + normalizeModulePath(candidate).substring(installedCoreRoot.length)
+            : candidate;
+
+    return Object.fromEntries(
+        Object.entries(aliases).map(([alias, value]) => [
+            alias,
+            Array.isArray(value) ? value.map(rewriteCandidate) : rewriteCandidate(value),
+        ]),
+    );
+};
 
 const getModulePath = (module: Module) => {
     const resource = typeof module.nameForCondition === 'function' ? module.nameForCondition() : undefined;
@@ -58,6 +76,8 @@ export default function createCompiler(
     logVerbose(`Creating compiler for client (${mode}).`);
     const dev = mode === 'dev';
     const outputPath = app.outputPath(outputTarget);
+    const installedCoreRoot = path.join(app.paths.root, 'node_modules', 'proteum');
+    const frameworkRoots = [cli.paths.core.root, installedCoreRoot];
 
     const commonConfig = createCommonConfig(app, 'client', mode, outputTarget);
 
@@ -73,11 +93,12 @@ export default function createCompiler(
 
     // Convert tsconfig paths into bundler aliases.
     const { aliases } = app.aliases.client.forWebpack({ modulesPath: app.paths.root + '/node_modules' });
+    const resolvedAliases = rewriteFrameworkAliasTargets(app, aliases);
 
     // We're not supposed in any case to import server libs from client
-    delete aliases['@server'];
-    delete aliases['@/server'];
-    const rspackAliases = toRspackAliases(aliases);
+    delete resolvedAliases['@server'];
+    delete resolvedAliases['@/server'];
+    const rspackAliases = toRspackAliases(resolvedAliases);
     rspackAliases['@/client/router$'] = cli.paths.core.root + '/client/router.ts';
     rspackAliases['preact/jsx-runtime$'] = resolveFromAppOrCore(app, 'preact/jsx-runtime');
     rspackAliases['react/jsx-runtime$'] = resolveFromAppOrCore(app, 'preact/jsx-runtime');
@@ -133,16 +154,16 @@ export default function createCompiler(
                     test: ssrScriptPattern,
                     include: [
                         app.paths.root + '/client',
-                        cli.paths.core.root + '/client',
                         app.paths.client.generated,
 
                         app.paths.root + '/common',
-                        cli.paths.core.root + '/common',
                         app.paths.common.generated,
 
                         app.paths.root + '/server',
-                        cli.paths.core.root + '/server',
                         app.paths.server.generated,
+                        ...frameworkRoots.map((rootPath) => rootPath + '/client'),
+                        ...frameworkRoots.map((rootPath) => rootPath + '/common'),
+                        ...frameworkRoots.map((rootPath) => rootPath + '/server'),
                     ],
                     loader: path.join(
                         cli.paths.core.root,
@@ -157,17 +178,18 @@ export default function createCompiler(
                     test: regex.scripts,
                     include: [
                         app.paths.root + '/client',
-                        cli.paths.core.root + '/client',
                         app.paths.client.generated,
 
                         app.paths.root + '/common',
-                        cli.paths.core.root + '/common',
                         app.paths.common.generated,
 
                         // Prisma 7 generates browser-safe TypeScript entrypoints under var/prisma.
                         app.paths.root + '/var/prisma',
 
                         app.paths.server.generated + '/models.ts',
+                        ...frameworkRoots.map((rootPath) => rootPath + '/client'),
+                        ...frameworkRoots.map((rootPath) => rootPath + '/common'),
+                        ...frameworkRoots.map((rootPath) => rootPath + '/server'),
                     ],
                     rules: require('../common/scripts')({ app, side: 'client', dev }),
                 },

package/cli/compiler/server/index.ts

@@ -49,6 +49,25 @@ const getDevGeneratedRuntimeEntries = (app: App) => ({
     __proteum_dev_routes: [app.paths.server.generated + '/routes.ts'],
     __proteum_dev_controllers: [app.paths.server.generated + '/controllers.ts'],
 });
+const normalizeModulePath = (value?: string) => (value || '').replace(/\\/g, '/');
+const rewriteFrameworkAliasTargets = (app: App, aliases: Record<string, string | string[]>) => {
+    const installedCoreRoot = normalizeModulePath(app.paths.root + '/node_modules/proteum');
+    const activeCoreRoot = normalizeModulePath(cli.paths.core.root);
+
+    if (installedCoreRoot === activeCoreRoot) return aliases;
+
+    const rewriteCandidate = (candidate: string) =>
+        normalizeModulePath(candidate).startsWith(installedCoreRoot + '/')
+            ? activeCoreRoot + normalizeModulePath(candidate).substring(installedCoreRoot.length)
+            : candidate;
+
+    return Object.fromEntries(
+        Object.entries(aliases).map(([alias, value]) => [
+            alias,
+            Array.isArray(value) ? value.map(rewriteCandidate) : rewriteCandidate(value),
+        ]),
+    );
+};
 
 /*----------------------------------
 - CONFIG
@@ -61,14 +80,17 @@ export default function createCompiler(
     debug && console.info(`Creating compiler for server (${mode}).`);
     const dev = mode === 'dev';
     const outputPath = app.outputPath(outputTarget);
+    const installedCoreRoot = app.paths.root + '/node_modules/proteum';
+    const frameworkRoots = [cli.paths.core.root, installedCoreRoot];
 
     const commonConfig = createCommonConfig(app, 'server', mode, outputTarget);
     const { aliases } = app.aliases.server.forWebpack({ modulesPath: app.paths.root + '/node_modules' });
+    const resolvedAliases = rewriteFrameworkAliasTargets(app, aliases);
 
     // We're not supposed in any case to import client services from server
-    delete aliases['@client/services'];
-    delete aliases['@/client/services'];
-    const rspackAliases = toRspackAliases(aliases);
+    delete resolvedAliases['@client/services'];
+    delete resolvedAliases['@/client/services'];
+    const rspackAliases = toRspackAliases(resolvedAliases);
     rspackAliases['@/client/router$'] = cli.paths.core.root + '/client/router.ts';
 
     debug &&
@@ -154,11 +176,9 @@ export default function createCompiler(
                     test: regex.scripts,
                     include: [
                         app.paths.root + '/client',
-                        cli.paths.core.root + '/client',
                         app.paths.client.generated,
 
                         app.paths.root + '/common',
-                        cli.paths.core.root + '/common',
                         app.paths.common.generated,
 
                         // Prisma 7 generates TypeScript entrypoints under var/prisma.
@@ -166,8 +186,10 @@ export default function createCompiler(
 
                         // Dossiers server uniquement pour le bundle server
                         app.paths.root + '/server',
-                        cli.paths.core.root + '/server',
                         app.paths.server.generated,
+                        ...frameworkRoots.map((rootPath) => rootPath + '/client'),
+                        ...frameworkRoots.map((rootPath) => rootPath + '/common'),
+                        ...frameworkRoots.map((rootPath) => rootPath + '/server'),
 
                         // Complle 5HTP modules so they can refer to the framework instance and aliases
                         // Temp disabled because compile issue on vercel

package/cli/paths.ts

@@ -43,13 +43,28 @@ export const staticAssetName = /*isDebug ? '[name].[ext].[hash:8]' :*/ '[hash:8]
 
 const pathInfosDefaultOpts = { shortenExtensions: ['ts', 'js', 'tsx', 'jsx'], trimIndex: true };
 
+const safeRealpath = (filepath: string) => {
+    try {
+        return fs.realpathSync(filepath);
+    } catch {
+        return path.resolve(filepath);
+    }
+};
+
 const resolveCoreRoot = (appRoot: string) => {
+    const currentPackageRoot = path.resolve(__dirname, '..');
+    const currentBin = path.join(currentPackageRoot, 'cli', 'bin.js');
+    const invokedScript = process.argv[1] ? safeRealpath(process.argv[1]) : '';
+    const invokedCurrentPackage = invokedScript === safeRealpath(currentBin);
+
+    if (invokedCurrentPackage) return currentPackageRoot;
+
     const localInstall = path.join(appRoot, 'node_modules', 'proteum');
     if (fs.existsSync(localInstall)) return localInstall;
 
     // When running `npx`/global installs, there may be no local `node_modules/proteum` yet.
     // Fall back to the installed package root (this file lives in `<root>/cli`).
-    return path.resolve(__dirname, '..');
+    return currentPackageRoot;
 };
 
 const normalizeImportPath = (value: string) => value.replace(/\\/g, '/');

package/cli/presentation/commands.ts

@@ -13,6 +13,7 @@ export const proteumCommandNames = [
     'check',
     'doctor',
     'explain',
+    'trace',
 ] as const;
 
 export type TProteumCommandName = (typeof proteumCommandNames)[number];
@@ -45,7 +46,7 @@ export const proteumRecommendedFlow: TRow[] = [
 export const proteumCommandGroups: Array<{ title: string; names: TProteumCommandName[] }> = [
     { title: 'Daily workflow', names: ['dev', 'refresh', 'build'] },
     { title: 'Quality gates', names: ['typecheck', 'lint', 'check'] },
-    { title: 'Manifest and contracts', names: ['doctor', 'explain'] },
+    { title: 'Manifest and contracts', names: ['doctor', 'explain', 'trace'] },
     { title: 'Project scaffolding', names: ['init'] },
 ];
 
@@ -184,6 +185,27 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         notes: ['Legacy positional section selection remains supported, for example `proteum explain routes services`.'],
         status: 'stable',
     },
+    trace: {
+        name: 'trace',
+        category: 'Manifest and contracts',
+        summary: 'Inspect live in-memory request traces from a running Proteum dev server.',
+        usage: 'proteum trace [latest|show <requestId>|requests|arm|export <requestId>] [--port <port>|--url <baseUrl>] [--json]',
+        bestFor:
+            'Debugging route resolution, context creation, SSR payloads, renders, and runtime errors without attaching a debugger.',
+        examples: [
+            { description: 'Show the latest request trace', command: 'proteum trace latest' },
+            { description: 'List recent trace summaries', command: 'proteum trace requests' },
+            { description: 'Arm the next request for deep capture', command: 'proteum trace arm --capture deep' },
+            { description: 'Export a request trace to disk', command: 'proteum trace export <requestId>' },
+            { description: 'Target a custom dev base URL directly', command: 'proteum trace latest --url http://127.0.0.1:3010' },
+        ],
+        notes: [
+            'This command talks to the running app over the dev-only `__proteum/trace` HTTP endpoints.',
+            'Traces are stored in a bounded in-memory buffer with payload summarization and sensitive-field redaction.',
+            'Use `--port` when the app is not running on the router port declared in `env.yaml`, or `--url` when the host itself is non-standard.',
+        ],
+        status: 'experimental',
+    },
 };
 
 export const isLikelyProteumAppRoot = (workdir: string) =>

package/cli/presentation/devSession.ts

@@ -43,6 +43,8 @@ export const renderDevSession = async ({
                 { label: 'root', value: appRoot },
                 { label: 'router', value: `http://localhost:${routerPort}` },
                 { label: 'hmr', value: `http://localhost:${devEventPort}/__proteum_hmr` },
+                { label: 'trace', value: `proteum trace latest --port ${routerPort}` },
+                { label: 'trace deep', value: `proteum trace arm --capture deep --port ${routerPort}` },
                 { label: 'hotkeys', value: 'Ctrl+R reload, Ctrl+C stop' },
             ],
             { minLabelWidth: 12, maxLabelWidth: 12 },
@@ -52,9 +54,11 @@ export const renderDevSession = async ({
 export const renderServerReadyBanner = async ({
     appName,
     publicUrl,
+    routerPort,
 }: {
     appName: string;
     publicUrl: string;
+    routerPort: number;
 }) =>
     renderInk(({ Box, Text }) => {
         const createElement = React.createElement;
@@ -66,5 +70,6 @@ export const renderServerReadyBanner = async ({
             createElement(Text, { bold: true, color: 'green' }, appName),
             createElement(Text, { bold: true }, publicUrl),
             createElement(Text, { dimColor: true }, 'SSR server is listening for requests and hot reloads.'),
+            createElement(Text, { dimColor: true }, `Trace latest: proteum trace latest --port ${routerPort}`),
         );
     });

package/cli/runtime/commands.ts

@@ -185,6 +185,35 @@ class ExplainCommand extends ProteumCommand {
     }
 }
 
+class TraceCommand extends ProteumCommand {
+    public static paths = [['trace']];
+
+    public static usage = buildUsage('trace');
+
+    public port = Option.String('--port', { description: 'Override the router port used to query the running dev server.' });
+    public url = Option.String('--url', { description: 'Override the full base URL used to query the running dev server.' });
+    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    public capture = Option.String('--capture', { description: 'Capture mode used by `proteum trace arm`.' });
+    public output = Option.String('--output', { description: 'Output filepath used by `proteum trace export`.' });
+    public args = Option.Rest();
+
+    public async execute() {
+        const [action = 'latest', id = ''] = this.args;
+
+        this.setCliArgs({
+            action,
+            id,
+            port: this.port ?? '',
+            url: this.url ?? '',
+            json: this.json,
+            capture: this.capture ?? '',
+            output: this.output ?? '',
+        });
+
+        await runCommandModule(() => import('../commands/trace'));
+    }
+}
+
 export const registeredCommands = {
     init: InitCommand,
     dev: DevCommand,
@@ -195,6 +224,7 @@ export const registeredCommands = {
     check: CheckCommand,
     doctor: DoctorCommand,
     explain: ExplainCommand,
+    trace: TraceCommand,
 } as const;
 
 export const createCli = (version: string) => {
@@ -216,6 +246,7 @@ export const createCli = (version: string) => {
     clipanion.register(CheckCommand);
     clipanion.register(DoctorCommand);
     clipanion.register(ExplainCommand);
+    clipanion.register(TraceCommand);
 
     return clipanion;
 };

package/common/dev/requestTrace.ts

@@ -0,0 +1,81 @@
+export const traceCaptureModes = ['summary', 'resolve', 'deep'] as const;
+
+export type TTraceCaptureMode = (typeof traceCaptureModes)[number];
+
+export const traceEventTypes = [
+    'request.start',
+    'request.user',
+    'resolve.start',
+    'resolve.controller-route',
+    'resolve.routes-evaluated',
+    'resolve.route-skip',
+    'resolve.route-match',
+    'resolve.not-found',
+    'controller.start',
+    'controller.result',
+    'setup.options',
+    'context.create',
+    'page.data',
+    'ssr.payload',
+    'render.start',
+    'render.end',
+    'response.send',
+    'request.finish',
+    'error',
+] as const;
+
+export type TTraceEventType = (typeof traceEventTypes)[number];
+
+export type TTraceSummaryValue =
+    | PrimitiveValue
+    | null
+    | { kind: 'undefined' }
+    | { kind: 'redacted'; reason: string }
+    | { kind: 'bigint'; value: string }
+    | { kind: 'symbol'; value: string }
+    | { kind: 'function'; name: string }
+    | { kind: 'date'; value: string }
+    | { kind: 'error'; name: string; message: string; stack?: string }
+    | { kind: 'buffer'; byteLength: number }
+    | { kind: 'array'; length: number; items: TTraceSummaryValue[]; truncated: boolean }
+    | {
+          kind: 'object';
+          constructorName: string;
+          keys: string[];
+          entries: { [key: string]: TTraceSummaryValue };
+          truncated: boolean;
+      }
+    | { kind: 'map'; size: number }
+    | { kind: 'set'; size: number };
+
+export type TTraceEvent = {
+    index: number;
+    at: string;
+    elapsedMs: number;
+    type: TTraceEventType;
+    details: { [key: string]: TTraceSummaryValue };
+};
+
+export type TRequestTrace = {
+    id: string;
+    method: string;
+    path: string;
+    url: string;
+    capture: TTraceCaptureMode;
+    startedAt: string;
+    finishedAt?: string;
+    durationMs?: number;
+    statusCode?: number;
+    user?: string;
+    droppedEvents: number;
+    persistedFilepath?: string;
+    errorMessage?: string;
+    events: TTraceEvent[];
+};
+
+export type TRequestTraceListItem = Omit<TRequestTrace, 'events'> & { eventCount: number };
+
+export type TRequestTraceListResponse = { requests: TRequestTraceListItem[] };
+export type TRequestTraceResponse = { request: TRequestTrace };
+export type TRequestTraceArmResponse = { armed: true; capture: TTraceCaptureMode };
+export type TRequestTraceErrorResponse = { error: string };