@pixelbyte-software/pixcode 1.33.11 → 1.34.0

package/dist-server/server/modules/orchestration/a2a/validator.js

@@ -0,0 +1,85 @@
+// 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.
+export class A2AValidationError extends Error {
+    path;
+    constructor(message, path) {
+        super(`${path}: ${message}`);
+        this.path = path;
+        this.name = 'A2AValidationError';
+    }
+}
+function assertNonEmptyString(value, path) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new A2AValidationError('expected non-empty string', path);
+    }
+}
+function assertPart(value, path) {
+    if (!value || typeof value !== 'object') {
+        throw new A2AValidationError('expected object', path);
+    }
+    const part = value;
+    if (part.kind === 'text') {
+        assertNonEmptyString(part.text, `${path}.text`);
+        return;
+    }
+    if (part.kind === 'file') {
+        assertNonEmptyString(part.name, `${path}.name`);
+        return;
+    }
+    if (part.kind === 'data') {
+        const data = part.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, path = '$') {
+    if (!value || typeof value !== 'object') {
+        throw new A2AValidationError('expected object', path);
+    }
+    const m = value;
+    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) {
+    if (!value || typeof value !== 'object') {
+        throw new A2AValidationError('expected object', '$');
+    }
+    const v = value;
+    assertMessage(v.message, '$.message');
+    assertNonEmptyString(v.adapterId, '$.adapterId');
+}
+export function assertAgentCard(value) {
+    if (!value || typeof value !== 'object') {
+        throw new A2AValidationError('expected object', '$');
+    }
+    const card = value;
+    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`);
+    });
+}
+//# sourceMappingURL=validator.js.map

package/dist-server/server/modules/orchestration/a2a/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../../../../server/modules/orchestration/a2a/validator.ts"],"names":[],"mappings":"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"}

package/dist-server/server/modules/orchestration/index.js

@@ -0,0 +1,10 @@
+// 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 { AbstractA2AAdapter } from './a2a/adapters/abstract-a2a.adapter.js';
+export { a2aBus } from './a2a/bus.js';
+//# sourceMappingURL=index.js.map

package/dist-server/server/modules/orchestration/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../server/modules/orchestration/index.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,+CAA+C;AAC/C,uDAAuD;AACvD,qCAAqC;AAErC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAK7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixelbyte-software/pixcode",
-  "version": "1.33.11",
+  "version": "1.34.0",
   "description": "Pixcode — a desktop and mobile web UI for Claude Code, Cursor CLI, Codex, Gemini CLI, Qwen Code, and OpenCode.",
   "type": "module",
   "main": "dist-server/server/index.js",

package/scripts/smoke/a2a-roundtrip.mjs

@@ -0,0 +1,98 @@
+// scripts/smoke/a2a-roundtrip.mjs
+// End-to-end smoke check for the A2A foundation.
+//
+// Usage:   node scripts/smoke/a2a-roundtrip.mjs [baseUrl]
+// Default: http://127.0.0.1:3001
+//
+// Pre-reqs:
+//   - pixcode server running (npm run server:dev-watch)
+//   - ANTHROPIC_API_KEY (or pixcode auth) configured for Claude Code
+//
+// What it does:
+//   1. GET /a2a/.well-known/agent-card.json   - sanity check
+//   2. GET /a2a/agents                        - confirms claude-code is registered
+//   3. POST /a2a/tasks                        - submits a tiny task
+//   4. Streams /a2a/tasks/:id/stream          - prints events until terminal state
+//
+// Pass/fail:
+//   Exits 0 on terminal state "completed". Non-zero otherwise.
+
+const baseUrl = process.argv[2] ?? 'http://127.0.0.1:3001';
+
+async function jget(path) {
+  const r = await fetch(`${baseUrl}${path}`);
+  if (!r.ok) throw new Error(`GET ${path} -> ${r.status}`);
+  return r.json();
+}
+
+async function main() {
+  console.log('1) /a2a/.well-known/agent-card.json');
+  const card = await jget('/a2a/.well-known/agent-card.json');
+  console.log('   name=', card.name, 'version=', card.version);
+  if (card.name !== 'pixcode') throw new Error('AgentCard.name != "pixcode"');
+
+  console.log('2) /a2a/agents');
+  const agents = await jget('/a2a/agents');
+  const ids = agents.agents.map((a) => a.name);
+  console.log('   registered:', ids.join(', '));
+  if (!ids.includes('pixcode-claude-code')) {
+    throw new Error('claude-code adapter not registered');
+  }
+
+  console.log('3) POST /a2a/tasks');
+  const submitRes = await fetch(`${baseUrl}/a2a/tasks`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      adapterId: 'claude-code',
+      message: {
+        messageId: 'm_smoke_1',
+        role: 'user',
+        parts: [{ kind: 'text', text: 'Reply with the single word: ok' }],
+      },
+    }),
+  });
+  if (!submitRes.ok) throw new Error(`submit -> ${submitRes.status}`);
+  const task = await submitRes.json();
+  console.log('   task.id=', task.id, 'state=', task.state);
+
+  console.log('4) GET /a2a/tasks/:id/stream (SSE)');
+  const streamRes = await fetch(`${baseUrl}/a2a/tasks/${task.id}/stream`);
+  if (!streamRes.ok) throw new Error(`stream -> ${streamRes.status}`);
+
+  const reader = streamRes.body.getReader();
+  const dec = new TextDecoder();
+  let buffer = '';
+  let terminalState = null;
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += dec.decode(value, { stream: true });
+
+    let idx;
+    while ((idx = buffer.indexOf('\n\n')) !== -1) {
+      const frame = buffer.slice(0, idx);
+      buffer = buffer.slice(idx + 2);
+      const dataLine = frame.split('\n').find((l) => l.startsWith('data: '));
+      if (!dataLine) continue;
+      const event = JSON.parse(dataLine.slice('data: '.length));
+      console.log('   event:', event.kind ?? 'snapshot', '->', event);
+      if (event.kind === 'task-state') {
+        terminalState = event.state;
+        if (['completed', 'canceled', 'failed'].includes(terminalState)) break;
+      }
+    }
+    if (terminalState && ['completed', 'canceled', 'failed'].includes(terminalState)) break;
+  }
+
+  console.log('terminal state:', terminalState);
+  if (terminalState !== 'completed') {
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('SMOKE FAILED:', err);
+  process.exit(2);
+});

package/server/index.js

@@ -71,6 +71,11 @@ import qwenRoutes from './routes/qwen.js';
 import pluginsRoutes from './routes/plugins.js';
 import messagesRoutes from './routes/messages.js';
 import providerRoutes from './modules/providers/provider.routes.js';
+import {
+  createA2ARouter,
+  adapterRegistry,
+  ClaudeCodeA2AAdapter,
+} from './modules/orchestration/index.js';
 import networkRoutes from './routes/network.js';
 import telegramRoutes from './routes/telegram.js';
 import { restoreBotFromConfig } from './services/telegram/bot.js';
@@ -376,6 +381,10 @@ app.use('/api/sessions', authenticateToken, messagesRoutes);
 // Unified provider MCP routes (protected)
 app.use('/api/providers', authenticateToken, providerRoutes);
 
+// A2A protocol router — has its own auth middleware, do NOT wrap with authenticateToken
+adapterRegistry.register(new ClaudeCodeA2AAdapter());
+app.use('/a2a', createA2ARouter());
+
 // Network discovery / QR endpoints (protected)
 app.use('/api/network', authenticateToken, networkRoutes);
 

package/server/modules/orchestration/a2a/adapter-registry.ts

@@ -0,0 +1,58 @@
+// server/modules/orchestration/a2a/adapter-registry.ts
+// In-process registry mapping adapter ids to AbstractA2AAdapter
+// instances. Resolution supports three id forms:
+//   - "claude-code"        explicit
+//   - "skill:<skillId>"    first REGISTERED adapter advertising that skill
+//                          (Map iteration is insertion-ordered per ES spec).
+//   - "auto"               first registered adapter (placeholder until
+//                          AI-suggested routing arrives in a later plan)
+
+import type { AbstractA2AAdapter } from '@/modules/orchestration/a2a/adapters/abstract-a2a.adapter.js';
+import type { AgentCard } from '@/modules/orchestration/a2a/types.js';
+
+class AdapterRegistry {
+  // Map iteration order is insertion-ordered (ES spec); auto and skill: resolution depend on this.
+  private readonly byId = new Map<string, AbstractA2AAdapter>();
+
+  register(adapter: AbstractA2AAdapter): void {
+    if (this.byId.has(adapter.id)) {
+      throw new Error(`A2A adapter already registered: ${adapter.id}`);
+    }
+    this.byId.set(adapter.id, adapter);
+  }
+
+  get(idOrSelector: string): AbstractA2AAdapter | undefined {
+    if (idOrSelector === 'auto') {
+      if (this.byId.size > 1) {
+        throw new Error(
+          'A2A adapter selector "auto" is not yet implemented for multi-adapter registries. ' +
+          'Pass an explicit adapter id ("claude-code") or a "skill:<id>" selector. ' +
+          'AI-suggested routing will replace this stub in a later plan.',
+        );
+      }
+      const first = this.byId.values().next().value;
+      return first ?? undefined;
+    }
+    if (idOrSelector.startsWith('skill:')) {
+      const skill = idOrSelector.slice('skill:'.length);
+      for (const adapter of this.byId.values()) {
+        if (adapter.agentCard.skills.some((s) => s.id === skill)) {
+          return adapter;
+        }
+      }
+      return undefined;
+    }
+    return this.byId.get(idOrSelector);
+  }
+
+  list(): AbstractA2AAdapter[] {
+    return [...this.byId.values()];
+  }
+
+  agentCards(): AgentCard[] {
+    return this.list().map((a) => a.agentCard);
+  }
+}
+
+export const adapterRegistry = new AdapterRegistry();
+export type { AdapterRegistry };

package/server/modules/orchestration/a2a/adapters/abstract-a2a.adapter.ts

@@ -0,0 +1,49 @@
+// server/modules/orchestration/a2a/adapters/abstract-a2a.adapter.ts
+// Base class every CLI adapter extends. Adapters wrap the
+// existing per-CLI runtime files (claude-sdk.js, openai-codex.js, ...)
+// and translate between A2A messages and the CLI's native I/O.
+
+import { a2aBus } from '@/modules/orchestration/a2a/bus.js';
+import type {
+  AgentCard,
+  Artifact,
+  Message,
+  Task,
+  TaskError,
+  TaskState,
+} from '@/modules/orchestration/a2a/types.js';
+
+export interface AdapterContext {
+  /** Where the adapter executes — for now this is the project cwd; a future
+   *  plan introduces WorkspaceHandle (worktree / docker). */
+  cwd: string;
+  /** pixcode permission mode passed through to the underlying CLI. */
+  permissionMode?: 'acceptEdits' | 'plan' | 'bypassPermissions' | 'default';
+  /** Optional parent task id when this adapter is invoked inside a workflow. */
+  parentTaskId?: string;
+}
+
+export interface TaskHandle {
+  cancel(): Promise<void>;
+  finished: Promise<void>;
+}
+
+export abstract class AbstractA2AAdapter {
+  abstract readonly id: string;
+  abstract readonly agentCard: AgentCard;
+
+  abstract submitTask(task: Task, ctx: AdapterContext): Promise<TaskHandle>;
+  abstract cancelTask(taskId: string): Promise<void>;
+
+  protected emitState(taskId: string, state: TaskState, error?: TaskError): void {
+    a2aBus.publish({ kind: 'task-state', taskId, state, error });
+  }
+
+  protected emitMessage(taskId: string, message: Message): void {
+    a2aBus.publish({ kind: 'message', taskId, message });
+  }
+
+  protected emitArtifact(taskId: string, artifact: Artifact): void {
+    a2aBus.publish({ kind: 'artifact', taskId, artifact });
+  }
+}

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> }],
+        });
+    }
+  }
+}