@pixelbyte-software/pixcode 1.34.0 → 1.35.1

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

@@ -0,0 +1,97 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { builtInWorkflows } from '@/modules/orchestration/workflows/built-in-workflows.js';
+import type { Workflow, WorkflowRun } from '@/modules/orchestration/workflows/workflow.types.js';
+
+interface Document {
+  version: 1;
+  runs: WorkflowRun[];
+}
+
+const TERMINAL_RUN_STATES = new Set(['completed', 'failed', 'canceled']);
+const TERMINAL_NODE_STATES = new Set(['completed', 'failed', 'canceled', 'skipped']);
+
+export class WorkflowStore {
+  private readonly filePath = process.env.WORKFLOW_RUNS_PATH ??
+    path.join(os.homedir(), '.pixcode', 'workflow-runs.json');
+  private readonly tmpPath = `${this.filePath}.tmp`;
+  private readonly runs = new Map<string, WorkflowRun>();
+
+  constructor() {
+    this.load();
+  }
+
+  listWorkflows(): Workflow[] {
+    return builtInWorkflows;
+  }
+
+  getWorkflow(id: string): Workflow | undefined {
+    return builtInWorkflows.find((workflow) => workflow.id === id);
+  }
+
+  listRuns(): WorkflowRun[] {
+    return [...this.runs.values()].sort((a, b) => b.startedAt - a.startedAt);
+  }
+
+  getRun(id: string): WorkflowRun | undefined {
+    return this.runs.get(id);
+  }
+
+  setRun(run: WorkflowRun): void {
+    this.runs.set(run.id, run);
+    this.flush();
+  }
+
+  private load(): void {
+    fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+    if (!fs.existsSync(this.filePath)) {
+      this.flush();
+      return;
+    }
+    let repaired = false;
+    try {
+      const parsed = JSON.parse(fs.readFileSync(this.filePath, 'utf8')) as Partial<Document>;
+      for (const run of Array.isArray(parsed.runs) ? parsed.runs : []) {
+        if (run && typeof run.id === 'string') {
+          if (!TERMINAL_RUN_STATES.has(run.status)) {
+            run.status = 'failed';
+            run.finishedAt = run.finishedAt ?? Date.now();
+            run.metadata = {
+              ...run.metadata,
+              error: 'Pixcode restarted before this workflow run reached a terminal state.',
+            };
+            for (const node of run.nodeRuns ?? []) {
+              if (!TERMINAL_NODE_STATES.has(node.status)) {
+                node.status = 'failed';
+                node.finishedAt = node.finishedAt ?? run.finishedAt;
+                node.error = node.error ?? 'Workflow runner stopped before this node reached a terminal state.';
+              }
+            }
+            repaired = true;
+          }
+          this.runs.set(run.id, run);
+        }
+      }
+    } catch {
+      this.flush();
+      return;
+    }
+
+    if (repaired) {
+      this.flush();
+    }
+  }
+
+  private flush(): void {
+    fs.writeFileSync(
+      this.tmpPath,
+      JSON.stringify({ version: 1, runs: [...this.runs.values()] }, null, 2),
+      'utf8',
+    );
+    fs.renameSync(this.tmpPath, this.filePath);
+  }
+}
+
+export const workflowStore = new WorkflowStore();

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

@@ -0,0 +1,169 @@
+import type { Router } from 'express';
+import express from 'express';
+
+import { workflowRunner } from '@/modules/orchestration/workflows/workflow-runner.js';
+import { workflowStore } from '@/modules/orchestration/workflows/workflow-store.js';
+import { findPixcodeAppRoot } from '@/modules/orchestration/workflows/workspace-target.js';
+
+const TERMINAL_RUN_STATES = new Set(['completed', 'failed', 'canceled']);
+
+function readMetadata(body: unknown): Record<string, unknown> | undefined {
+  if (!body || typeof body !== 'object') return undefined;
+  const metadata = (body as Record<string, unknown>).metadata;
+  return metadata && typeof metadata === 'object' ? metadata as Record<string, unknown> : undefined;
+}
+
+function sendRunSnapshot(res: express.Response, runId: string): boolean {
+  const run = workflowStore.getRun(runId);
+  if (!run) {
+    res.write(`event: error\ndata: ${JSON.stringify({ error: { code: 'RUN_NOT_FOUND', message: runId } })}\n\n`);
+    return true;
+  }
+
+  res.write(`event: snapshot\ndata: ${JSON.stringify({ run })}\n\n`);
+  return TERMINAL_RUN_STATES.has(run.status);
+}
+
+export function createWorkflowRouter(): Router {
+  const router = express.Router();
+  router.use(express.json({ limit: '2mb' }));
+
+  router.get('/workflows', (_req, res) => {
+    res.json({ workflows: workflowStore.listWorkflows() });
+  });
+
+  router.get('/workflows/context', (_req, res) => {
+    res.json({
+      appRoot: findPixcodeAppRoot(),
+      defaultWorkspaceTarget: 'selected_project',
+      supportedWorkspaceTargets: ['selected_project', 'pixcode_app', 'custom'],
+    });
+  });
+
+  router.get('/workflows/runs', (req, res) => {
+    const projectId = typeof req.query.projectId === 'string' ? req.query.projectId : undefined;
+    const runs = projectId
+      ? workflowStore.listRuns().filter((run) => run.metadata?.projectId === projectId)
+      : workflowStore.listRuns();
+    res.json({ runs });
+  });
+
+  router.get('/workflows/runs/:runId/events', (req, res) => {
+    res.setHeader('Content-Type', 'text/event-stream');
+    res.setHeader('Cache-Control', 'no-cache, no-transform');
+    res.setHeader('Connection', 'keep-alive');
+    res.setHeader('X-Accel-Buffering', 'no');
+    if (typeof res.flushHeaders === 'function') {
+      res.flushHeaders();
+    }
+    if (res.socket && typeof res.socket.setNoDelay === 'function') {
+      try {
+        res.socket.setNoDelay(true);
+      } catch {
+        // Non-fatal; SSE still works without disabling Nagle.
+      }
+    }
+
+    const terminal = sendRunSnapshot(res, req.params.runId);
+    if (terminal) {
+      res.end();
+      return;
+    }
+
+    const heartbeat = setInterval(() => {
+      res.write(': ping\n\n');
+    }, 15_000);
+    const timer = setInterval(() => {
+      const done = sendRunSnapshot(res, req.params.runId);
+      if (done) {
+        clearInterval(timer);
+        clearInterval(heartbeat);
+        res.end();
+      }
+    }, 1_000);
+
+    req.on('close', () => {
+      clearInterval(timer);
+      clearInterval(heartbeat);
+    });
+  });
+
+  router.get('/workflows/runs/:runId', (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(run);
+  });
+
+  router.post('/workflows/:id/preview', (req, res) => {
+    const workflow = workflowStore.getWorkflow(req.params.id);
+    if (!workflow) {
+      res.status(404).json({ error: { code: 'WORKFLOW_NOT_FOUND', message: req.params.id } });
+      return;
+    }
+    try {
+      const runtimeWorkflow = workflowRunner.preview(workflow, readMetadata(req.body));
+      res.json({
+        workflow: runtimeWorkflow,
+        nodeCount: runtimeWorkflow.nodes.length,
+        nodes: runtimeWorkflow.nodes.map((node) => ({
+          id: node.id,
+          adapterId: node.adapterId,
+          agentInstanceId: node.agentInstanceId,
+          agentLabel: node.agentLabel,
+          assignment: node.assignment,
+          stage: node.stage,
+          inputs: node.inputs,
+          onFail: node.onFail,
+          output: node.output,
+          model: node.model,
+          permissionMode: node.permissionMode,
+          timeoutMs: node.timeoutMs,
+        })),
+      });
+    } catch (error) {
+      res.status(400).json({
+        error: {
+          code: 'WORKFLOW_INVALID',
+          message: error instanceof Error ? error.message : String(error),
+        },
+      });
+    }
+  });
+
+  router.post('/workflows/runs/:runId/cancel', async (req, res) => {
+    const run = await workflowRunner.cancel(req.params.runId);
+    if (!run) {
+      res.status(404).json({ error: { code: 'RUN_NOT_FOUND', message: req.params.runId } });
+      return;
+    }
+    res.json(run);
+  });
+
+  router.post('/workflows/:id/runs', (req, res) => {
+    const workflow = workflowStore.getWorkflow(req.params.id);
+    if (!workflow) {
+      res.status(404).json({ error: { code: 'WORKFLOW_NOT_FOUND', message: req.params.id } });
+      return;
+    }
+    try {
+      const run = workflowRunner.start(
+        workflow,
+        typeof req.body?.input === 'string' ? req.body.input : '',
+        readMetadata(req.body),
+      );
+      res.status(202).json(run);
+    } catch (error) {
+      res.status(400).json({
+        error: {
+          code: 'WORKFLOW_INVALID',
+          message: error instanceof Error ? error.message : String(error),
+        },
+      });
+    }
+  });
+
+  return router;
+}

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

@@ -0,0 +1,70 @@
+export type WorkflowRunStatus = 'queued' | 'running' | 'completed' | 'failed' | 'canceled';
+export type WorkflowNodeStatus = WorkflowRunStatus | 'skipped';
+
+export interface WorkflowNode {
+  id: string;
+  adapterId: string;
+  prompt: string;
+  inputs: string[];
+  output: 'message' | 'artifact' | 'both';
+  onFail: 'abort' | 'continue' | 'retry';
+  stage?: string;
+  agentInstanceId?: string;
+  agentLabel?: string;
+  assignment?: string;
+  model?: string;
+  permissionMode?: string;
+  toolsSettings?: Record<string, unknown>;
+  isolation?: 'host' | 'worktree' | 'docker';
+  timeoutMs?: number;
+}
+
+export interface Workflow {
+  id: string;
+  name: string;
+  description?: string;
+  trigger: 'manual' | 'on-task-create' | 'on-pr-open';
+  nodes: WorkflowNode[];
+  isBuiltin?: boolean;
+}
+
+export interface WorkflowNodeRun {
+  nodeId: string;
+  adapterId?: string;
+  agentInstanceId?: string;
+  agentLabel?: string;
+  assignment?: string;
+  model?: string;
+  permissionMode?: string;
+  timeoutMs?: number;
+  stage?: string;
+  status: WorkflowNodeStatus;
+  a2aTaskId?: string;
+  startedAt?: number;
+  finishedAt?: number;
+  error?: string;
+  outputText?: string;
+  messages?: Array<{
+    role: string;
+    text: string;
+    createdAt?: number;
+  }>;
+  artifacts?: Array<{
+    type: string;
+    text?: string;
+    data?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+  }>;
+}
+
+export interface WorkflowRun {
+  id: string;
+  workflowId: string;
+  contextId: string;
+  status: WorkflowRunStatus;
+  nodeRuns: WorkflowNodeRun[];
+  input?: string;
+  startedAt: number;
+  finishedAt?: number;
+  metadata?: Record<string, unknown>;
+}

package/server/modules/orchestration/workflows/workspace-target.ts

@@ -0,0 +1,120 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export type WorkspaceTargetKind = 'selected_project' | 'pixcode_app' | 'custom';
+
+export type ResolvedWorkspaceTarget = {
+  kind: WorkspaceTargetKind;
+  label: string;
+  projectPath: string;
+  selectedProjectPath?: string;
+  selectedProjectName?: string;
+  appRoot: string;
+};
+
+const pixcodePackageName = '@pixelbyte-software/pixcode';
+
+function readRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' ? value as Record<string, unknown> : undefined;
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function readTargetKind(value: unknown): WorkspaceTargetKind | undefined {
+  return value === 'selected_project' || value === 'pixcode_app' || value === 'custom'
+    ? value
+    : undefined;
+}
+
+export function findPixcodeAppRoot(): string {
+  let currentDir = dirname(fileURLToPath(import.meta.url));
+
+  for (let depth = 0; depth < 10; depth += 1) {
+    try {
+      const packagePath = resolve(currentDir, 'package.json');
+      const pkg = JSON.parse(readFileSync(packagePath, 'utf8')) as { name?: string };
+      if (pkg.name === pixcodePackageName) {
+        return currentDir;
+      }
+    } catch {
+      // Walk upward until the Pixcode package root is found.
+    }
+
+    const parent = dirname(currentDir);
+    if (parent === currentDir) break;
+    currentDir = parent;
+  }
+
+  return process.cwd();
+}
+
+export function resolveWorkflowWorkspace(metadata?: Record<string, unknown>): ResolvedWorkspaceTarget {
+  const target = readRecord(metadata?.workspaceTarget);
+  const appRoot = findPixcodeAppRoot();
+  const selectedProjectPath = readString(metadata?.selectedProjectPath) ?? readString(metadata?.projectPath);
+  const selectedProjectName = readString(metadata?.projectName) ?? readString(metadata?.projectId);
+  const kind = readTargetKind(target?.kind) ?? 'selected_project';
+  const customPath = readString(target?.projectPath);
+
+  if (kind === 'pixcode_app') {
+    return {
+      kind,
+      label: 'Pixcode app',
+      projectPath: appRoot,
+      selectedProjectPath,
+      selectedProjectName,
+      appRoot,
+    };
+  }
+
+  if (kind === 'custom') {
+    return {
+      kind,
+      label: readString(target?.label) ?? 'Custom workspace',
+      projectPath: customPath ?? selectedProjectPath ?? appRoot,
+      selectedProjectPath,
+      selectedProjectName,
+      appRoot,
+    };
+  }
+
+  return {
+    kind: 'selected_project',
+    label: selectedProjectName ?? 'Selected project',
+    projectPath: selectedProjectPath ?? appRoot,
+    selectedProjectPath,
+    selectedProjectName,
+    appRoot,
+  };
+}
+
+export function workspaceTargetMetadata(target: ResolvedWorkspaceTarget): Record<string, unknown> {
+  return {
+    kind: target.kind,
+    label: target.label,
+    projectPath: target.projectPath,
+    selectedProjectPath: target.selectedProjectPath,
+    selectedProjectName: target.selectedProjectName,
+    appRoot: target.appRoot,
+  };
+}
+
+export function workspaceContextPrompt(target: ResolvedWorkspaceTarget): string {
+  return [
+    'Pixcode orchestration execution context:',
+    `- Target workspace: ${target.label}`,
+    `- Working directory for this agent: ${target.projectPath}`,
+    target.selectedProjectName ? `- Selected UI project: ${target.selectedProjectName}` : '',
+    target.selectedProjectPath ? `- Selected UI project path: ${target.selectedProjectPath}` : '',
+    `- Pixcode app root: ${target.appRoot}`,
+    '',
+    'Rules:',
+    '- Treat the working directory above as the authoritative project/application for this task.',
+    '- Do not guess another repository path unless the user explicitly asks for it.',
+    '- If the user asks to analyze or modify Pixcode/orchestration itself, the target workspace must be the Pixcode app root.',
+    '- Before running package-manager commands, inspect the package files in the working directory.',
+  ].filter(Boolean).join('\n');
+}

package/server/modules/orchestration/workspace/docker-workspace.ts

@@ -0,0 +1,135 @@
+import { WorkspaceError } from '@/modules/orchestration/workspace/types.js';
+import type {
+  ExecResult,
+  WorkspaceHandle,
+  WorkspaceRequest,
+} from '@/modules/orchestration/workspace/types.js';
+
+async function run(
+  command: string,
+  args: string[],
+): Promise<ExecResult> {
+  try {
+    const { execFile } = await import('node:child_process');
+    const { promisify } = await import('node:util');
+    const execFileAsync = promisify(execFile);
+    const { stdout, stderr } = await execFileAsync(command, args, {
+      maxBuffer: 20 * 1024 * 1024,
+    });
+    return { stdout: String(stdout), stderr: String(stderr), exitCode: 0 };
+  } catch (error) {
+    const err = error as Error & { stdout?: string; stderr?: string; code?: number };
+    return {
+      stdout: String(err.stdout ?? ''),
+      stderr: String(err.stderr ?? err.message),
+      exitCode: typeof err.code === 'number' ? err.code : 1,
+    };
+  }
+}
+
+export class DockerWorkspace implements WorkspaceHandle {
+  readonly kind = 'docker' as const;
+  readonly id: string;
+  readonly path: string;
+  readonly baseRef: string;
+  readonly metadata: Record<string, unknown>;
+  private containerId?: string;
+  private readonly worktreePath: string;
+
+  constructor(request: WorkspaceRequest) {
+    this.id = `docker_${request.taskId}`;
+    this.path = '/workspace';
+    this.baseRef = request.baseRef ?? 'HEAD';
+    this.worktreePath = request.projectPath;
+    this.metadata = {
+      ...request.metadata,
+      image: request.metadata?.image ?? 'node:22-slim',
+      containerId: undefined,
+      exposedPorts: [],
+    };
+  }
+
+  private async ensureStarted(): Promise<void> {
+    if (this.containerId) return;
+    const image = String(this.metadata.image ?? 'node:22-slim');
+    const pullResult = await run('docker', ['pull', image]);
+    if (pullResult.exitCode !== 0) {
+      throw new WorkspaceError('WORKSPACE_DOCKER_PULL_FAILED', pullResult.stderr || pullResult.stdout, {
+        image,
+        workspaceId: this.id,
+      });
+    }
+    const createResult = await run('docker', [
+      'create',
+      '--rm',
+      '-v', `${this.worktreePath}:/workspace`,
+      '-w', '/workspace',
+      image,
+      'tail', '-f', '/dev/null',
+    ]);
+    if (createResult.exitCode !== 0 || !createResult.stdout.trim()) {
+      throw new WorkspaceError('WORKSPACE_DOCKER_CREATE_FAILED', createResult.stderr || createResult.stdout, {
+        image,
+        workspaceId: this.id,
+      });
+    }
+    this.containerId = createResult.stdout.trim();
+    const startResult = await run('docker', ['start', this.containerId]);
+    if (startResult.exitCode !== 0) {
+      await this.cleanupContainer();
+      throw new WorkspaceError('WORKSPACE_DOCKER_START_FAILED', startResult.stderr || startResult.stdout, {
+        containerId: this.containerId,
+        workspaceId: this.id,
+      });
+    }
+    this.metadata.containerId = this.containerId;
+  }
+
+  private async cleanupContainer(): Promise<void> {
+    if (!this.containerId) return;
+    await run('docker', ['rm', '-f', this.containerId]).catch(() => {});
+    this.containerId = undefined;
+  }
+
+  async exec(command: string, args: string[] = []): Promise<ExecResult> {
+    await this.ensureStarted();
+    return run('docker', ['exec', this.containerId!, command, ...args]);
+  }
+
+  async readFile(relativePath: string): Promise<string> {
+    await this.ensureStarted();
+    const result = await run('docker', ['exec', this.containerId!, 'cat', relativePath]);
+    if (result.exitCode !== 0) {
+      throw new WorkspaceError('WORKSPACE_READ_FAILED', result.stderr, { path: relativePath });
+    }
+    return result.stdout;
+  }
+
+  async writeFile(relativePath: string, content: string): Promise<void> {
+    await this.ensureStarted();
+    const result = await run('docker', ['exec', this.containerId!, 'sh', '-c', `cat > ${relativePath}`]);
+    if (result.exitCode !== 0) {
+      throw new WorkspaceError('WORKSPACE_WRITE_FAILED', result.stderr, { path: relativePath });
+    }
+  }
+
+  async diff(): Promise<string> {
+    const { execFile } = await import('node:child_process');
+    const { promisify } = await import('node:util');
+    const execFileAsync = promisify(execFile);
+    try {
+      const { stdout } = await execFileAsync('git', ['diff', `${this.baseRef}...HEAD`], {
+        cwd: this.worktreePath,
+        maxBuffer: 20 * 1024 * 1024,
+      });
+      return String(stdout);
+    } catch (error) {
+      const err = error as Error & { stderr?: string };
+      return String(err.stderr ?? err.message);
+    }
+  }
+
+  async destroy(): Promise<void> {
+    await this.cleanupContainer();
+  }
+}

package/server/modules/orchestration/workspace/path-safety.ts

@@ -0,0 +1,55 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { WorkspaceError } from '@/modules/orchestration/workspace/types.js';
+
+const SAFE_ID = /^[a-zA-Z0-9_-]+$/;
+
+export function getWorktreesRoot(): string {
+  return process.env.PIXCODE_WORKTREES_ROOT ?? path.join(os.homedir(), '.pixcode', 'worktrees');
+}
+
+export function assertSafeId(value: string, label: string): string {
+  if (!SAFE_ID.test(value) || value.includes('..')) {
+    throw new WorkspaceError('UNSAFE_WORKSPACE_ID', `Unsafe ${label}: ${value}`, { value, label });
+  }
+  return value;
+}
+
+export function ensureDirectory(dir: string): void {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+export function safeWorkspacePath(workspaceId: string): string {
+  assertSafeId(workspaceId, 'workspace id');
+  const root = getWorktreesRoot();
+  ensureDirectory(root);
+  const resolvedRoot = fs.realpathSync.native(root);
+  const target = path.resolve(resolvedRoot, workspaceId);
+  if (!target.startsWith(`${resolvedRoot}${path.sep}`)) {
+    throw new WorkspaceError('WORKSPACE_PATH_TRAVERSAL', 'Workspace path escaped root', {
+      root: resolvedRoot,
+      target,
+    });
+  }
+  return target;
+}
+
+export function safeJoin(root: string, relativePath: string): string {
+  if (path.isAbsolute(relativePath) || relativePath.includes('\0')) {
+    throw new WorkspaceError('WORKSPACE_PATH_TRAVERSAL', 'Workspace file path must be relative', {
+      relativePath,
+    });
+  }
+
+  const target = path.resolve(root, relativePath);
+  const resolvedRoot = fs.existsSync(root) ? fs.realpathSync.native(root) : path.resolve(root);
+  if (!target.startsWith(`${resolvedRoot}${path.sep}`) && target !== resolvedRoot) {
+    throw new WorkspaceError('WORKSPACE_PATH_TRAVERSAL', 'Workspace file path escaped root', {
+      root: resolvedRoot,
+      target,
+    });
+  }
+  return target;
+}

package/server/modules/orchestration/workspace/types.ts

@@ -0,0 +1,52 @@
+import type { ExecFileOptions } from 'node:child_process';
+
+export type WorkspaceKind = 'host' | 'worktree' | 'docker';
+
+export interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export interface WorkspaceHandle {
+  id: string;
+  kind: WorkspaceKind;
+  path: string;
+  baseRef: string;
+  branchName?: string;
+  metadata: Record<string, unknown>;
+  exec(command: string, args?: string[], options?: ExecFileOptions): Promise<ExecResult>;
+  readFile(relativePath: string): Promise<string>;
+  writeFile(relativePath: string, content: string): Promise<void>;
+  diff(): Promise<string>;
+  destroy(): Promise<void>;
+}
+
+export interface WorkspaceRequest {
+  taskId: string;
+  projectPath: string;
+  kind?: WorkspaceKind;
+  baseRef?: string;
+  keepAfterCompletion?: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+export interface WorkspaceMetadata {
+  id: string;
+  kind: WorkspaceKind;
+  path: string;
+  baseRef: string;
+  branchName?: string;
+  keepAfterCompletion?: boolean;
+}
+
+export class WorkspaceError extends Error {
+  constructor(
+    public readonly code: string,
+    message: string,
+    public readonly details: Record<string, unknown> = {},
+  ) {
+    super(message);
+    this.name = 'WorkspaceError';
+  }
+}