@pixelbyte-software/pixcode 1.41.2 → 1.41.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixelbyte-software/pixcode",
-  "version": "1.41.2",
+  "version": "1.41.4",
   "description": "Self-hosted AI coding agent control room for Claude Code, Cursor CLI, OpenAI Codex, Gemini CLI, Qwen Code, and OpenCode with chat, files, shell, Git, orchestration, API keys, Telegram, MCP, plugins, themes, and desktop/server deployment.",
   "type": "module",
   "main": "dist-server/server/index.js",

package/scripts/smoke/live-view-diagnostics.mjs

@@ -39,8 +39,8 @@ assert.match(payload.errorDetail, /spawn php ENOENT/);
 assert.ok(payload.diagnostics.command.includes('php -S'), 'Payload should include the attempted PHP command.');
 assert.ok(payload.diagnostics.logs.some((line) => line.includes('spawn php ENOENT')), 'Payload should include process logs.');
 assert.ok(
-  payload.suggestions.some((suggestion) => /php/i.test(suggestion) && /PATH/i.test(suggestion)),
-  'PHP failures should suggest checking the php executable in PATH.',
+  payload.suggestions.some((suggestion) => /php/i.test(suggestion) && /local PHP runtime/i.test(suggestion)),
+  'PHP failures should explain that Pixcode can prepare a local PHP runtime.',
 );
 assert.notEqual(payload.error, 'Live View session not found.', 'Existing failed sessions must not be hidden as missing sessions.');
 

package/scripts/smoke/live-view-integration.mjs

@@ -1,4 +1,5 @@
 import { access, chmod, mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import net from 'node:net';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -10,6 +11,13 @@ const read = async (relativePath) => {
   return readFile(path.join(repoRoot, relativePath), 'utf8');
 };
 const fileExists = async (filePath) => access(filePath).then(() => true, () => false);
+const canBindLoopback = () => new Promise((resolve) => {
+  const server = net.createServer();
+  server.once('error', () => resolve(false));
+  server.listen(0, '127.0.0.1', () => {
+    server.close(() => resolve(true));
+  });
+});
 
 const appTypes = await read('src/types/app.ts');
 assert.ok(
@@ -386,53 +394,57 @@ const brokenStatus = await getManagedRuntimeStatus('frankenphp', {
 });
 assert.equal(brokenStatus.status, 'missing', 'Broken managed FrankenPHP manifests should be treated as missing so Pixcode can reinstall them.');
 
-const phpRuntimeEnvHome = path.join(workspace, 'php-runtime-env');
-const phpRuntimeCurrent = path.join(phpRuntimeEnvHome, 'frankenphp', 'current');
-await mkdir(phpRuntimeCurrent, { recursive: true });
-const phpRuntimeExecutable = path.join(phpRuntimeCurrent, process.platform === 'win32' ? 'frankenphp.cmd' : 'frankenphp');
-await writeFile(phpRuntimeExecutable, [
-  '#!/usr/bin/env node',
-  'const http = require("node:http");',
-  'const path = require("node:path");',
-  'const runtimeDir = __dirname;',
-  'if (process.argv.includes("version")) process.exit(0);',
-  'const pathValue = process.env.Path || process.env.PATH || "";',
-  'if (!pathValue.split(path.delimiter).includes(runtimeDir)) {',
-  '  console.error("runtime path missing from PATH");',
-  '  process.exit(1);',
-  '}',
-  'const port = Number(process.env.PORT || 0);',
-  'http.createServer((req, res) => res.end("php runtime ok")).listen(port, "127.0.0.1");',
-  '',
-].join('\n'));
-if (process.platform !== 'win32') {
-  await chmod(phpRuntimeExecutable, 0o755);
-}
-await writeFile(path.join(phpRuntimeEnvHome, 'frankenphp', 'pixcode-runtime.json'), JSON.stringify({
-  id: 'frankenphp',
-  label: 'Pixcode PHP runtime',
-  executablePath: phpRuntimeExecutable,
-  version: 'path-env-smoke',
-}, null, 2));
-const previousRuntimeHome = process.env.PIXCODE_MANAGED_RUNTIMES_HOME;
-process.env.PIXCODE_MANAGED_RUNTIMES_HOME = phpRuntimeEnvHome;
-try {
-  const phpRuntimeSession = await startLiveView('php-runtime-env-smoke', phpProject);
-  assert.equal(phpRuntimeSession.status, 'running', 'Managed PHP Live View should start with the runtime directory on PATH.');
-  await stopLiveView('php-runtime-env-smoke');
-} finally {
-  if (previousRuntimeHome === undefined) {
-    delete process.env.PIXCODE_MANAGED_RUNTIMES_HOME;
-  } else {
-    process.env.PIXCODE_MANAGED_RUNTIMES_HOME = previousRuntimeHome;
+if (await canBindLoopback()) {
+  const phpRuntimeEnvHome = path.join(workspace, 'php-runtime-env');
+  const phpRuntimeCurrent = path.join(phpRuntimeEnvHome, 'frankenphp', 'current');
+  await mkdir(phpRuntimeCurrent, { recursive: true });
+  const phpRuntimeExecutable = path.join(phpRuntimeCurrent, process.platform === 'win32' ? 'frankenphp.cmd' : 'frankenphp');
+  await writeFile(phpRuntimeExecutable, [
+    '#!/usr/bin/env node',
+    'const http = require("node:http");',
+    'const path = require("node:path");',
+    'const runtimeDir = __dirname;',
+    'if (process.argv.includes("version")) process.exit(0);',
+    'const pathValue = process.env.Path || process.env.PATH || "";',
+    'if (!pathValue.split(path.delimiter).includes(runtimeDir)) {',
+    '  console.error("runtime path missing from PATH");',
+    '  process.exit(1);',
+    '}',
+    'const port = Number(process.env.PORT || 0);',
+    'http.createServer((req, res) => res.end("php runtime ok")).listen(port, "127.0.0.1");',
+    '',
+  ].join('\n'));
+  if (process.platform !== 'win32') {
+    await chmod(phpRuntimeExecutable, 0o755);
+  }
+  await writeFile(path.join(phpRuntimeEnvHome, 'frankenphp', 'pixcode-runtime.json'), JSON.stringify({
+    id: 'frankenphp',
+    label: 'Pixcode PHP runtime',
+    executablePath: phpRuntimeExecutable,
+    version: 'path-env-smoke',
+  }, null, 2));
+  const previousRuntimeHome = process.env.PIXCODE_MANAGED_RUNTIMES_HOME;
+  process.env.PIXCODE_MANAGED_RUNTIMES_HOME = phpRuntimeEnvHome;
+  try {
+    const phpRuntimeSession = await startLiveView('php-runtime-env-smoke', phpProject);
+    assert.equal(phpRuntimeSession.status, 'running', 'Managed PHP Live View should start with the runtime directory on PATH.');
+    await stopLiveView('php-runtime-env-smoke');
+  } finally {
+    if (previousRuntimeHome === undefined) {
+      delete process.env.PIXCODE_MANAGED_RUNTIMES_HOME;
+    } else {
+      process.env.PIXCODE_MANAGED_RUNTIMES_HOME = previousRuntimeHome;
+    }
   }
-}
 
-const staticSession = await startLiveView('static-smoke', staticProject);
-assert.equal(staticSession.status, 'running', 'Static Live View should start without a child process.');
-assert.match(staticSession.sharePath, /^\/live\/[a-f0-9]{24}\/$/, 'Live View should expose a random public share path.');
-const staticState = await getLiveViewState('static-smoke', staticProject);
-assert.equal(staticState.session?.shareId, staticSession.shareId, 'Live View state should retain the active share session.');
-await stopLiveView('static-smoke');
+  const staticSession = await startLiveView('static-smoke', staticProject);
+  assert.equal(staticSession.status, 'running', 'Static Live View should start without a child process.');
+  assert.match(staticSession.sharePath, /^\/live\/[a-f0-9]{24}\/$/, 'Live View should expose a random public share path.');
+  const staticState = await getLiveViewState('static-smoke', staticProject);
+  assert.equal(staticState.session?.shareId, staticSession.shareId, 'Live View state should retain the active share session.');
+  await stopLiveView('static-smoke');
+} else {
+  console.warn('Skipping Live View launch smoke because this sandbox cannot bind 127.0.0.1.');
+}
 
 console.log('live view integration smoke passed');

package/scripts/smoke/runtime-manager.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const root = process.cwd();
+
+function read(relativePath) {
+  return fs.readFileSync(path.join(root, relativePath), 'utf8');
+}
+
+const managerSource = read('server/services/runtime-manager.js');
+assert.match(managerSource, /RUNTIME_DEFINITIONS/, 'Runtime manager should define a central runtime registry.');
+assert.match(managerSource, /node/, 'Runtime manager should include Node.js.');
+assert.match(managerSource, /php/, 'Runtime manager should include PHP.');
+assert.match(managerSource, /python/, 'Runtime manager should include Python.');
+assert.match(managerSource, /go/, 'Runtime manager should include Go.');
+assert.match(managerSource, /java/, 'Runtime manager should include Java.');
+assert.match(managerSource, /rust/, 'Runtime manager should include Rust.');
+assert.match(managerSource, /discoverRuntime/, 'Runtime manager should expose runtime discovery.');
+assert.match(managerSource, /resolveLiveViewRuntime/, 'Runtime manager should expose Live View runtime resolution.');
+
+const liveViewSource = read('server/services/live-view.js');
+assert.match(liveViewSource, /resolveLiveViewRuntime/, 'Live View should route runtime checks through the runtime manager.');
+assert.match(liveViewSource, /runtime:\s*session\.runtime/, 'Live View public session payload should expose runtime diagnostics.');
+assert.ok(
+  liveViewSource.includes('target.runtime'),
+  'Live View start should keep the runtime manager result on the session.',
+);
+
+const {
+  discoverRuntime,
+  resolveLiveViewRuntime,
+  runtimeManager,
+} = await import('../../server/services/runtime-manager.js');
+
+assert.equal(typeof runtimeManager.discover, 'function', 'Runtime manager should expose a discover method.');
+
+const nodeRuntime = await discoverRuntime('node');
+assert.equal(nodeRuntime.id, 'node');
+assert.equal(nodeRuntime.status, 'available', 'The current Node runtime should be detected as available.');
+assert.ok(nodeRuntime.path, 'Node runtime should include an executable path.');
+assert.match(nodeRuntime.version || '', /\d+\.\d+\.\d+/, 'Node runtime should include a version.');
+
+const missingPython = await discoverRuntime('python', {
+  strictPath: true,
+  env: {
+    ...process.env,
+    PATH: '',
+    Path: '',
+  },
+});
+assert.equal(missingPython.status, 'missing', 'Missing Python should produce a missing runtime status.');
+assert.match(missingPython.diagnostic.message, /Python/i, 'Missing Python diagnostics should name the runtime.');
+assert.match(missingPython.diagnostic.action, /python/i, 'Missing Python diagnostics should include an actionable install command.');
+
+const nodeLiveRuntime = await resolveLiveViewRuntime({
+  id: 'npm-dev-vite',
+  label: 'Vite dev server',
+  framework: 'Vite',
+  command: 'npm',
+  args: ['run', 'dev'],
+  displayCommand: 'npm run dev',
+  packageManager: 'npm',
+}, {
+  env: {
+    ...process.env,
+    PATH: '',
+    Path: '',
+  },
+  preferManaged: true,
+});
+assert.equal(nodeLiveRuntime.runtime.id, 'node', 'JavaScript Live View commands should resolve to the Node runtime.');
+assert.equal(nodeLiveRuntime.managedRuntime?.id, 'npm', 'JavaScript Live View commands should keep the managed npm hook.');
+assert.equal(nodeLiveRuntime.available, true, 'Managed npm should keep JavaScript projects runnable when npm is missing.');
+assert.match(nodeLiveRuntime.reason, /Node package runner/i, 'Managed npm diagnostics should explain the package runner.');
+
+const phpLiveRuntime = await resolveLiveViewRuntime({
+  id: 'php-built-in',
+  label: 'PHP built-in server',
+  framework: 'PHP',
+  command: 'php',
+  args: ['-S', '127.0.0.1:$PORT', '-t', '.'],
+  displayCommand: 'php -S 127.0.0.1:$PORT -t .',
+}, {
+  env: {
+    ...process.env,
+    PATH: '',
+    Path: '',
+  },
+  preferManaged: true,
+});
+assert.equal(phpLiveRuntime.runtime.id, 'php', 'PHP Live View commands should resolve to the PHP runtime.');
+assert.equal(phpLiveRuntime.managedRuntime?.id, 'frankenphp', 'PHP Live View commands should keep the managed FrankenPHP hook.');
+assert.equal(phpLiveRuntime.available, true, 'Managed PHP should keep PHP projects runnable when php is missing.');
+assert.match(phpLiveRuntime.reason, /PHP runtime/i, 'Managed PHP diagnostics should explain the Pixcode runtime.');
+
+console.log('runtime manager smoke passed');

package/scripts/smoke/workflow-trace-timeline.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const root = process.cwd();
+
+function read(relativePath) {
+  return fs.readFileSync(path.join(root, relativePath), 'utf8');
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+const types = read('server/modules/orchestration/workflows/workflow.types.ts');
+assert(types.includes('WorkflowTraceEvent'), 'Workflow trace event type is missing.');
+assert(types.includes("type: 'run' | 'node' | 'provider' | 'message' | 'artifact' | 'file' | 'error'"), 'Trace event type taxonomy is missing.');
+assert(types.includes("severity: 'info' | 'warning' | 'error'"), 'Trace event severity taxonomy is missing.');
+
+const traceService = read('server/modules/orchestration/workflows/workflow-trace.ts');
+assert(traceService.includes('export function buildWorkflowTrace'), 'Workflow trace builder is missing.');
+assert(traceService.includes('redactTraceText'), 'Trace text redaction helper is missing.');
+assert(traceService.includes('file-diff'), 'Trace builder must surface file edit artifacts.');
+assert(traceService.includes('durationMs'), 'Trace builder must include event durations.');
+assert(traceService.includes('workflow.trace.runStarted'), 'Trace builder must emit stable trace title keys.');
+
+const routes = read('server/modules/orchestration/workflows/workflow.routes.ts');
+assert(routes.includes("'/workflows/runs/:runId/trace'"), 'Workflow trace API endpoint is missing.');
+assert(routes.includes('buildWorkflowTrace(run)'), 'Workflow trace route must use the shared trace builder.');
+
+const panel = read('src/components/orchestration/workflows/WorkflowRunPanel.tsx');
+assert(panel.includes('WorkflowTraceEvent'), 'Workflow run panel must type trace events.');
+assert(panel.includes('loadTrace'), 'Workflow run panel must load trace events from the API.');
+assert(panel.includes('traceFilters'), 'Workflow run panel must expose trace filters.');
+assert(panel.includes('traceTimelineId'), 'Workflow trace timeline tab is missing.');
+assert(panel.includes('orchestration.traceTimeline'), 'Workflow run panel must render the trace timeline label.');
+
+const en = read('src/i18n/locales/en/common.json');
+const tr = read('src/i18n/locales/tr/common.json');
+assert(en.includes('"traceTimeline"'), 'English trace timeline translation is missing.');
+assert(tr.includes('"traceTimeline"'), 'Turkish trace timeline translation is missing.');
+
+console.log(JSON.stringify({ ok: true, checked: 'workflow trace timeline' }, null, 2));

package/server/modules/orchestration/index.ts

@@ -55,6 +55,7 @@ export type {
   WorkflowNodeStatus,
   WorkflowRun,
   WorkflowRunStatus,
+  WorkflowTraceEvent,
 } from './workflows/workflow.types.js';
 export type {
   ExecResult,

package/server/modules/orchestration/workflows/workflow-runner.ts

@@ -1086,6 +1086,7 @@ function nodeRunFromNode(node: WorkflowNode): WorkflowNodeRun {
     agentInstanceId: node.agentInstanceId,
     agentLabel: node.agentLabel,
     assignment: node.assignment,
+    promptPreview: node.prompt,
     model: node.model,
     permissionMode: node.permissionMode,
     timeoutMs: node.timeoutMs,

package/server/modules/orchestration/workflows/workflow-trace.ts

@@ -0,0 +1,270 @@
+import os from 'node:os';
+
+import type {
+  WorkflowNodeRun,
+  WorkflowRun,
+  WorkflowTraceEvent,
+} from '@/modules/orchestration/workflows/workflow.types.js';
+
+const MAX_TRACE_TEXT_CHARS = 2_400;
+const TERMINAL_STATES = new Set(['completed', 'failed', 'canceled', 'skipped']);
+
+function traceId(parts: Array<string | number | undefined>): string {
+  return parts.filter((part) => part !== undefined && part !== '').join(':');
+}
+
+function durationMs(startedAt?: number, finishedAt?: number): number | undefined {
+  if (!startedAt || !finishedAt) return undefined;
+  return Math.max(0, finishedAt - startedAt);
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value : undefined;
+}
+
+function redactionValues(run: WorkflowRun): string[] {
+  const metadata = run.metadata ?? {};
+  const workspaceTarget = metadata.workspaceTarget && typeof metadata.workspaceTarget === 'object'
+    ? metadata.workspaceTarget as Record<string, unknown>
+    : {};
+
+  return [
+    os.homedir(),
+    readString(metadata.projectPath),
+    readString(metadata.selectedProjectPath),
+    readString(workspaceTarget.path),
+    readString(workspaceTarget.projectPath),
+    readString(workspaceTarget.selectedProjectPath),
+  ].filter((value): value is string => Boolean(value && value.length > 2));
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function redactTraceText(value: string | undefined, run: WorkflowRun, maxLength = MAX_TRACE_TEXT_CHARS): string | undefined {
+  if (!value?.trim()) return undefined;
+
+  let text = value;
+  for (const secret of redactionValues(run)) {
+    text = text.replace(new RegExp(escapeRegExp(secret), 'g'), '[workspace]');
+  }
+
+  text = text
+    .replace(/\b(?:sk|ghp|github_pat|glpat|npm)_[A-Za-z0-9_=-]{12,}\b/gu, '[redacted-token]')
+    .replace(/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/gu, '[redacted-email]')
+    .trim();
+
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, maxLength - 32).trimEnd()}\n...[trace truncated]`;
+}
+
+function eventBase(
+  node: WorkflowNodeRun | undefined,
+): Pick<WorkflowTraceEvent, 'actor' | 'adapterId' | 'agentInstanceId' | 'agentLabel' | 'model' | 'nodeId'> {
+  if (!node) {
+    return { actor: 'Pixcode' };
+  }
+
+  return {
+    actor: node.agentLabel || node.adapterId || node.nodeId,
+    nodeId: node.nodeId,
+    adapterId: node.adapterId,
+    agentInstanceId: node.agentInstanceId,
+    agentLabel: node.agentLabel,
+    model: node.model,
+  };
+}
+
+function pushEvent(
+  events: WorkflowTraceEvent[],
+  event: WorkflowTraceEvent,
+): void {
+  events.push(event);
+}
+
+function artifactTitleKey(type: string): string {
+  if (type === 'file-diff') return 'workflow.trace.fileChanged';
+  if (type === 'preview-url') return 'workflow.trace.previewReady';
+  if (type === 'command-output') return 'workflow.trace.commandOutput';
+  return 'workflow.trace.artifact';
+}
+
+function artifactType(type: string): WorkflowTraceEvent['type'] {
+  return type === 'file-diff' ? 'file' : 'artifact';
+}
+
+function artifactTitle(type: string): string {
+  if (type === 'file-diff') return 'File changes captured';
+  if (type === 'preview-url') return 'Preview output captured';
+  if (type === 'command-output') return 'Command output captured';
+  return 'Artifact captured';
+}
+
+function artifactSummary(
+  artifact: NonNullable<WorkflowNodeRun['artifacts']>[number],
+  run: WorkflowRun,
+): string | undefined {
+  if (artifact.text?.trim()) {
+    return redactTraceText(artifact.text, run);
+  }
+  if (artifact.data && Object.keys(artifact.data).length > 0) {
+    return redactTraceText(JSON.stringify(artifact.data, null, 2), run);
+  }
+  return artifact.type;
+}
+
+function nodeTimestamp(run: WorkflowRun, node: WorkflowNodeRun, index: number): number {
+  return node.startedAt ?? run.startedAt + index;
+}
+
+export function buildWorkflowTrace(run: WorkflowRun): WorkflowTraceEvent[] {
+  const events: WorkflowTraceEvent[] = [];
+
+  pushEvent(events, {
+    id: traceId([run.id, 'run-started']),
+    type: 'run',
+    severity: 'info',
+    status: run.status,
+    timestamp: run.startedAt,
+    durationMs: durationMs(run.startedAt, run.finishedAt),
+    actor: 'Pixcode',
+    title: 'Workflow run started',
+    titleKey: 'workflow.trace.runStarted',
+    summary: redactTraceText(run.input, run),
+    metadata: {
+      workflowId: run.workflowId,
+      contextId: run.contextId,
+    },
+  });
+
+  run.nodeRuns.forEach((node, index) => {
+    const base = eventBase(node);
+    const timestamp = nodeTimestamp(run, node, index);
+    const nodeDuration = durationMs(node.startedAt, node.finishedAt);
+
+    pushEvent(events, {
+      id: traceId([run.id, node.nodeId, 'node']),
+      type: 'node',
+      severity: node.status === 'failed' ? 'error' : 'info',
+      status: node.status,
+      timestamp,
+      durationMs: nodeDuration,
+      ...base,
+      title: TERMINAL_STATES.has(node.status) ? 'Workflow step finished' : 'Workflow step started',
+      titleKey: TERMINAL_STATES.has(node.status) ? 'workflow.trace.nodeFinished' : 'workflow.trace.nodeStarted',
+      summary: redactTraceText(node.assignment, run),
+      metadata: {
+        stage: node.stage,
+        internal: node.internal,
+      },
+    });
+
+    if (node.promptPreview) {
+      pushEvent(events, {
+        id: traceId([run.id, node.nodeId, 'prompt']),
+        type: 'message',
+        severity: 'info',
+        status: node.status,
+        timestamp: timestamp + 1,
+        ...base,
+        title: 'Prompt prepared',
+        titleKey: 'workflow.trace.prompt',
+        summary: redactTraceText(node.promptPreview, run),
+      });
+    }
+
+    if (node.adapterId || node.model) {
+      pushEvent(events, {
+        id: traceId([run.id, node.nodeId, 'provider']),
+        type: 'provider',
+        severity: node.status === 'failed' ? 'error' : 'info',
+        status: node.a2aTaskId ? 'submitted' : node.status,
+        timestamp: timestamp + 2,
+        durationMs: nodeDuration,
+        ...base,
+        title: 'Provider call',
+        titleKey: 'workflow.trace.providerCall',
+        summary: [node.adapterId, node.model].filter(Boolean).join(' / '),
+        metadata: {
+          a2aTaskId: node.a2aTaskId,
+          permissionMode: node.permissionMode,
+          timeoutMs: node.timeoutMs,
+        },
+      });
+    }
+
+    (node.messages ?? [])
+      .filter((message) => message.role !== 'user' && message.text.trim())
+      .forEach((message, messageIndex) => {
+        pushEvent(events, {
+          id: traceId([run.id, node.nodeId, 'message', messageIndex]),
+          type: 'message',
+          severity: 'info',
+          status: node.status,
+          timestamp: message.createdAt ?? timestamp + 10 + messageIndex,
+          ...base,
+          title: 'Agent message',
+          titleKey: 'workflow.trace.agentMessage',
+          summary: redactTraceText(message.text, run),
+          metadata: {
+            role: message.role,
+          },
+        });
+      });
+
+    (node.artifacts ?? []).forEach((artifact, artifactIndex) => {
+      pushEvent(events, {
+        id: traceId([run.id, node.nodeId, 'artifact', artifactIndex]),
+        type: artifactType(artifact.type),
+        severity: 'info',
+        status: node.status,
+        timestamp: node.finishedAt ?? timestamp + 20 + artifactIndex,
+        ...base,
+        title: artifactTitle(artifact.type),
+        titleKey: artifactTitleKey(artifact.type),
+        summary: artifactSummary(artifact, run),
+        metadata: {
+          artifactType: artifact.type,
+          artifactMetadata: artifact.metadata,
+        },
+      });
+    });
+
+    if (node.error) {
+      pushEvent(events, {
+        id: traceId([run.id, node.nodeId, 'error']),
+        type: 'error',
+        severity: 'error',
+        status: node.status,
+        timestamp: node.finishedAt ?? timestamp + 30,
+        durationMs: nodeDuration,
+        ...base,
+        title: 'Step error',
+        titleKey: 'workflow.trace.error',
+        summary: redactTraceText(node.error, run),
+      });
+    }
+  });
+
+  if (run.finishedAt) {
+    pushEvent(events, {
+      id: traceId([run.id, 'run-finished']),
+      type: 'run',
+      severity: run.status === 'failed' ? 'error' : 'info',
+      status: run.status,
+      timestamp: run.finishedAt,
+      durationMs: durationMs(run.startedAt, run.finishedAt),
+      actor: 'Pixcode',
+      title: 'Workflow run finished',
+      titleKey: 'workflow.trace.runFinished',
+      summary: redactTraceText(readString(run.metadata?.error), run),
+      metadata: {
+        workflowId: run.workflowId,
+        contextId: run.contextId,
+      },
+    });
+  }
+
+  return events.sort((a, b) => a.timestamp - b.timestamp || a.id.localeCompare(b.id));
+}

package/server/modules/orchestration/workflows/workflow.routes.ts

@@ -3,6 +3,7 @@ import express from 'express';
 
 import { workflowRunner } from '@/modules/orchestration/workflows/workflow-runner.js';
 import { workflowStore } from '@/modules/orchestration/workflows/workflow-store.js';
+import { buildWorkflowTrace } from '@/modules/orchestration/workflows/workflow-trace.js';
 import { findPixcodeAppRoot } from '@/modules/orchestration/workflows/workspace-target.js';
 
 const TERMINAL_RUN_STATES = new Set(['completed', 'failed', 'canceled']);
@@ -120,6 +121,19 @@ export function createWorkflowRouter(): Router {
     });
   });
 
+  router.get('/workflows/runs/:runId/trace', (req, res) => {
+    const run = workflowStore.getRun(req.params.runId);
+    if (!run) {
+      res.status(404).json({ error: { code: 'RUN_NOT_FOUND', message: req.params.runId } });
+      return;
+    }
+
+    res.json({
+      runId: run.id,
+      trace: buildWorkflowTrace(run),
+    });
+  });
+
   router.get('/workflows/runs/:runId', (req, res) => {
     const run = workflowStore.getRun(req.params.runId);
     if (!run) {

package/server/modules/orchestration/workflows/workflow.types.ts

@@ -35,6 +35,7 @@ export interface WorkflowNodeRun {
   agentInstanceId?: string;
   agentLabel?: string;
   assignment?: string;
+  promptPreview?: string;
   model?: string;
   permissionMode?: string;
   timeoutMs?: number;
@@ -70,3 +71,23 @@ export interface WorkflowRun {
   finishedAt?: number;
   metadata?: Record<string, unknown>;
 }
+
+export interface WorkflowTraceEvent {
+  id: string;
+  type: 'run' | 'node' | 'provider' | 'message' | 'artifact' | 'file' | 'error';
+  severity: 'info' | 'warning' | 'error';
+  status: WorkflowRunStatus | WorkflowNodeStatus | 'submitted';
+  timestamp: number;
+  durationMs?: number;
+  actor: string;
+  title: string;
+  titleKey?: string;
+  summary?: string;
+  detail?: string;
+  nodeId?: string;
+  adapterId?: string;
+  agentInstanceId?: string;
+  agentLabel?: string;
+  model?: string;
+  metadata?: Record<string, unknown>;
+}