@pixelbyte-software/pixcode 1.33.10 → 1.34.0

package/server/modules/orchestration/a2a/adapters/claude-code.adapter.ts

@@ -0,0 +1,283 @@
+// server/modules/orchestration/a2a/adapters/claude-code.adapter.ts
+// Wraps the existing server/claude-sdk.js queryClaudeSDK() function.
+// claude-sdk.js was designed to stream SDK messages over a WebSocket
+// connection, so we feed it a "fake WS" that captures send() calls and
+// emits A2A bus events instead.
+//
+// IMPORTANT: claude-sdk.js calls ws.send(<NormalizedMessage object>) — it
+// does NOT JSON.stringify before send. Our shim therefore receives objects
+// (not strings) and dispatches on `frame.kind` (not `frame.type`). See
+// server/shared/types.ts for the MessageKind enum.
+
+import crypto from 'node:crypto';
+
+// eslint-disable-next-line boundaries/no-unknown -- claude-sdk.js is a top-level CLI runtime not yet classified by eslint.config.js; cleanup deferred (cascades into a server/services classification gap).
+import { abortClaudeSDKSession, queryClaudeSDK } from '@/claude-sdk.js';
+import { AbstractA2AAdapter } from '@/modules/orchestration/a2a/adapters/abstract-a2a.adapter.js';
+import type {
+  AdapterContext,
+  TaskHandle,
+} from '@/modules/orchestration/a2a/adapters/abstract-a2a.adapter.js';
+import type { AgentCard, Part, Task } from '@/modules/orchestration/a2a/types.js';
+
+interface FakeWS {
+  send(data: unknown): void;
+  readyState: number;
+}
+
+// WebSocket.OPEN per the ws library — claude-sdk.js gates send() on readyState === 1.
+const WS_OPEN = 1;
+
+function joinPartsToPrompt(parts: Part[]): string {
+  return parts
+    .map((p) => {
+      if (p.kind === 'text') return p.text;
+      if (p.kind === 'data') return JSON.stringify(p.data);
+      // file parts: include name + uri/inline marker
+      return `[file:${p.name}${p.uri ? ` uri=${p.uri}` : ''}]`;
+    })
+    .join('\n');
+}
+
+function newId(prefix: string): string {
+  return `${prefix}_${crypto.randomBytes(8).toString('hex')}`;
+}
+
+export class ClaudeCodeA2AAdapter extends AbstractA2AAdapter {
+  readonly id = 'claude-code';
+
+  readonly agentCard: AgentCard = {
+    name: 'pixcode-claude-code',
+    description: 'Anthropic Claude Code, accessed via Pixcode',
+    url: '/a2a/agents/claude-code',
+    version: '1.0.0',
+    capabilities: ['streaming', 'fileEdit', 'commandExec', 'mcp'],
+    skills: [
+      {
+        id: 'architectural-review',
+        description: 'Review code architecture and propose structural changes',
+      },
+      {
+        id: 'typescript-edit',
+        description: 'Edit TypeScript files with type-aware reasoning',
+      },
+      {
+        id: 'multi-file-refactor',
+        description: 'Coordinated edits across many files',
+      },
+      {
+        id: 'test-run',
+        description: 'Run test suites and react to results',
+      },
+    ],
+    authentication: { type: 'bearer' },
+  };
+
+  private readonly active = new Map<string, { sessionId: string | null }>();
+
+  async submitTask(task: Task, ctx: AdapterContext): Promise<TaskHandle> {
+    // Foundation: only the last user message is fed in. Multi-turn resumption
+    // (input-required tasks, workflow chaining) needs to pass options.sessionId
+    // and append history; deferred to a follow-on plan.
+    const promptText = joinPartsToPrompt(
+      task.history[task.history.length - 1]?.parts ?? [],
+    );
+    const session = { sessionId: null as string | null };
+    this.active.set(task.id, session);
+
+    this.emitState(task.id, 'working');
+
+    const fakeWS: FakeWS = {
+      readyState: WS_OPEN,
+      send: (data) => this.handleSdkFrame(task.id, data, session),
+    };
+
+    const finished = (async () => {
+      try {
+        await queryClaudeSDK(
+          promptText,
+          {
+            cwd: ctx.cwd,
+            permissionMode: ctx.permissionMode ?? 'default',
+          },
+          fakeWS,
+        );
+        // If cancelTask removed us from `active` first, suppress the spurious
+        // 'completed' that would otherwise race the 'canceled' state.
+        if (this.active.has(task.id)) {
+          this.emitState(task.id, 'completed');
+        }
+      } catch (err) {
+        if (this.active.has(task.id)) {
+          this.emitState(task.id, 'failed', {
+            code: 'ADAPTER_RUNTIME_ERROR',
+            message: err instanceof Error ? err.message : String(err),
+          });
+        }
+      } finally {
+        this.active.delete(task.id);
+      }
+    })();
+
+    return {
+      cancel: () => this.cancelTask(task.id),
+      finished,
+    };
+  }
+
+  async cancelTask(taskId: string): Promise<void> {
+    const session = this.active.get(taskId);
+    if (!session) {
+      this.emitState(taskId, 'canceled');
+      return;
+    }
+    // Delete BEFORE awaiting so submitTask's IIFE guard (this.active.has)
+    // suppresses the spurious 'completed' state when queryClaudeSDK's
+    // for-await loop unwinds from the abort.
+    this.active.delete(taskId);
+    if (session.sessionId) {
+      try {
+        await abortClaudeSDKSession(session.sessionId);
+      } catch {
+        // swallow — adapter has already cleaned its own state
+      }
+    }
+    this.emitState(taskId, 'canceled');
+  }
+
+  /**
+   * claude-sdk.js calls `ws.send(<NormalizedMessage>)` with a JS OBJECT
+   * (not a JSON string). We translate each frame into A2A bus events.
+   * See server/shared/types.ts for the MessageKind union.
+   */
+  private handleSdkFrame(
+    taskId: string,
+    frame: unknown,
+    session: { sessionId: string | null },
+  ): void {
+    if (!frame || typeof frame !== 'object') return;
+    const f = frame as {
+      kind?: string;
+      sessionId?: unknown;
+      newSessionId?: unknown;
+      text?: unknown;
+      content?: unknown;
+      toolName?: unknown;
+      toolInput?: unknown;
+      toolResult?: unknown;
+    };
+
+    // session_created carries the new session id in `newSessionId`. Capture
+    // it here so cancelTask can call abortClaudeSDKSession with the right id.
+    if (
+      f.kind === 'session_created' &&
+      typeof f.newSessionId === 'string' &&
+      !session.sessionId
+    ) {
+      session.sessionId = f.newSessionId;
+    }
+
+    switch (f.kind) {
+      case 'session_created':
+      case 'status':
+      case 'stream_delta':
+      case 'stream_end':
+        // session_created and status are not user-facing.
+        // stream_delta and stream_end CARRY user-visible delta text but are
+        // not currently emitted by claude-sdk.js (it doesn't pass
+        // includePartialMessages: true to query()). If that flag flips on
+        // upstream, these cases must be re-routed to emit text Messages.
+        return;
+
+      case 'text':
+      case 'thinking': {
+        const text =
+          typeof f.text === 'string'
+            ? f.text
+            : typeof f.content === 'string'
+              ? f.content
+              : null;
+        if (text) {
+          this.emitMessage(taskId, {
+            messageId: newId('msg'),
+            role: 'agent',
+            parts: [{ kind: 'text', text }],
+            taskId,
+          });
+        }
+        return;
+      }
+
+      case 'tool_use': {
+        this.emitArtifact(taskId, {
+          artifactId: newId('art'),
+          type: 'command-output',
+          parts: [
+            {
+              kind: 'data',
+              data: { toolName: f.toolName, toolInput: f.toolInput },
+            },
+          ],
+          metadata: { source: 'claude-tool-use' },
+        });
+        return;
+      }
+
+      case 'tool_result': {
+        this.emitArtifact(taskId, {
+          artifactId: newId('art'),
+          type: 'command-output',
+          parts: [{ kind: 'data', data: { toolResult: f.toolResult } }],
+          metadata: { source: 'claude-tool-result' },
+        });
+        return;
+      }
+
+      case 'permission_request':
+      case 'permission_cancelled':
+      case 'interactive_prompt':
+      case 'task_notification':
+        // Informational — surface as data artifact for visibility.
+        this.emitArtifact(taskId, {
+          artifactId: newId('art'),
+          type: 'data',
+          parts: [{ kind: 'data', data: f as Record<string, unknown> }],
+          metadata: { source: `claude-${f.kind}` },
+        });
+        return;
+
+      case 'error': {
+        // claude-sdk.js catches internally and emits an error frame without
+        // rethrowing, so the IIFE await would resolve cleanly. Force the
+        // failed state here and remove from active so the IIFE's
+        // 'completed' emit is suppressed by its active.has() guard.
+        const message =
+          typeof f.content === 'string'
+            ? f.content
+            : typeof f.text === 'string'
+              ? f.text
+              : 'Claude Code reported an error';
+        this.emitState(taskId, 'failed', {
+          code: 'CLAUDE_RUNTIME_ERROR',
+          message,
+          details: f as Record<string, unknown>,
+        });
+        this.active.delete(taskId);
+        return;
+      }
+
+      case 'complete':
+        // Lifecycle redundant with the IIFE's 'completed' emit; suppress to
+        // avoid double-signaling. The IIFE owns terminal state transitions.
+        return;
+
+      default:
+        // Unknown kind — surface for visibility
+        this.emitArtifact(taskId, {
+          artifactId: newId('art'),
+          type: 'data',
+          parts: [{ kind: 'data', data: f as Record<string, unknown> }],
+        });
+    }
+  }
+}

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;
+}