@pixelbyte-software/pixcode 1.33.11 → 1.35.0

package/server/modules/orchestration/a2a/task-store.ts

@@ -0,0 +1,178 @@
+// server/modules/orchestration/a2a/task-store.ts
+// A2A task persistence backed by shared JsonStore for atomic writes and corruption recovery.
+// Exposes a Map-compatible surface (get/set/delete/size/entries/values) so routes.ts
+// can treat the store as a typed Map while still benefiting from durable JSON storage.
+
+import os from 'os';
+import path from 'path';
+
+import { JsonStore } from '@/database/json-store.js';
+import type { Message, Task, TaskState, TaskSummary } from '@/modules/orchestration/a2a/types.js';
+
+const filePath = path.join(os.homedir(), '.pixcode', 'a2a-tasks.json');
+
+export interface A2ATaskStoreOptions {
+  terminalTaskTtlMs?: number;
+}
+
+export interface ListOptions {
+  state?: TaskState;
+  contextId?: string;
+  adapterId?: string;
+  limit?: number;
+}
+
+export class A2ATaskStore {
+  private store: JsonStore;
+
+  constructor(_options?: A2ATaskStoreOptions) {
+    this.store = new JsonStore(filePath, { a2a_tasks: [] });
+  }
+
+  // ── Map-compatible API ─────────────────────────────────────────────────────
+
+  get(id: string): Task | undefined {
+    return this.store.findWhere('a2a_tasks', (t: Task) => t.id === id) ?? undefined;
+  }
+
+  set(task: Task): void {
+    const existing = this.get(task.id);
+    if (existing) {
+      this.store.updateWhere('a2a_tasks', (t: Task) => t.id === task.id, task);
+    } else {
+      this.store.insert('a2a_tasks', task, { autoId: false });
+    }
+  }
+
+  delete(id: string): void {
+    this.store.deleteWhere('a2a_tasks', (t: Task) => t.id === id);
+  }
+
+  get size(): number {
+    return (this.store.filterWhere('a2a_tasks', () => true) as Task[]).length;
+  }
+
+  *entries(): IterableIterator<[string, Task]> {
+    const tasks = this.store.filterWhere('a2a_tasks', () => true) as Task[];
+    for (const task of tasks) {
+      yield [task.id, task];
+    }
+  }
+
+  *values(): IterableIterator<Task> {
+    const tasks = this.store.filterWhere('a2a_tasks', () => true) as Task[];
+    for (const task of tasks) {
+      yield task;
+    }
+  }
+
+  // ── Query helpers ──────────────────────────────────────────────────────────
+
+  list(options: ListOptions = {}): Task[] {
+    const { state, contextId, adapterId, limit = 50 } = options;
+    let tasks = this.store.filterWhere('a2a_tasks', (t: Task) => {
+      if (state && t.state !== state) return false;
+      if (contextId && t.contextId !== contextId) return false;
+      if (adapterId && (t.metadata?.adapterId as string | undefined) !== adapterId) return false;
+      return true;
+    }) as Task[];
+    if (limit > 0) tasks = tasks.slice(0, limit);
+    return tasks;
+  }
+
+  summarize(task: Task): TaskSummary {
+    return {
+      id: task.id,
+      contextId: task.contextId,
+      state: task.state,
+      adapterId: task.metadata?.adapterId as string | undefined,
+      adapterSelector: task.metadata?.adapterSelector as string | undefined,
+      error: task.error,
+      createdAt: task.createdAt,
+      updatedAt: task.updatedAt,
+      messageCount: task.history?.length ?? 0,
+      artifactCount: task.artifacts?.length ?? 0,
+      lastMessage: task.history?.at(-1),
+    };
+  }
+
+  // ── Legacy named methods (kept for any future internal callers) ────────────
+
+  getTask(id: string): Task | undefined {
+    return this.get(id);
+  }
+
+  getTaskByIndex(index: number): Task | undefined {
+    const tasks = this.store.filterWhere('a2a_tasks', () => true) as Task[];
+    return tasks[index] ?? undefined;
+  }
+
+  getTasks(): Task[] {
+    return this.store.filterWhere('a2a_tasks', () => true) as Task[];
+  }
+
+  createTask(task: Task): void {
+    this.store.insert('a2a_tasks', task, { autoId: false });
+  }
+
+  updateTask(id: string, updates: Partial<Task>): void {
+    const existing = this.get(id);
+    if (!existing) return;
+    const updated = { ...existing, ...updates, id: existing.id };
+    this.store.updateWhere('a2a_tasks', (t: Task) => t.id === id, updated);
+  }
+
+  updateTaskState(id: string, state: TaskState): void {
+    this.updateTask(id, { status: { state } } as Partial<Task>);
+  }
+
+  deleteTask(id: string): void {
+    this.delete(id);
+  }
+
+  appendHistory(id: string, entry: { state: TaskState; timestamp: string }): void {
+    const task = this.get(id);
+    if (!task) return;
+    const history = [...(task.history ?? []), entry as unknown as Message];
+    this.updateTask(id, { history } as Partial<Task>);
+  }
+
+  addArtifact(id: string, artifact: NonNullable<Task['artifacts']>[number]): void {
+    const task = this.get(id);
+    if (!task) return;
+    const artifacts = [...(task.artifacts ?? []), artifact];
+    this.updateTask(id, { artifacts } as Partial<Task>);
+  }
+
+  addMessage(id: string, message: Message): void {
+    const task = this.get(id);
+    if (!task) return;
+    const history = [...(task.history ?? []), message];
+    this.updateTask(id, { history } as Partial<Task>);
+  }
+
+  updateMessage(id: string, messageId: string, updates: Partial<Message>): void {
+    const task = this.get(id);
+    if (!task?.history) return;
+    const history = task.history.map((m) =>
+      m.messageId === messageId ? { ...m, ...updates } : m,
+    );
+    this.updateTask(id, { history } as Partial<Task>);
+  }
+
+  getMessage(id: string, messageId: string): Message | undefined {
+    const task = this.get(id);
+    return task?.history?.find((m) => m.messageId === messageId);
+  }
+
+  getMessages(id: string): Message[] {
+    const task = this.get(id);
+    return task?.history ?? [];
+  }
+
+  clearMessages(id: string): void {
+    this.updateTask(id, { history: [] } as Partial<Task>);
+  }
+}
+
+export const a2aTaskStore = new A2ATaskStore();

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

@@ -0,0 +1,125 @@
+// server/modules/orchestration/a2a/types.ts
+// A2A protocol v0.2 types — minimal surface used by pixcode.
+// See https://a2a-protocol.org for the full spec; this file
+// keeps only what the orchestrator actually exchanges.
+
+export type TaskState =
+  | 'submitted'
+  | 'working'
+  | 'input-required'
+  | 'completed'
+  | 'canceled'
+  | 'failed';
+
+export type Role = 'user' | 'agent';
+
+export type PartKind = 'text' | 'file' | 'data';
+
+export interface TextPart {
+  kind: 'text';
+  text: string;
+}
+
+export interface FilePart {
+  kind: 'file';
+  name: string;
+  mimeType?: string;
+  bytesBase64?: string;
+  uri?: string;
+}
+
+export interface DataPart {
+  kind: 'data';
+  data: Record<string, unknown>;
+}
+
+export type Part = TextPart | FilePart | DataPart;
+
+export interface Message {
+  messageId: string;
+  role: Role;
+  parts: Part[];
+  /** Required for task-scoped messages. Omit only for broadcast/standalone messages. */
+  taskId?: string;
+}
+
+export type ArtifactType =
+  | 'file-diff'
+  | 'command-output'
+  | 'preview-url'
+  | 'data';
+
+// Note: Artifact and AuthScheme use `type` discriminator (matches A2A
+// v0.2 wire format). Part and BusEvent use `kind` per the same spec.
+export interface Artifact {
+  artifactId: string;
+  type: ArtifactType;
+  parts: Part[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface TaskError {
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+export interface Task {
+  id: string;
+  contextId?: string;
+  state: TaskState;
+  history: Message[];
+  artifacts: Artifact[];
+  error?: TaskError;
+  metadata?: Record<string, unknown>;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface TaskSummary {
+  id: string;
+  contextId?: string;
+  state: TaskState;
+  adapterId?: string;
+  adapterSelector?: string;
+  error?: TaskError;
+  createdAt: number;
+  updatedAt: number;
+  messageCount: number;
+  artifactCount: number;
+  lastMessage?: Message;
+}
+
+export interface AgentSkill {
+  id: string;
+  description: string;
+  examples?: string[];
+}
+
+export type AuthScheme =
+  | { type: 'none' }
+  | { type: 'bearer' }
+  | { type: 'mtls' };
+
+export interface AgentCard {
+  name: string;
+  description: string;
+  url: string;
+  version: string;
+  capabilities: string[];
+  skills: AgentSkill[];
+  authentication: AuthScheme;
+}
+
+export interface SubmitTaskInput {
+  message: Message;
+  contextId?: string;
+  metadata?: Record<string, unknown>;
+  /** Adapter id, "auto", or "skill:<id>". Resolved by the adapter registry. */
+  adapterId: string;
+}
+
+export type BusEvent =
+  | { kind: 'task-state'; taskId: string; state: TaskState; error?: TaskError }
+  | { kind: 'message'; taskId: string; message: Message }
+  | { kind: 'artifact'; taskId: string; artifact: Artifact };

package/server/modules/orchestration/a2a/validator.ts

@@ -0,0 +1,113 @@
+// server/modules/orchestration/a2a/validator.ts
+// Hand-written validators for incoming A2A payloads.
+// We deliberately avoid adding a new dep (zod, ajv) for the
+// foundation; a follow-on plan can swap to a schema lib if needed.
+//
+// All path strings use JSONPath-style "$" as the document root so
+// callers can map errors to wire-payload locations consistently.
+
+import type { AgentCard, DataPart, FilePart, Message, Part, SubmitTaskInput, TextPart } from '@/modules/orchestration/a2a/types.js';
+
+export class A2AValidationError extends Error {
+  constructor(message: string, public readonly path: string) {
+    super(`${path}: ${message}`);
+    this.name = 'A2AValidationError';
+  }
+}
+
+function assertNonEmptyString(value: unknown, path: string): asserts value is string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new A2AValidationError('expected non-empty string', path);
+  }
+}
+
+function assertOptionalNonEmptyString(value: unknown, path: string): void {
+  if (value === undefined) {
+    return;
+  }
+  assertNonEmptyString(value, path);
+}
+
+function assertPlainObject(value: unknown, path: string): void {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new A2AValidationError('expected plain object', path);
+  }
+}
+
+function assertPart(value: unknown, path: string): asserts value is Part {
+  if (!value || typeof value !== 'object') {
+    throw new A2AValidationError('expected object', path);
+  }
+  const part = value as { kind?: unknown };
+  if (part.kind === 'text') {
+    assertNonEmptyString((part as Partial<TextPart>).text, `${path}.text`);
+    return;
+  }
+  if (part.kind === 'file') {
+    assertNonEmptyString((part as Partial<FilePart>).name, `${path}.name`);
+    return;
+  }
+  if (part.kind === 'data') {
+    const data = (part as Partial<DataPart>).data;
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+      throw new A2AValidationError('data must be a plain object', `${path}.data`);
+    }
+    return;
+  }
+  throw new A2AValidationError('part.kind must be text|file|data', `${path}.kind`);
+}
+
+export function assertMessage(value: unknown, path = '$'): asserts value is Message {
+  if (!value || typeof value !== 'object') {
+    throw new A2AValidationError('expected object', path);
+  }
+  const m = value as { messageId?: unknown; role?: unknown; parts?: unknown; taskId?: unknown };
+  assertNonEmptyString(m.messageId, `${path}.messageId`);
+  if (m.role !== 'user' && m.role !== 'agent') {
+    throw new A2AValidationError('role must be user|agent', `${path}.role`);
+  }
+  if (!Array.isArray(m.parts) || m.parts.length === 0) {
+    throw new A2AValidationError('parts must be non-empty array', `${path}.parts`);
+  }
+  assertOptionalNonEmptyString(m.taskId, `${path}.taskId`);
+  m.parts.forEach((p, i) => assertPart(p, `${path}.parts[${i}]`));
+}
+
+export function assertSubmitTaskInput(value: unknown): asserts value is SubmitTaskInput {
+  if (!value || typeof value !== 'object') {
+    throw new A2AValidationError('expected object', '$');
+  }
+  const v = value as {
+    message?: unknown;
+    adapterId?: unknown;
+    contextId?: unknown;
+    metadata?: unknown;
+  };
+  assertMessage(v.message, '$.message');
+  assertNonEmptyString(v.adapterId, '$.adapterId');
+  assertOptionalNonEmptyString(v.contextId, '$.contextId');
+  if (v.metadata !== undefined) {
+    assertPlainObject(v.metadata, '$.metadata');
+  }
+}
+
+export function assertAgentCard(value: unknown): asserts value is AgentCard {
+  if (!value || typeof value !== 'object') {
+    throw new A2AValidationError('expected object', '$');
+  }
+  const card = value as Partial<AgentCard>;
+  assertNonEmptyString(card.name, '$.name');
+  assertNonEmptyString(card.description, '$.description');
+  assertNonEmptyString(card.url, '$.url');
+  assertNonEmptyString(card.version, '$.version');
+  if (!Array.isArray(card.capabilities)) {
+    throw new A2AValidationError('capabilities must be array', '$.capabilities');
+  }
+  if (!Array.isArray(card.skills)) {
+    throw new A2AValidationError('skills must be array', '$.skills');
+  }
+  card.skills.forEach((s, i) => {
+    assertNonEmptyString(s.id, `$.skills[${i}].id`);
+    assertNonEmptyString(s.description, `$.skills[${i}].description`);
+  });
+}

package/server/modules/orchestration/index.ts

@@ -0,0 +1,66 @@
+// server/modules/orchestration/index.ts
+// Public surface for the orchestration module.
+// All cross-module consumers must import from here per
+// eslint.config.js boundaries rules.
+
+export { createA2ARouter } from './a2a/routes.js';
+export { adapterRegistry } from './a2a/adapter-registry.js';
+export { ClaudeCodeA2AAdapter } from './a2a/adapters/claude-code.adapter.js';
+export { CodexA2AAdapter } from './a2a/adapters/codex.adapter.js';
+export { CursorA2AAdapter } from './a2a/adapters/cursor.adapter.js';
+export { GeminiA2AAdapter } from './a2a/adapters/gemini.adapter.js';
+export { QwenA2AAdapter } from './a2a/adapters/qwen.adapter.js';
+export { OpenCodeA2AAdapter } from './a2a/adapters/opencode.adapter.js';
+export type {
+  AdapterContext,
+  TaskHandle,
+} from './a2a/adapters/abstract-a2a.adapter.js';
+export { AbstractA2AAdapter } from './a2a/adapters/abstract-a2a.adapter.js';
+export { a2aBus } from './a2a/bus.js';
+export { portWatcher } from './preview/port-watcher.js';
+export { createPreviewProxyRouter } from './preview/preview-proxy.js';
+export { createOrchestrationTaskRouter } from './tasks/orchestration-task.routes.js';
+export { orchestrationTaskService } from './tasks/orchestration-task.service.js';
+export { createWorkflowRouter } from './workflows/workflow.routes.js';
+export { workflowRunner } from './workflows/workflow-runner.js';
+export { workflowStore } from './workflows/workflow-store.js';
+export { workspaceManager } from './workspace/workspace-manager.js';
+export type {
+  AgentCard,
+  Artifact,
+  ArtifactType,
+  BusEvent,
+  Message,
+  Part,
+  SubmitTaskInput,
+  Task,
+  TaskSummary,
+  TaskError,
+  TaskState,
+} from './a2a/types.js';
+export type {
+  PortEvent,
+  PreviewArtifactData,
+} from './preview/types.js';
+export type {
+  CreateOrchestrationTaskInput,
+  DispatchOrchestrationTaskInput,
+  OrchestrationTask,
+  OrchestrationTaskState,
+} from './tasks/orchestration-task.types.js';
+export type {
+  Workflow,
+  WorkflowNode,
+  WorkflowNodeRun,
+  WorkflowNodeStatus,
+  WorkflowRun,
+  WorkflowRunStatus,
+} from './workflows/workflow.types.js';
+export type {
+  ExecResult,
+  WorkspaceHandle,
+  WorkspaceKind,
+  WorkspaceMetadata,
+  WorkspaceRequest,
+} from './workspace/types.js';
+export { WorkspaceError } from './workspace/types.js';

package/server/modules/orchestration/preview/port-watcher.ts

@@ -0,0 +1,112 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+import type { PortEvent } from '@/modules/orchestration/preview/types.js';
+import type { WorkspaceHandle } from '@/modules/orchestration/workspace/types.js';
+
+const execFileAsync = promisify(execFile);
+
+interface WatchOptions {
+  taskId: string;
+  workspace: WorkspaceHandle;
+  intervalMs?: number;
+  onPort(event: PortEvent): void;
+}
+
+interface ListeningPort {
+  port: number;
+  host: string;
+  processName?: string;
+}
+
+const knownPreviewPorts = new Map<number, PortEvent>();
+
+function parseAddress(address: string): { host: string; port: number } | null {
+  const normalized = address.trim();
+  const idx = normalized.lastIndexOf(':');
+  if (idx === -1) return null;
+  const port = Number.parseInt(normalized.slice(idx + 1), 10);
+  if (!Number.isFinite(port) || port <= 0) return null;
+  const host = normalized.slice(0, idx).replace(/^\[|\]$/g, '') || '127.0.0.1';
+  return { host: host === '*' || host === '0.0.0.0' ? '127.0.0.1' : host, port };
+}
+
+function parseSs(output: string): ListeningPort[] {
+  const ports: ListeningPort[] = [];
+  for (const line of output.split('\n')) {
+    if (!line.includes('LISTEN')) continue;
+    const parts = line.trim().split(/\s+/);
+    const address = parts[3] ?? parts[4];
+    const parsed = address ? parseAddress(address) : null;
+    if (!parsed) continue;
+    const processMatch = line.match(/users:\(\("([^"]+)"/);
+    ports.push({
+      ...parsed,
+      processName: processMatch?.[1],
+    });
+  }
+  return ports;
+}
+
+async function readListeningPorts(): Promise<ListeningPort[]> {
+  try {
+    const { stdout } = await execFileAsync('ss', ['-ltnp'], {
+      maxBuffer: 1024 * 1024,
+    });
+    return parseSs(String(stdout));
+  } catch {
+    return [];
+  }
+}
+
+export function getKnownPreviewPort(port: number): PortEvent | undefined {
+  return knownPreviewPorts.get(port);
+}
+
+export class PortWatcher {
+  watch(options: WatchOptions): () => void {
+    const {
+      taskId,
+      workspace,
+      intervalMs = 1000,
+      onPort,
+    } = options;
+    const seen = new Set<number>();
+    let stopped = false;
+    let timer: NodeJS.Timeout | undefined;
+    let initialized = false;
+
+    const tick = async () => {
+      if (stopped) return;
+      const ports = await readListeningPorts();
+      for (const port of ports) {
+        if (seen.has(port.port)) continue;
+        seen.add(port.port);
+        if (!initialized) continue;
+        const event: PortEvent = {
+          taskId,
+          workspaceId: workspace.id,
+          port: port.port,
+          host: port.host,
+          url: `http://${port.host}:${port.port}`,
+          processName: port.processName,
+          confidence: 'low',
+          detectedAt: Date.now(),
+        };
+        knownPreviewPorts.set(port.port, event);
+        onPort(event);
+      }
+      initialized = true;
+      timer = setTimeout(tick, intervalMs);
+    };
+
+    void tick();
+
+    return () => {
+      stopped = true;
+      if (timer) clearTimeout(timer);
+    };
+  }
+}
+
+export const portWatcher = new PortWatcher();

package/server/modules/orchestration/preview/preview-proxy.ts

@@ -0,0 +1,60 @@
+import type { RequestHandler, Router } from 'express';
+import express from 'express';
+
+import { getKnownPreviewPort } from '@/modules/orchestration/preview/port-watcher.js';
+
+function buildTargetUrl(port: number, path: string): string {
+  const event = getKnownPreviewPort(port);
+  const host = event?.host ?? '127.0.0.1';
+  return `http://${host}:${port}${path}`;
+}
+
+function proxyHandler(): RequestHandler {
+  return async (req, res) => {
+    const rawPort = Array.isArray(req.params.port) ? req.params.port[0] : req.params.port;
+    const port = Number.parseInt(rawPort, 10);
+    if (!Number.isFinite(port) || port <= 0 || !getKnownPreviewPort(port)) {
+      res.status(404).json({
+        error: {
+          code: 'PREVIEW_PORT_NOT_FOUND',
+          message: 'Preview port is not registered for an orchestration task.',
+        },
+      });
+      return;
+    }
+
+    const path = req.originalUrl.replace(/^\/preview\/\d+/, '') || '/';
+    const target = buildTargetUrl(port, path);
+    try {
+      const upstream = await fetch(target, {
+        method: req.method,
+        headers: {
+          accept: req.header('accept') ?? '*/*',
+          'user-agent': req.header('user-agent') ?? 'pixcode-preview-proxy',
+        },
+      });
+      res.status(upstream.status);
+      upstream.headers.forEach((value, key) => {
+        const lower = key.toLowerCase();
+        if (lower === 'content-encoding' || lower === 'content-length') return;
+        if (lower === 'x-frame-options' || lower === 'content-security-policy') return;
+        res.setHeader(key, value);
+      });
+      res.send(Buffer.from(await upstream.arrayBuffer()));
+    } catch (error) {
+      res.status(502).json({
+        error: {
+          code: 'PREVIEW_PROXY_FAILED',
+          message: error instanceof Error ? error.message : String(error),
+        },
+      });
+    }
+  };
+}
+
+export function createPreviewProxyRouter(): Router {
+  const router = express.Router();
+  router.use('/:port', proxyHandler());
+  router.use('/:port/*', proxyHandler());
+  return router;
+}

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

@@ -0,0 +1,19 @@
+export interface PortEvent {
+  taskId: string;
+  workspaceId?: string;
+  port: number;
+  host: string;
+  url: string;
+  processName?: string;
+  confidence: 'low' | 'medium' | 'high';
+  detectedAt: number;
+}
+
+export interface PreviewArtifactData {
+  url: string;
+  proxiedUrl: string;
+  port: number;
+  host: string;
+  processName?: string;
+  confidence: 'low' | 'medium' | 'high';
+}