dexto 1.8.5 → 1.8.6

package/dist/cli/commands/span/register.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from 'commander';
+export interface SpanCommandRegisterContext {
+    program: Command;
+}
+export declare function registerSpanCommand({ program }: SpanCommandRegisterContext): void;
+//# sourceMappingURL=register.d.ts.map

package/dist/cli/commands/span/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/span/register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGzC,MAAM,WAAW,0BAA0B;IACvC,OAAO,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,mBAAmB,CAAC,EAAE,OAAO,EAAE,EAAE,0BAA0B,GAAG,IAAI,CAwBjF"}

package/dist/cli/commands/span/register.js

@@ -0,0 +1,25 @@
+import { withAnalytics, safeExit, ExitSignal } from '../../../analytics/wrapper.js';
+export function registerSpanCommand({ program }) {
+    const span = program.command('span').description('Inspect hosted run spans from Dexto Cloud');
+    span.command('list <runId>')
+        .description('List spans for a hosted run')
+        .option('--json', 'Print the raw span list response as JSON')
+        .option('--limit <count>', 'Maximum number of spans to return')
+        .option('--name <spanName>', 'Filter to an exact span name')
+        .option('--platform-url <url>', 'Use a custom Dexto platform URL')
+        .option('--sort <sort>', 'Sort by started_at or duration')
+        .option('--status <status>', 'Filter to a span status')
+        .action(withAnalytics('span:list', async (runId, options) => {
+        try {
+            const { handleSpanListCommand } = await import('../trace/index.js');
+            await handleSpanListCommand(runId, options);
+            safeExit('span:list', 0);
+        }
+        catch (err) {
+            if (err instanceof ExitSignal)
+                throw err;
+            console.error(`❌ dexto span list command failed: ${err}`);
+            safeExit('span:list', 1, 'error');
+        }
+    }));
+}

package/dist/cli/commands/trace/client.d.ts

@@ -0,0 +1,98 @@
+import { z } from 'zod';
+declare const RunTraceSpanSchema: z.ZodObject<{
+    attributes: z.ZodUnknown;
+    durationMs: z.ZodNullable<z.ZodNumber>;
+    endedAt: z.ZodNullable<z.ZodString>;
+    errorCode: z.ZodNullable<z.ZodString>;
+    errorMessage: z.ZodNullable<z.ZodString>;
+    id: z.ZodString;
+    name: z.ZodString;
+    parentSpanId: z.ZodNullable<z.ZodString>;
+    runAttemptId: z.ZodNullable<z.ZodString>;
+    runId: z.ZodString;
+    sessionId: z.ZodNullable<z.ZodString>;
+    spanId: z.ZodString;
+    startedAt: z.ZodString;
+    status: z.ZodEnum<{
+        failed: "failed";
+        completed: "completed";
+        cancelled: "cancelled";
+        running: "running";
+    }>;
+    traceId: z.ZodString;
+}, z.core.$loose>;
+declare const RunTraceSchema: z.ZodObject<{
+    events: z.ZodArray<z.ZodObject<{
+        attributes: z.ZodUnknown;
+        eventId: z.ZodString;
+        name: z.ZodString;
+        occurredAt: z.ZodString;
+        runId: z.ZodString;
+        runSpanId: z.ZodString;
+    }, z.core.$loose>>;
+    spans: z.ZodArray<z.ZodObject<{
+        attributes: z.ZodUnknown;
+        durationMs: z.ZodNullable<z.ZodNumber>;
+        endedAt: z.ZodNullable<z.ZodString>;
+        errorCode: z.ZodNullable<z.ZodString>;
+        errorMessage: z.ZodNullable<z.ZodString>;
+        id: z.ZodString;
+        name: z.ZodString;
+        parentSpanId: z.ZodNullable<z.ZodString>;
+        runAttemptId: z.ZodNullable<z.ZodString>;
+        runId: z.ZodString;
+        sessionId: z.ZodNullable<z.ZodString>;
+        spanId: z.ZodString;
+        startedAt: z.ZodString;
+        status: z.ZodEnum<{
+            failed: "failed";
+            completed: "completed";
+            cancelled: "cancelled";
+            running: "running";
+        }>;
+        traceId: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+declare const RunTraceSummarySchema: z.ZodObject<{
+    durationMs: z.ZodNumber;
+    errorCount: z.ZodNumber;
+    eventCount: z.ZodNumber;
+    firstSpanStartedAt: z.ZodString;
+    lastSpanStartedAt: z.ZodString;
+    runId: z.ZodString;
+    sessionId: z.ZodString;
+    spanCount: z.ZodNumber;
+    spanNames: z.ZodArray<z.ZodString>;
+    status: z.ZodString;
+}, z.core.$loose>;
+export type RunTrace = z.output<typeof RunTraceSchema>;
+export type RunTraceSpan = z.output<typeof RunTraceSpanSchema>;
+export type RunTraceSummary = z.output<typeof RunTraceSummarySchema>;
+export interface TraceClientOptions {
+    platformUrl?: string | undefined;
+}
+export interface RequestOptions {
+    signal?: AbortSignal | undefined;
+}
+export interface FetchRunTraceOptions extends RequestOptions {
+}
+export interface ListRunTracesOptions extends RequestOptions {
+    limit?: number | undefined;
+    period?: string | undefined;
+    sessionId?: string | undefined;
+    status?: string | undefined;
+}
+export interface ListRunSpansOptions extends RequestOptions {
+    limit?: number | undefined;
+    name?: string | undefined;
+    sort?: 'started_at' | 'duration' | undefined;
+    status?: string | undefined;
+}
+export declare function resolveTracePlatformUrl(platformUrl?: string): string;
+export declare function createTraceClient(options?: TraceClientOptions): {
+    fetchRunTrace(runId: string, fetchOptions?: FetchRunTraceOptions): Promise<RunTrace>;
+    listRunSpans(runId: string, listOptions?: ListRunSpansOptions): Promise<RunTraceSpan[]>;
+    listRunTraces(listOptions?: ListRunTracesOptions): Promise<RunTraceSummary[]>;
+};
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/cli/commands/trace/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/trace/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;iBAkBN,CAAC;AAanB,QAAA,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAKF,CAAC;AAQnB,QAAA,MAAM,qBAAqB;;;;;;;;;;;iBAaT,CAAC;AAcnB,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AACvD,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC/D,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAErE,MAAM,WAAW,kBAAkB;IAC/B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED,MAAM,WAAW,cAAc;IAC3B,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CACpC;AAED,MAAM,WAAW,oBAAqB,SAAQ,cAAc;CAAG;AAE/D,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IACxD,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAoB,SAAQ,cAAc;IACvD,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,IAAI,CAAC,EAAE,YAAY,GAAG,UAAU,GAAG,SAAS,CAAC;IAC7C,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED,wBAAgB,uBAAuB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAOpE;AAiDD,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB;yBAsB/C,MAAM,iBACC,oBAAoB,GACnC,OAAO,CAAC,QAAQ,CAAC;wBAUT,MAAM,gBACA,mBAAmB,GACjC,OAAO,CAAC,YAAY,EAAE,CAAC;gCAYO,oBAAoB,GAAQ,OAAO,CAAC,eAAe,EAAE,CAAC;EAY9F"}

package/dist/cli/commands/trace/client.js

@@ -0,0 +1,150 @@
+import { z } from 'zod';
+import { DEXTO_PLATFORM_URL } from '../../auth/constants.js';
+import { getDextoApiKey } from '../../auth/service.js';
+const TRACE_REQUEST_TIMEOUT_MS = 10_000;
+const RunTraceSpanStatusSchema = z.enum(['running', 'completed', 'failed', 'cancelled']);
+const RunTraceSpanSchema = z
+    .object({
+    attributes: z.unknown(),
+    durationMs: z.number().nullable(),
+    endedAt: z.string().nullable(),
+    errorCode: z.string().nullable(),
+    errorMessage: z.string().nullable(),
+    id: z.string(),
+    name: z.string(),
+    parentSpanId: z.string().nullable(),
+    runAttemptId: z.string().nullable(),
+    runId: z.string(),
+    sessionId: z.string().nullable(),
+    spanId: z.string(),
+    startedAt: z.string(),
+    status: RunTraceSpanStatusSchema,
+    traceId: z.string(),
+})
+    .passthrough();
+const RunTraceEventSchema = z
+    .object({
+    attributes: z.unknown(),
+    eventId: z.string(),
+    name: z.string(),
+    occurredAt: z.string(),
+    runId: z.string(),
+    runSpanId: z.string(),
+})
+    .passthrough();
+const RunTraceSchema = z
+    .object({
+    events: z.array(RunTraceEventSchema),
+    spans: z.array(RunTraceSpanSchema),
+})
+    .passthrough();
+const RunTraceResponseSchema = z
+    .object({
+    trace: RunTraceSchema,
+})
+    .passthrough();
+const RunTraceSummarySchema = z
+    .object({
+    durationMs: z.number(),
+    errorCount: z.number(),
+    eventCount: z.number(),
+    firstSpanStartedAt: z.string(),
+    lastSpanStartedAt: z.string(),
+    runId: z.string(),
+    sessionId: z.string(),
+    spanCount: z.number(),
+    spanNames: z.array(z.string()),
+    status: z.string(),
+})
+    .passthrough();
+const RunTraceListResponseSchema = z
+    .object({
+    traces: z.array(RunTraceSummarySchema),
+})
+    .passthrough();
+const RunSpansResponseSchema = z
+    .object({
+    spans: z.array(RunTraceSpanSchema),
+})
+    .passthrough();
+export function resolveTracePlatformUrl(platformUrl) {
+    const rawUrl = platformUrl?.trim() || DEXTO_PLATFORM_URL;
+    if (rawUrl.trim().length === 0) {
+        throw new Error('Dexto platform URL is empty.');
+    }
+    return rawUrl.replace(/\/+$/, '');
+}
+async function resolveTraceApiKey() {
+    const apiKey = await getDextoApiKey();
+    if (!apiKey?.trim()) {
+        throw new Error('Authentication required. Run `dexto login` before using `dexto trace`.');
+    }
+    return apiKey.trim();
+}
+async function parseJsonResponse(response) {
+    const contentType = response.headers.get('content-type') ?? '';
+    if (!contentType.toLowerCase().includes('application/json')) {
+        return null;
+    }
+    return response.json().catch(() => null);
+}
+function formatHttpFailure(status, payload) {
+    if (payload && typeof payload === 'object' && 'error' in payload) {
+        return `${status} ${JSON.stringify(payload)}`;
+    }
+    return `${status}`;
+}
+function appendOptionalSearchParam(url, key, value) {
+    if (value === undefined) {
+        return;
+    }
+    url.searchParams.set(key, String(value));
+}
+function createRequestSignal(signal) {
+    const timeoutSignal = AbortSignal.timeout(TRACE_REQUEST_TIMEOUT_MS);
+    if (!signal) {
+        return timeoutSignal;
+    }
+    return AbortSignal.any([signal, timeoutSignal]);
+}
+export function createTraceClient(options = {}) {
+    const platformBaseUrl = resolveTracePlatformUrl(options.platformUrl);
+    async function fetchJson(path, fetchOptions = {}) {
+        const response = await fetch(`${platformBaseUrl}${path}`, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${await resolveTraceApiKey()}`,
+            },
+            signal: createRequestSignal(fetchOptions.signal),
+        });
+        const payload = await parseJsonResponse(response);
+        if (!response.ok) {
+            throw new Error(`Trace request failed: ${formatHttpFailure(response.status, payload)}`);
+        }
+        return payload;
+    }
+    return {
+        async fetchRunTrace(runId, fetchOptions = {}) {
+            const payload = await fetchJson(`/api/runs/${encodeURIComponent(runId)}/trace`, fetchOptions);
+            return RunTraceResponseSchema.parse(payload).trace;
+        },
+        async listRunSpans(runId, listOptions = {}) {
+            const url = new URL(`${platformBaseUrl}/api/runs/${encodeURIComponent(runId)}/spans`);
+            appendOptionalSearchParam(url, 'limit', listOptions.limit);
+            appendOptionalSearchParam(url, 'name', listOptions.name);
+            appendOptionalSearchParam(url, 'sort', listOptions.sort);
+            appendOptionalSearchParam(url, 'status', listOptions.status);
+            const payload = await fetchJson(`${url.pathname}${url.search}`, listOptions);
+            return RunSpansResponseSchema.parse(payload).spans;
+        },
+        async listRunTraces(listOptions = {}) {
+            const url = new URL(`${platformBaseUrl}/api/runs/traces`);
+            appendOptionalSearchParam(url, 'limit', listOptions.limit);
+            appendOptionalSearchParam(url, 'period', listOptions.period);
+            appendOptionalSearchParam(url, 'sessionId', listOptions.sessionId);
+            appendOptionalSearchParam(url, 'status', listOptions.status);
+            const payload = await fetchJson(`${url.pathname}${url.search}`, listOptions);
+            return RunTraceListResponseSchema.parse(payload).traces;
+        },
+    };
+}

package/dist/cli/commands/trace/format.d.ts

@@ -0,0 +1,5 @@
+import type { RunTrace, RunTraceSpan, RunTraceSummary } from './client.js';
+export declare function formatTraceSummary(runId: string, trace: RunTrace): string;
+export declare function formatTraceList(traces: RunTraceSummary[]): string;
+export declare function formatSpanList(runId: string, spans: RunTraceSpan[]): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/cli/commands/trace/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/trace/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAc3E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,MAAM,CAsBzE;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,CAkBjE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,MAAM,CAoB3E"}

package/dist/cli/commands/trace/format.js

@@ -0,0 +1,58 @@
+function formatDuration(span) {
+    return span.durationMs === null ? 'running' : `${span.durationMs}ms`;
+}
+function formatDurationMs(durationMs) {
+    return durationMs === null ? 'running' : `${durationMs}ms`;
+}
+function sortSpans(spans) {
+    return [...spans].sort((left, right) => left.startedAt.localeCompare(right.startedAt));
+}
+export function formatTraceSummary(runId, trace) {
+    const lines = [
+        `Run trace ${runId}`,
+        `Spans: ${trace.spans.length}  Events: ${trace.events.length}`,
+    ];
+    if (trace.spans.length === 0) {
+        lines.push('No spans found.');
+        return lines.join('\n');
+    }
+    lines.push('');
+    for (const span of sortSpans(trace.spans)) {
+        lines.push(`${span.startedAt}  ${span.status.padEnd(9)}  ${formatDuration(span).padStart(8)}  ${span.name}`);
+        if (span.errorMessage) {
+            lines.push(`  error: ${span.errorMessage}`);
+        }
+    }
+    return lines.join('\n');
+}
+export function formatTraceList(traces) {
+    if (traces.length === 0) {
+        return 'No run traces found.';
+    }
+    const lines = ['Recent run traces', ''];
+    for (const trace of traces) {
+        const names = trace.spanNames.slice(0, 5).join(', ');
+        lines.push(`${trace.lastSpanStartedAt}  ${trace.status.padEnd(16)}  spans=${String(trace.spanCount).padStart(2)}  errors=${trace.errorCount}  duration=${formatDurationMs(trace.durationMs).padStart(8)}  ${trace.runId}`);
+        lines.push(`  session: ${trace.sessionId}`);
+        if (names.length > 0) {
+            lines.push(`  spans: ${names}`);
+        }
+    }
+    return lines.join('\n');
+}
+export function formatSpanList(runId, spans) {
+    const lines = [`Spans for run ${runId}`, `Count: ${spans.length}`];
+    if (spans.length === 0) {
+        lines.push('No spans found.');
+        return lines.join('\n');
+    }
+    lines.push('');
+    for (const span of spans) {
+        lines.push(`${span.startedAt}  ${span.status.padEnd(9)}  ${formatDuration(span).padStart(8)}  ${span.name}`);
+        lines.push(`  span: ${span.spanId}  trace: ${span.traceId}`);
+        if (span.errorMessage) {
+            lines.push(`  error: ${span.errorMessage}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/cli/commands/trace/index.d.ts

@@ -0,0 +1,21 @@
+export interface TraceCommandOptions {
+    json?: boolean | undefined;
+    platformUrl?: string | undefined;
+}
+export interface TraceListCommandOptions extends TraceCommandOptions {
+    limit?: string | number | undefined;
+    period?: string | undefined;
+    session?: string | undefined;
+    status?: string | undefined;
+}
+export interface SpanListCommandOptions extends TraceCommandOptions {
+    limit?: string | number | undefined;
+    name?: string | undefined;
+    sort?: 'started_at' | 'duration' | undefined;
+    status?: string | undefined;
+}
+export declare function handleTraceCommand(runId: string, options?: TraceCommandOptions): Promise<void>;
+export declare function handleTraceViewCommand(runId: string, options?: TraceCommandOptions): Promise<void>;
+export declare function handleTraceListCommand(options?: TraceListCommandOptions): Promise<void>;
+export declare function handleSpanListCommand(runId: string, options?: SpanListCommandOptions): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/commands/trace/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/trace/index.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,mBAAmB;IAChC,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IAChE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACpC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IAC/D,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACpC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,IAAI,CAAC,EAAE,YAAY,GAAG,UAAU,GAAG,SAAS,CAAC;IAC7C,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAeD,wBAAsB,kBAAkB,CACpC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,mBAAwB,GAClC,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,sBAAsB,CACxC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,mBAAwB,GAClC,OAAO,CAAC,IAAI,CAAC,CAWf;AAED,wBAAsB,sBAAsB,CAAC,OAAO,GAAE,uBAA4B,GAAG,OAAO,CAAC,IAAI,CAAC,CAcjG;AAED,wBAAsB,qBAAqB,CACvC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,sBAA2B,GACrC,OAAO,CAAC,IAAI,CAAC,CAiBf"}

package/dist/cli/commands/trace/index.js

@@ -0,0 +1,49 @@
+import { createTraceClient } from './client.js';
+import { formatSpanList, formatTraceList, formatTraceSummary } from './format.js';
+function parsePositiveInteger(value, fallback) {
+    if (value === undefined) {
+        return fallback;
+    }
+    const parsed = typeof value === 'number' ? value : Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new Error(`Expected a positive integer, received ${String(value)}.`);
+    }
+    return parsed;
+}
+export async function handleTraceCommand(runId, options = {}) {
+    await handleTraceViewCommand(runId, options);
+}
+export async function handleTraceViewCommand(runId, options = {}) {
+    const trace = await createTraceClient({ platformUrl: options.platformUrl }).fetchRunTrace(runId);
+    if (options.json) {
+        console.log(JSON.stringify({ trace }, null, 2));
+        return;
+    }
+    console.log(formatTraceSummary(runId, trace));
+}
+export async function handleTraceListCommand(options = {}) {
+    const traces = await createTraceClient({ platformUrl: options.platformUrl }).listRunTraces({
+        limit: parsePositiveInteger(options.limit, 20),
+        ...(options.period === undefined ? {} : { period: options.period }),
+        ...(options.session === undefined ? {} : { sessionId: options.session }),
+        ...(options.status === undefined ? {} : { status: options.status }),
+    });
+    if (options.json) {
+        console.log(JSON.stringify({ traces }, null, 2));
+        return;
+    }
+    console.log(formatTraceList(traces));
+}
+export async function handleSpanListCommand(runId, options = {}) {
+    const spans = await createTraceClient({ platformUrl: options.platformUrl }).listRunSpans(runId, {
+        limit: parsePositiveInteger(options.limit, 100),
+        ...(options.name === undefined ? {} : { name: options.name }),
+        ...(options.sort === undefined ? {} : { sort: options.sort }),
+        ...(options.status === undefined ? {} : { status: options.status }),
+    });
+    if (options.json) {
+        console.log(JSON.stringify({ spans }, null, 2));
+        return;
+    }
+    console.log(formatSpanList(runId, spans));
+}

package/dist/cli/commands/trace/register.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from 'commander';
+export interface TraceCommandRegisterContext {
+    program: Command;
+}
+export declare function registerTraceCommand({ program }: TraceCommandRegisterContext): void;
+//# sourceMappingURL=register.d.ts.map

package/dist/cli/commands/trace/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/trace/register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGzC,MAAM,WAAW,2BAA2B;IACxC,OAAO,EAAE,OAAO,CAAC;CACpB;AAOD,wBAAgB,oBAAoB,CAAC,EAAE,OAAO,EAAE,EAAE,2BAA2B,GAAG,IAAI,CAuEnF"}

package/dist/cli/commands/trace/register.js

@@ -0,0 +1,71 @@
+import { withAnalytics, safeExit, ExitSignal } from '../../../analytics/wrapper.js';
+export function registerTraceCommand({ program }) {
+    const trace = program
+        .command('trace [runId]')
+        .description('Discover and fetch hosted run traces from Dexto Cloud')
+        .option('--json', 'Print the raw trace response as JSON')
+        .option('--platform-url <url>', 'Use a custom Dexto platform URL')
+        .action(withAnalytics('trace', async (runId, options) => {
+        try {
+            if (!runId) {
+                trace.help();
+                return;
+            }
+            const { handleTraceCommand } = await import('./index.js');
+            await handleTraceCommand(runId, options);
+            safeExit('trace', 0);
+        }
+        catch (err) {
+            if (err instanceof ExitSignal)
+                throw err;
+            console.error(`❌ dexto trace command failed: ${err}`);
+            safeExit('trace', 1, 'error');
+        }
+    }));
+    trace
+        .command('list')
+        .description('List recent hosted run traces')
+        .option('--json', 'Print the raw trace list response as JSON')
+        .option('--limit <count>', 'Maximum number of traces to return')
+        .option('--period <period>', 'Filter to a recent period such as 15m, 3h, or 7d')
+        .option('--platform-url <url>', 'Use a custom Dexto platform URL')
+        .option('--session <sessionId>', 'Filter to a session id')
+        .option('--status <status>', 'Filter to a run status')
+        .action(withAnalytics('trace:list', async (options) => {
+        try {
+            const { handleTraceListCommand } = await import('./index.js');
+            await handleTraceListCommand({
+                ...trace.opts(),
+                ...options,
+            });
+            safeExit('trace:list', 0);
+        }
+        catch (err) {
+            if (err instanceof ExitSignal)
+                throw err;
+            console.error(`❌ dexto trace list command failed: ${err}`);
+            safeExit('trace:list', 1, 'error');
+        }
+    }));
+    trace
+        .command('view <runId>')
+        .description('Fetch one hosted run trace')
+        .option('--json', 'Print the raw trace response as JSON')
+        .option('--platform-url <url>', 'Use a custom Dexto platform URL')
+        .action(withAnalytics('trace:view', async (runId, options) => {
+        try {
+            const { handleTraceViewCommand } = await import('./index.js');
+            await handleTraceViewCommand(runId, {
+                ...trace.opts(),
+                ...options,
+            });
+            safeExit('trace:view', 0);
+        }
+        catch (err) {
+            if (err instanceof ExitSignal)
+                throw err;
+            console.error(`❌ dexto trace view command failed: ${err}`);
+            safeExit('trace:view', 1, 'error');
+        }
+    }));
+}

package/dist/index-main.js

@@ -60,6 +60,8 @@ import { registerImageCommand } from './cli/commands/image/register.js';
 import { registerPluginCommand } from './cli/commands/plugin/register.js';
 import { registerAgentsCommand } from './cli/commands/agents/register.js';
 import { registerDeployCommand } from './cli/commands/deploy/register.js';
+import { registerSpanCommand } from './cli/commands/span/register.js';
+import { registerTraceCommand } from './cli/commands/trace/register.js';
 import { registerInitCommand } from './cli/commands/init.js';
 import { ensureImageImporterConfigured } from './cli/utils/image-importer.js';
 const program = new Command();
@@ -143,6 +145,8 @@ program
 }));
 registerImageCommand({ program });
 registerDeployCommand({ program });
+registerSpanCommand({ program });
+registerTraceCommand({ program });
 registerInitCommand({ program });
 // 4) `init-app` SUB-COMMAND
 program

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dexto",
-  "version": "1.8.5",
+  "version": "1.8.6",
   "type": "module",
   "bin": {
     "dexto": "./dist/index.js"
@@ -34,18 +34,18 @@
     "ws": "^8.18.1",
     "yaml": "^2.8.3",
     "zod": "^4.3.6",
-    "@dexto/agent-config": "1.8.5",
-    "@dexto/agent-management": "1.8.5",
-    "@dexto/analytics": "1.8.5",
-    "@dexto/client-sdk": "1.8.5",
-    "@dexto/core": "1.8.5",
-    "@dexto/image-local": "1.8.5",
-    "@dexto/image-logger-agent": "1.8.5",
-    "@dexto/llm": "1.8.5",
-    "@dexto/registry": "1.8.5",
-    "@dexto/server": "1.8.5",
-    "@dexto/storage": "1.8.5",
-    "@dexto/tui": "1.8.5"
+    "@dexto/agent-config": "1.8.6",
+    "@dexto/agent-management": "1.8.6",
+    "@dexto/analytics": "1.8.6",
+    "@dexto/client-sdk": "1.8.6",
+    "@dexto/core": "1.8.6",
+    "@dexto/image-local": "1.8.6",
+    "@dexto/image-logger-agent": "1.8.6",
+    "@dexto/llm": "1.8.6",
+    "@dexto/registry": "1.8.6",
+    "@dexto/server": "1.8.6",
+    "@dexto/storage": "1.8.6",
+    "@dexto/tui": "1.8.6"
   },
   "devDependencies": {
     "@types/ws": "^8.5.11",