@pixelbyte-software/pixcode 1.33.11 → 1.35.0

package/server/database/json-store.js

@@ -29,7 +29,7 @@ import path from 'node:path';
 const CURRENT_VERSION = 1;
 
 // Tables the store manages — empty arrays on a fresh file.
-const EMPTY_STORE = () => ({
+const EMPTY_STORE = (extraTables = {}) => ({
   _version: CURRENT_VERSION,
   _sequences: {
     users: 0,
@@ -37,6 +37,7 @@ const EMPTY_STORE = () => ({
     user_credentials: 0,
     vapid_keys: 0,
     push_subscriptions: 0,
+    ...Object.fromEntries(Object.keys(extraTables).map((k) => [k, 0])),
   },
   users: [],
   api_keys: [],
@@ -48,12 +49,14 @@ const EMPTY_STORE = () => ({
   app_config: [], // each row: { key, value, created_at }
   telegram_config: [], // 0 or 1 row: { id=1, bot_token, bot_username, updated_at }
   telegram_links: [], // each row: { user_id, chat_id, ... }
+  ...Object.fromEntries(Object.entries(extraTables).map(([k, v]) => [k, v ?? []])),
 });
 
 export class JsonStore {
-  constructor(filePath) {
+  constructor(filePath, extraTables = {}) {
     this.filePath = filePath;
     this.tmpPath = `${filePath}.tmp`;
+    this.extraTables = extraTables;
     this.data = null;
     this._ensureLoaded();
   }
@@ -69,7 +72,7 @@ export class JsonStore {
     }
 
     if (!fs.existsSync(this.filePath)) {
-      this.data = EMPTY_STORE();
+      this.data = EMPTY_STORE(this.extraTables);
       this._flush();
       return;
     }
@@ -79,7 +82,7 @@ export class JsonStore {
       const parsed = JSON.parse(raw);
       // Fill missing keys from EMPTY_STORE so adding a new "table" in a
       // later schema doesn't crash a fresh deploy reading an old file.
-      this.data = { ...EMPTY_STORE(), ...parsed };
+      this.data = { ...EMPTY_STORE(this.extraTables), ...parsed };
       // Ensure each well-known array key is actually an array — defends
       // against a hand-edited file that set one to null or an object.
       const empty = EMPTY_STORE();
@@ -96,7 +99,7 @@ export class JsonStore {
       const backup = `${this.filePath}.corrupt-${Date.now()}`;
       console.error(`[JsonStore] Failed to read ${this.filePath}: ${err.message}. Backing up to ${backup}.`);
       try { fs.renameSync(this.filePath, backup); } catch { /* noop */ }
-      this.data = EMPTY_STORE();
+      this.data = EMPTY_STORE(this.extraTables);
       this._flush();
     }
   }

package/server/index.js

@@ -71,6 +71,19 @@ 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,
+  CodexA2AAdapter,
+  CursorA2AAdapter,
+  GeminiA2AAdapter,
+  OpenCodeA2AAdapter,
+  QwenA2AAdapter,
+  createPreviewProxyRouter,
+  createOrchestrationTaskRouter,
+  createWorkflowRouter,
+} 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 +389,18 @@ 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());
+adapterRegistry.register(new CodexA2AAdapter());
+adapterRegistry.register(new CursorA2AAdapter());
+adapterRegistry.register(new GeminiA2AAdapter());
+adapterRegistry.register(new QwenA2AAdapter());
+adapterRegistry.register(new OpenCodeA2AAdapter());
+app.use('/a2a', createA2ARouter());
+app.use('/preview', authenticateToken, createPreviewProxyRouter());
+app.use('/api/orchestration', authenticateToken, createOrchestrationTaskRouter());
+app.use('/api/orchestration', authenticateToken, createWorkflowRouter());
+
 // Network discovery / QR endpoints (protected)
 app.use('/api/network', authenticateToken, networkRoutes);
 
@@ -2822,6 +2847,7 @@ const SERVER_PORT = process.env.SERVER_PORT || 3001;
 const HOST = process.env.HOST || '0.0.0.0';
 const DISPLAY_HOST = getConnectableHost(HOST);
 const VITE_PORT = process.env.VITE_PORT || 5173;
+const SEPARATE_FRONTEND = process.env.PIXCODE_SEPARATE_FRONTEND === '1';
 
 async function isPortOpen(port, timeoutMs = 800) {
     return await new Promise((resolve) => {
@@ -2873,7 +2899,17 @@ function printSystemDaemonActiveNotice(port) {
     console.log(`${c.info('[INFO]')} Logs: ${c.bright(logsCommand)}`);
 }
 
-function printUserDaemonActiveNotice(port, frontendPort) {
+function daemonFrontendArgs() {
+    return SEPARATE_FRONTEND
+        ? ['--frontend-port', String(VITE_PORT)]
+        : ['--single-port'];
+}
+
+function daemonInstallArgs(mode) {
+    return ['install', '--mode', mode, '--port', String(SERVER_PORT), ...daemonFrontendArgs()];
+}
+
+function printUserDaemonActiveNotice(port, frontendPort, frontendEnabled = SEPARATE_FRONTEND) {
     const effectivePort = Number(port) || 3001;
     const effectiveFrontendPort = Number(frontendPort) || 5173;
     const statusCommand = buildDaemonCliCommand(
@@ -2889,8 +2925,10 @@ function printUserDaemonActiveNotice(port, frontendPort) {
         DAEMON_COMMAND_CONTEXT
     );
     console.log(`${c.ok('[OK]')} User daemon is active for this account.`);
-    console.log(`${c.info('[INFO]')} Backend: ${c.bright(`http://localhost:${effectivePort}`)}`);
-    console.log(`${c.info('[INFO]')} Frontend: ${c.bright(`http://localhost:${effectiveFrontendPort}`)}`);
+    console.log(`${c.info('[INFO]')} App URL: ${c.bright(`http://localhost:${effectivePort}`)}`);
+    if (frontendEnabled) {
+        console.log(`${c.info('[INFO]')} Frontend: ${c.bright(`http://localhost:${effectiveFrontendPort}`)}`);
+    }
     console.log(`${c.info('[INFO]')} Status: ${c.bright(statusCommand)}`);
     console.log(`${c.info('[INFO]')} Stop: ${c.bright(stopCommand)}`);
     console.log(`${c.info('[INFO]')} Logs: ${c.bright(logsCommand)}`);
@@ -2910,8 +2948,8 @@ async function maybeAutoDaemonBootstrapFromIndex() {
 
     process.env.PIXCODE_DAEMON_ATTEMPTED = '1';
 
-    const systemArgs = ['install', '--mode=system', '--port', String(SERVER_PORT), '--frontend-port', String(VITE_PORT)];
-    const userArgs = ['install', '--mode=user', '--port', String(SERVER_PORT), '--frontend-port', String(VITE_PORT)];
+    const systemArgs = daemonInstallArgs('system');
+    const userArgs = daemonInstallArgs('user');
 
     try {
         console.log(`${c.info('[INFO]')} Linux detected. Enforcing system daemon mode for Pixcode...`);
@@ -2935,7 +2973,7 @@ async function maybeAutoDaemonBootstrapFromIndex() {
                 {
                     subcommand: 'install',
                     mode: 'system',
-                    extraArgs: ['--port', String(SERVER_PORT), '--frontend-port', String(VITE_PORT)],
+                    extraArgs: ['--port', String(SERVER_PORT), ...daemonFrontendArgs()],
                 },
                 DAEMON_COMMAND_CONTEXT
             );
@@ -2969,7 +3007,7 @@ async function maybeAutoDaemonBootstrapFromIndex() {
                 {
                     subcommand: 'install',
                     mode: 'system',
-                    extraArgs: ['--port', String(SERVER_PORT), '--frontend-port', String(VITE_PORT)],
+                    extraArgs: ['--port', String(SERVER_PORT), ...daemonFrontendArgs()],
                 },
                 DAEMON_COMMAND_CONTEXT
             );
@@ -2977,7 +3015,7 @@ async function maybeAutoDaemonBootstrapFromIndex() {
                 {
                     subcommand: 'install',
                     mode: 'user',
-                    extraArgs: ['--port', String(SERVER_PORT), '--frontend-port', String(VITE_PORT)],
+                    extraArgs: ['--port', String(SERVER_PORT), ...daemonFrontendArgs()],
                 },
                 DAEMON_COMMAND_CONTEXT
             );
@@ -3045,7 +3083,9 @@ async function startServer() {
             console.log(`${c.info('[INFO]')} To run in production mode, go to http://${DISPLAY_HOST}:${SERVER_PORT}`);            
         }
 
-        console.log(`${c.info('[INFO]')} To run in development mode with hot-module replacement, go to http://${DISPLAY_HOST}:${VITE_PORT}`);
+        if (SEPARATE_FRONTEND) {
+            console.log(`${c.info('[INFO]')} To run in development mode with hot-module replacement, go to http://${DISPLAY_HOST}:${VITE_PORT}`);
+        }
    
         server.listen(SERVER_PORT, HOST, async () => {
             const appInstallPath = APP_ROOT;

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

@@ -0,0 +1,108 @@
+// 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 (deterministic fallback
+//                          until smarter 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';
+
+interface ResolveAdapterOptions {
+  preferredAdapterId?: string;
+  preferredProvider?: string;
+  preferredSkillId?: string;
+}
+
+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(id: string): AbstractA2AAdapter | undefined {
+    return this.byId.get(id);
+  }
+
+  resolve(idOrSelector: string, options: ResolveAdapterOptions = {}): AbstractA2AAdapter | undefined {
+    const normalizedSelector = idOrSelector.trim();
+    if (!normalizedSelector) {
+      return undefined;
+    }
+
+    if (normalizedSelector === 'auto') {
+      return this.pickPreferred(this.list(), options);
+    }
+
+    if (normalizedSelector.startsWith('skill:')) {
+      const skill = normalizedSelector.slice('skill:'.length);
+      const matches = this.list().filter((adapter) =>
+        adapter.agentCard.skills.some((s) => s.id === skill),
+      );
+      if (matches.length === 0) {
+        return undefined;
+      }
+      return this.pickPreferred(matches, {
+        ...options,
+        preferredSkillId: options.preferredSkillId ?? skill,
+      });
+    }
+
+    return this.byId.get(normalizedSelector);
+  }
+
+  list(): AbstractA2AAdapter[] {
+    return [...this.byId.values()];
+  }
+
+  agentCards(): AgentCard[] {
+    return this.list().map((a) => a.agentCard);
+  }
+
+  private pickPreferred(
+    adapters: AbstractA2AAdapter[],
+    options: ResolveAdapterOptions,
+  ): AbstractA2AAdapter | undefined {
+    const {
+      preferredAdapterId,
+      preferredProvider,
+      preferredSkillId,
+    } = options;
+
+    if (preferredAdapterId) {
+      const byAdapterId = adapters.find((adapter) => adapter.id === preferredAdapterId);
+      if (byAdapterId) {
+        return byAdapterId;
+      }
+    }
+
+    if (preferredProvider) {
+      const normalizedProvider = preferredProvider.trim().toLowerCase();
+      const byProvider = adapters.find((adapter) => adapter.id === normalizedProvider);
+      if (byProvider) {
+        return byProvider;
+      }
+    }
+
+    if (preferredSkillId) {
+      const bySkill = adapters.find((adapter) =>
+        adapter.agentCard.skills.some((skill) => skill.id === preferredSkillId),
+      );
+      if (bySkill) {
+        return bySkill;
+      }
+    }
+
+    return adapters[0];
+  }
+}
+
+export const adapterRegistry = new AdapterRegistry();
+export type { AdapterRegistry, ResolveAdapterOptions };

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

@@ -0,0 +1,55 @@
+// 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';
+import type { WorkspaceHandle } from '@/modules/orchestration/workspace/types.js';
+
+export interface AdapterContext {
+  /** Isolated execution workspace for the task. */
+  workspace: WorkspaceHandle;
+  /** Compatibility alias while legacy adapters still accept cwd directly. */
+  cwd: string;
+  /** pixcode permission mode passed through to the underlying CLI. */
+  permissionMode?: string;
+  /** Provider model selected by the user in Pixcode. */
+  model?: string;
+  /** Provider-specific tool / permission settings from Pixcode Settings. */
+  toolsSettings?: Record<string, unknown>;
+  /** 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,284 @@
+// 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',
+            toolsSettings: ctx.toolsSettings,
+          },
+          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> }],
+        });
+    }
+  }
+}