@pixelbyte-software/pixcode 1.33.11 → 1.34.0

package/server/modules/orchestration/a2a/agent-card.ts

@@ -0,0 +1,55 @@
+// server/modules/orchestration/a2a/agent-card.ts
+// Pixcode advertises itself as one A2A agent at /a2a/.well-known/agent-card.json.
+// Per-CLI adapters publish their own cards under /a2a/agents/:id/agent-card.
+
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { adapterRegistry } from '@/modules/orchestration/a2a/adapter-registry.js';
+import type { AgentCard } from '@/modules/orchestration/a2a/types.js';
+
+// Resolve <repo-root>/package.json from this file's location.
+// Source layout:    server/modules/orchestration/a2a/agent-card.ts        (4 levels deep from repo root)
+// Built layout:     dist-server/server/modules/orchestration/a2a/agent-card.js  (5 levels deep)
+// Walk up until a package.json containing "name":"@pixelbyte-software/pixcode" is found.
+function readPixcodeVersion(): string {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 8; i++) {
+    try {
+      const candidate = resolve(dir, 'package.json');
+      const raw = readFileSync(candidate, 'utf8');
+      const pkg = JSON.parse(raw) as { name?: string; version?: string };
+      if (pkg.name === '@pixelbyte-software/pixcode' && typeof pkg.version === 'string') {
+        return pkg.version;
+      }
+    } catch {
+      // not here, walk up
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return '0.0.0-dev';
+}
+
+const VERSION: string = readPixcodeVersion();
+
+export function buildPixcodeAgentCard(baseUrl: string): AgentCard {
+  const skills = adapterRegistry
+    .agentCards()
+    .flatMap((card) => card.skills)
+    .filter((skill, idx, arr) => arr.findIndex((s) => s.id === skill.id) === idx);
+
+  return {
+    name: 'pixcode',
+    description:
+      'Pixcode multi-CLI orchestration platform. Routes A2A tasks to ' +
+      'Claude Code, Codex, Cursor, Gemini, Qwen, or OpenCode adapters.',
+    url: `${baseUrl.replace(/\/$/, '')}/a2a`,
+    version: VERSION,
+    capabilities: ['streaming', 'taskRouting'],
+    skills,
+    authentication: { type: 'bearer' },
+  };
+}

package/server/modules/orchestration/a2a/auth.middleware.ts

@@ -0,0 +1,29 @@
+// server/modules/orchestration/a2a/auth.middleware.ts
+// Localhost callers bypass auth; everyone else needs a Bearer JWT
+// validated by pixcode's existing auth stack.
+
+import type { NextFunction, Request, Response } from 'express';
+
+// @ts-ignore — plain-JS module without type declarations
+// eslint-disable-next-line boundaries/no-unknown -- server/middleware/auth.js is a top-level auth runtime not yet classified by eslint.config.js; cleanup deferred.
+import { authenticateToken } from '@/middleware/auth.js';
+
+const LOCAL_HOSTS = new Set(['127.0.0.1', '::1', 'localhost', '::ffff:127.0.0.1']);
+
+function isLocalRequest(req: Request): boolean {
+  const remote = req.socket.remoteAddress ?? '';
+  if (LOCAL_HOSTS.has(remote)) return true;
+  // Trust the X-Forwarded-For header only when the inbound socket is local
+  // (i.e. the reverse proxy itself is on the same host).
+  return false;
+}
+
+export function a2aAuth(req: Request, res: Response, next: NextFunction): void {
+  if (isLocalRequest(req)) {
+    next();
+    return;
+  }
+  // Delegate to existing pixcode JWT middleware. authenticateToken
+  // populates req.user on success and 401s on failure.
+  authenticateToken(req, res, next);
+}

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

@@ -0,0 +1,46 @@
+// server/modules/orchestration/a2a/bus.ts
+// In-process pub/sub on top of Node's EventEmitter.
+// Subscribers receive every event for a given taskId; an
+// "all" subscriber receives every event regardless of task.
+// Note: the literal taskId "__all__" is reserved for the broadcast
+// channel; callers must not use it as a real taskId.
+
+import { EventEmitter } from 'node:events';
+
+import type { BusEvent } from '@/modules/orchestration/a2a/types.js';
+
+type Listener = (event: BusEvent) => void;
+
+const ALL = '__all__';
+
+class A2ABus {
+  private readonly emitter = new EventEmitter();
+
+  constructor() {
+    this.emitter.setMaxListeners(0); // SSE clients can be numerous
+  }
+
+  /** Synchronous: listeners run before publish() returns. */
+  publish(event: BusEvent): void {
+    this.emitter.emit(event.taskId, event);
+    this.emitter.emit(ALL, event);
+  }
+
+  /** Subscribe to events for a specific taskId. Returns an unsubscribe
+   *  function — caller MUST invoke it to release the listener; the bus
+   *  retains a strong reference until then. */
+  subscribe(taskId: string, listener: Listener): () => void {
+    this.emitter.on(taskId, listener);
+    return () => this.emitter.off(taskId, listener);
+  }
+
+  /** Subscribe to ALL events. Returns an unsubscribe function with the
+   *  same release semantics as subscribe(). */
+  subscribeAll(listener: Listener): () => void {
+    this.emitter.on(ALL, listener);
+    return () => this.emitter.off(ALL, listener);
+  }
+}
+
+export const a2aBus = new A2ABus();
+export type { A2ABus };

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

@@ -0,0 +1,264 @@
+// server/modules/orchestration/a2a/routes.ts
+// HTTP surface for A2A v0.2. Mounted at /a2a in server/index.js.
+
+import crypto from 'node:crypto';
+
+import type { Request, Response, Router } from 'express';
+import express from 'express';
+
+import { adapterRegistry } from '@/modules/orchestration/a2a/adapter-registry.js';
+import { buildPixcodeAgentCard } from '@/modules/orchestration/a2a/agent-card.js';
+import { a2aAuth } from '@/modules/orchestration/a2a/auth.middleware.js';
+import { a2aBus } from '@/modules/orchestration/a2a/bus.js';
+import type {
+  BusEvent,
+  Message,
+  Task,
+  TaskState,
+} from '@/modules/orchestration/a2a/types.js';
+import {
+  A2AValidationError,
+  assertMessage,
+  assertSubmitTaskInput,
+} from '@/modules/orchestration/a2a/validator.js';
+
+// In-memory task store. Persistence is out of scope for the foundation;
+// a follow-on plan adds SQLite-backed storage.
+const tasks = new Map<string, Task>();
+// Per-task bus unsubscribe handles; called on terminal state.
+const taskUnsubs = new Map<string, () => void>();
+// Eviction timeouts (terminal tasks live for 1 hour before being purged).
+const taskEvictions = new Map<string, NodeJS.Timeout>();
+const TERMINAL_TASK_TTL_MS = 60 * 60 * 1000; // 1 hour
+const MAX_TASKS = 1000;
+
+function newId(prefix: string): string {
+  return `${prefix}_${crypto.randomBytes(8).toString('hex')}`;
+}
+
+function getBaseUrl(req: Request): string {
+  // TODO: this trusts X-Forwarded-Proto/Host without checking app's
+  // trust-proxy setting. Same posture as auth.middleware.ts; revisit
+  // when project-wide trust-proxy decision lands.
+  const proto = req.header('x-forwarded-proto') ?? req.protocol;
+  const host = req.header('x-forwarded-host') ?? req.get('host');
+  return `${proto}://${host}`;
+}
+
+function attachBusToTask(task: Task): void {
+  const unsubscribe = a2aBus.subscribe(task.id, (event: BusEvent) => {
+    if (event.kind === 'task-state') {
+      task.state = event.state;
+      if (event.error) task.error = event.error;
+      task.updatedAt = Date.now();
+      if (event.state === 'completed' || event.state === 'canceled' || event.state === 'failed') {
+        // Release the listener; schedule eviction.
+        const unsub = taskUnsubs.get(task.id);
+        if (unsub) {
+          unsub();
+          taskUnsubs.delete(task.id);
+        }
+        const existingTimeout = taskEvictions.get(task.id);
+        if (existingTimeout) clearTimeout(existingTimeout);
+        taskEvictions.set(
+          task.id,
+          setTimeout(() => {
+            tasks.delete(task.id);
+            taskEvictions.delete(task.id);
+          }, TERMINAL_TASK_TTL_MS),
+        );
+      }
+    } else if (event.kind === 'message') {
+      task.history.push(event.message);
+      task.updatedAt = Date.now();
+    } else if (event.kind === 'artifact') {
+      task.artifacts.push(event.artifact);
+      task.updatedAt = Date.now();
+    }
+  });
+  taskUnsubs.set(task.id, unsubscribe);
+}
+
+export function createA2ARouter(): Router {
+  const router: Router = express.Router();
+
+  router.use(express.json({ limit: '5mb' }));
+  router.use(a2aAuth);
+
+  // Discovery
+  router.get('/.well-known/agent-card.json', (req, res) => {
+    res.json(buildPixcodeAgentCard(getBaseUrl(req)));
+  });
+
+  router.get('/agents', (_req, res) => {
+    res.json({ agents: adapterRegistry.agentCards() });
+  });
+
+  router.get('/agents/:id/agent-card', (req, res) => {
+    const adapter = adapterRegistry.get(req.params.id);
+    if (!adapter) {
+      res.status(404).json({ error: { code: 'AGENT_NOT_FOUND', message: req.params.id } });
+      return;
+    }
+    res.json(adapter.agentCard);
+  });
+
+  // Task lifecycle
+  router.post('/tasks', async (req: Request, res: Response) => {
+    try {
+      assertSubmitTaskInput(req.body);
+    } catch (err) {
+      const e = err as A2AValidationError;
+      res.status(400).json({ error: { code: 'INVALID_INPUT', message: e.message, path: e.path } });
+      return;
+    }
+
+    const adapter = adapterRegistry.get(req.body.adapterId);
+    if (!adapter) {
+      res.status(404).json({
+        error: { code: 'ADAPTER_NOT_FOUND', message: req.body.adapterId },
+      });
+      return;
+    }
+
+    // Enforce MAX_TASKS cap. Evict the oldest terminal task first; if all
+    // active, fail closed with 503.
+    if (tasks.size >= MAX_TASKS) {
+      let evicted = false;
+      for (const [tid, t] of tasks) {
+        if (t.state === 'completed' || t.state === 'canceled' || t.state === 'failed') {
+          const timeout = taskEvictions.get(tid);
+          if (timeout) clearTimeout(timeout);
+          taskEvictions.delete(tid);
+          const unsub = taskUnsubs.get(tid);
+          if (unsub) {
+            unsub();
+            taskUnsubs.delete(tid);
+          }
+          tasks.delete(tid);
+          evicted = true;
+          break;
+        }
+      }
+      if (!evicted) {
+        res.status(503).json({
+          error: { code: 'TASK_LIMIT', message: `task store at capacity (${MAX_TASKS})` },
+        });
+        return;
+      }
+    }
+
+    const userMessage: Message = req.body.message;
+    const task: Task = {
+      id: newId('task'),
+      contextId: req.body.contextId,
+      state: 'submitted',
+      history: [userMessage],
+      artifacts: [],
+      metadata: req.body.metadata,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    };
+    tasks.set(task.id, task);
+    // Persist adapterId in metadata so cancel can resolve the owning adapter
+    // even when the original request body is no longer available.
+    task.metadata = { ...task.metadata, adapterId: req.body.adapterId };
+    attachBusToTask(task);
+
+    try {
+      await adapter.submitTask(task, { cwd: process.cwd() });
+    } catch (err) {
+      // Publish to bus so SSE subscribers and the attachBusToTask listener
+      // both see the failure transition. The listener mutates the stored
+      // task in place, so the 202 body still reflects the failed state.
+      a2aBus.publish({
+        kind: 'task-state',
+        taskId: task.id,
+        state: 'failed',
+        error: {
+          code: 'ADAPTER_SUBMIT_FAILED',
+          message: err instanceof Error ? err.message : String(err),
+        },
+      });
+    }
+
+    res.status(202).json(task);
+  });
+
+  router.get('/tasks/:id', (req, res) => {
+    const task = tasks.get(req.params.id);
+    if (!task) {
+      res.status(404).json({ error: { code: 'TASK_NOT_FOUND', message: req.params.id } });
+      return;
+    }
+    res.json(task);
+  });
+
+  router.get('/tasks/:id/stream', (req, res) => {
+    const task = tasks.get(req.params.id);
+    if (!task) {
+      res.status(404).json({ error: { code: 'TASK_NOT_FOUND', message: req.params.id } });
+      return;
+    }
+    res.setHeader('Content-Type', 'text/event-stream');
+    res.setHeader('Cache-Control', 'no-cache, no-transform');
+    res.setHeader('Connection', 'keep-alive');
+    res.flushHeaders();
+
+    // Replay current state once so late subscribers see history.
+    const initial = { kind: 'task-snapshot' as const, task };
+    res.write(`event: snapshot\ndata: ${JSON.stringify(initial)}\n\n`);
+
+    const TERMINAL: TaskState[] = ['completed', 'canceled', 'failed'];
+    const unsubscribe = a2aBus.subscribe(task.id, (event) => {
+      res.write(`event: ${event.kind}\ndata: ${JSON.stringify(event)}\n\n`);
+      if (event.kind === 'task-state' && TERMINAL.includes(event.state)) {
+        res.end();
+      }
+    });
+
+    req.on('close', () => {
+      unsubscribe();
+    });
+  });
+
+  router.post('/tasks/:id/cancel', async (req, res) => {
+    const task = tasks.get(req.params.id);
+    if (!task) {
+      res.status(404).json({ error: { code: 'TASK_NOT_FOUND', message: req.params.id } });
+      return;
+    }
+    // Look up the adapter that owns this task. We stored adapterId in metadata.
+    const adapterId = req.body?.adapterId ?? task.metadata?.adapterId;
+    const adapter = typeof adapterId === 'string' ? adapterRegistry.get(adapterId) : undefined;
+    if (!adapter) {
+      res.status(400).json({
+        error: {
+          code: 'ADAPTER_REQUIRED',
+          message: 'Provide adapterId to cancel a task whose adapter is unknown',
+        },
+      });
+      return;
+    }
+    await adapter.cancelTask(task.id);
+    res.json(tasks.get(task.id));
+  });
+
+  router.post('/messages', (req, res) => {
+    try {
+      assertMessage(req.body);
+    } catch (err) {
+      const e = err as A2AValidationError;
+      res.status(400).json({ error: { code: 'INVALID_INPUT', message: e.message, path: e.path } });
+      return;
+    }
+    a2aBus.publish({
+      kind: 'message',
+      taskId: req.body.taskId ?? 'broadcast',
+      message: req.body,
+    });
+    res.status(202).json({ accepted: true });
+  });
+
+  return router;
+}

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

@@ -0,0 +1,111 @@
+// 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 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,90 @@
+// 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 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 };
+  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`);
+  }
+  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 };
+  assertMessage(v.message, '$.message');
+  assertNonEmptyString(v.adapterId, '$.adapterId');
+}
+
+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,26 @@
+// 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 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 type {
+  AgentCard,
+  Artifact,
+  ArtifactType,
+  BusEvent,
+  Message,
+  Part,
+  SubmitTaskInput,
+  Task,
+  TaskError,
+  TaskState,
+} from './a2a/types.js';