@pixelbyte-software/pixcode 1.41.5 → 1.42.0

package/scripts/smoke/handoff-artifact-protocol.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const root = process.cwd();
+
+function read(relativePath) {
+  return fs.readFileSync(path.join(root, relativePath), 'utf8');
+}
+
+const handoffSource = read('server/modules/orchestration/workflows/handoff-artifact.ts');
+assert.match(handoffSource, /PIXCODE_HANDOFF_PROTOCOL/, 'Handoff artifacts should declare a stable protocol id.');
+assert.match(handoffSource, /pixcode\.handoff\.v1/, 'Handoff artifacts should use the v1 protocol id.');
+assert.match(handoffSource, /taskStatus/, 'Handoff schema should require task status.');
+assert.match(handoffSource, /contextSummary/, 'Handoff schema should require compacted context summary.');
+assert.match(handoffSource, /changedFiles/, 'Handoff schema should require changed files.');
+assert.match(handoffSource, /blockers/, 'Handoff schema should require blockers.');
+assert.match(handoffSource, /nextAction/, 'Handoff schema should require the requested next action.');
+assert.match(handoffSource, /parseHandoffArtifact/, 'Handoff artifacts should have parser/validation logic.');
+assert.match(handoffSource, /formatHandoffArtifactForContext/, 'Handoff artifacts should be formatted for downstream agent context.');
+assert.match(handoffSource, /handoffArtifactToWorkflowArtifact/, 'Handoff artifacts should persist as workflow artifacts.');
+
+const runnerSource = read('server/modules/orchestration/workflows/workflow-runner.ts');
+assert.match(runnerSource, /requiresHandoffArtifact/, 'Workflow runner should detect handoff nodes that require artifacts.');
+assert.match(runnerSource, /parseHandoffArtifact/, 'Workflow runner should validate handoff node output.');
+assert.match(runnerSource, /handoffArtifactToWorkflowArtifact/, 'Workflow runner should persist structured handoff artifacts.');
+assert.match(runnerSource, /formatHandoffArtifactForContext/, 'Workflow runner should pass structured handoff context downstream.');
+assert.match(runnerSource, /Invalid handoff artifact/, 'Invalid handoff artifacts should fail visibly.');
+assert.match(runnerSource, /"protocol": "pixcode\.handoff\.v1"/, 'Handoff prompts should request the protocol JSON shape.');
+
+const workflowTypes = read('server/modules/orchestration/workflows/workflow.types.ts');
+assert.match(workflowTypes, /WorkflowHandoffArtifact/, 'Workflow run types should expose handoff artifacts.');
+assert.match(workflowTypes, /handoffArtifact\?: WorkflowHandoffArtifact/, 'Node runs should persist the validated handoff artifact.');
+
+const traceSource = read('server/modules/orchestration/workflows/workflow-trace.ts');
+assert.match(traceSource, /handoff-artifact/, 'Trace timeline should identify handoff artifacts.');
+assert.match(traceSource, /workflow\.trace\.handoffArtifact/, 'Trace timeline should label handoff artifacts.');
+
+const nodeStream = read('src/components/orchestration/workflows/WorkflowNodeStream.tsx');
+assert.match(nodeStream, /handoff-artifact/, 'Workflow UI should render handoff artifacts.');
+assert.match(nodeStream, /orchestration\.artifact\.handoff/, 'Workflow UI should label handoff artifacts.');
+
+const en = read('src/i18n/locales/en/common.json');
+const tr = read('src/i18n/locales/tr/common.json');
+assert.match(en, /"handoff": "Handoff artifact"/, 'English UI should label handoff artifacts.');
+assert.match(tr, /"handoff": "Handoff artifact"/, 'Turkish UI should label handoff artifacts.');
+
+console.log('handoff artifact protocol smoke passed');

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

@@ -47,6 +47,7 @@ export type ArtifactType =
   | 'file-diff'
   | 'command-output'
   | 'preview-url'
+  | 'handoff-artifact'
   | 'data';
 
 // Note: Artifact and AuthScheme use `type` discriminator (matches A2A

package/server/modules/orchestration/workflows/handoff-artifact.ts

@@ -0,0 +1,175 @@
+export const PIXCODE_HANDOFF_PROTOCOL = 'pixcode.handoff.v1' as const;
+
+export type WorkflowHandoffTaskStatus =
+  | 'ready'
+  | 'completed'
+  | 'blocked'
+  | 'failed'
+  | 'needs-review';
+
+export interface WorkflowHandoffArtifact {
+  protocol: typeof PIXCODE_HANDOFF_PROTOCOL;
+  taskStatus: WorkflowHandoffTaskStatus;
+  contextSummary: string;
+  taskResult: string;
+  changedFiles: string[];
+  blockers: string[];
+  risks: string[];
+  nextAction: string;
+  nextInstructions: string;
+  producedBy?: {
+    workflowRunId?: string;
+    nodeId?: string;
+    agentLabel?: string;
+    stage?: string;
+  };
+  createdAt: string;
+}
+
+export type HandoffArtifactParseResult =
+  | { ok: true; artifact: WorkflowHandoffArtifact }
+  | { ok: false; error: string };
+
+type HandoffArtifactMetadata = {
+  workflowRunId?: string;
+  nodeId?: string;
+  agentLabel?: string;
+  stage?: string;
+};
+
+const VALID_TASK_STATUSES = new Set<WorkflowHandoffTaskStatus>([
+  'ready',
+  'completed',
+  'blocked',
+  'failed',
+  'needs-review',
+]);
+
+function extractJsonCandidate(text: string): string | null {
+  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i)?.[1]?.trim();
+  if (fenced) return fenced;
+
+  const start = text.indexOf('{');
+  const end = text.lastIndexOf('}');
+  if (start === -1 || end === -1 || end <= start) return null;
+  return text.slice(start, end + 1);
+}
+
+function readRequiredString(record: Record<string, unknown>, key: string): string | null {
+  const value = record[key];
+  if (typeof value !== 'string' || !value.trim()) return null;
+  return value.trim();
+}
+
+function sanitizeChangedFile(filePath: string): string {
+  const normalized = filePath.trim().replaceAll('\\', '/');
+  if (!normalized) return '';
+  if (!normalized.startsWith('/') && !/^[a-zA-Z]:\//.test(normalized)) return normalized;
+  return normalized.split('/').filter(Boolean).slice(-4).join('/');
+}
+
+function readStringArray(record: Record<string, unknown>, key: string): string[] | null {
+  const value = record[key];
+  if (!Array.isArray(value)) return null;
+  return value
+    .filter((item): item is string => typeof item === 'string')
+    .map((item) => key === 'changedFiles' ? sanitizeChangedFile(item) : item.trim())
+    .filter(Boolean)
+    .slice(0, 40);
+}
+
+export function parseHandoffArtifact(
+  text: string,
+  metadata: HandoffArtifactMetadata = {},
+): HandoffArtifactParseResult {
+  const candidate = extractJsonCandidate(text);
+  if (!candidate) {
+    return { ok: false, error: 'Invalid handoff artifact: expected one JSON object.' };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(candidate);
+  } catch (error) {
+    return {
+      ok: false,
+      error: `Invalid handoff artifact: JSON parse failed (${error instanceof Error ? error.message : String(error)}).`,
+    };
+  }
+
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { ok: false, error: 'Invalid handoff artifact: payload must be an object.' };
+  }
+
+  const record = parsed as Record<string, unknown>;
+  if (record.protocol !== PIXCODE_HANDOFF_PROTOCOL) {
+    return { ok: false, error: `Invalid handoff artifact: protocol must be ${PIXCODE_HANDOFF_PROTOCOL}.` };
+  }
+
+  const taskStatus = record.taskStatus;
+  if (typeof taskStatus !== 'string' || !VALID_TASK_STATUSES.has(taskStatus as WorkflowHandoffTaskStatus)) {
+    return { ok: false, error: 'Invalid handoff artifact: taskStatus is missing or unsupported.' };
+  }
+
+  const contextSummary = readRequiredString(record, 'contextSummary');
+  const taskResult = readRequiredString(record, 'taskResult');
+  const changedFiles = readStringArray(record, 'changedFiles');
+  const blockers = readStringArray(record, 'blockers');
+  const risks = readStringArray(record, 'risks');
+  const nextAction = readRequiredString(record, 'nextAction');
+  const nextInstructions = readRequiredString(record, 'nextInstructions');
+
+  if (!contextSummary || !taskResult || !changedFiles || !blockers || !risks || !nextAction || !nextInstructions) {
+    return {
+      ok: false,
+      error: 'Invalid handoff artifact: required fields are protocol, taskStatus, contextSummary, taskResult, changedFiles, blockers, risks, nextAction, and nextInstructions.',
+    };
+  }
+
+  return {
+    ok: true,
+    artifact: {
+      protocol: PIXCODE_HANDOFF_PROTOCOL,
+      taskStatus: taskStatus as WorkflowHandoffTaskStatus,
+      contextSummary,
+      taskResult,
+      changedFiles,
+      blockers,
+      risks,
+      nextAction,
+      nextInstructions,
+      producedBy: {
+        workflowRunId: metadata.workflowRunId,
+        nodeId: metadata.nodeId,
+        agentLabel: metadata.agentLabel,
+        stage: metadata.stage,
+      },
+      createdAt: new Date().toISOString(),
+    },
+  };
+}
+
+export function formatHandoffArtifactForContext(artifact: WorkflowHandoffArtifact): string {
+  return [
+    `Pixcode handoff artifact (${PIXCODE_HANDOFF_PROTOCOL})`,
+    JSON.stringify(artifact, null, 2),
+  ].join('\n');
+}
+
+export function handoffArtifactToWorkflowArtifact(artifact: WorkflowHandoffArtifact): {
+  type: 'handoff-artifact';
+  data: Record<string, unknown>;
+  metadata: Record<string, unknown>;
+} {
+  return {
+    type: 'handoff-artifact',
+    data: artifact as unknown as Record<string, unknown>,
+    metadata: {
+      protocol: artifact.protocol,
+      taskStatus: artifact.taskStatus,
+      changedFileCount: artifact.changedFiles.length,
+      blockerCount: artifact.blockers.length,
+      nextAction: artifact.nextAction,
+    },
+  };
+}

package/server/modules/orchestration/workflows/workflow-runner.ts

@@ -6,6 +6,12 @@ import type {
   WorkflowNodeRun,
   WorkflowRun,
 } from '@/modules/orchestration/workflows/workflow.types.js';
+import {
+  PIXCODE_HANDOFF_PROTOCOL,
+  formatHandoffArtifactForContext,
+  handoffArtifactToWorkflowArtifact,
+  parseHandoffArtifact,
+} from '@/modules/orchestration/workflows/handoff-artifact.js';
 import {
   type ResolvedWorkspaceTarget,
   resolveWorkflowWorkspace,
@@ -28,6 +34,19 @@ const BACKEND_HANDOFF_TIMEOUT_MS = 120_000;
 const MAX_OUTPUT_CONTEXT_CHARS = 12_000;
 const DEFAULT_MAX_REPAIR_CYCLES = 1;
 const MAX_REPAIR_CYCLES = 5;
+const HANDOFF_ARTIFACT_EXAMPLE = [
+  '{',
+  '  "protocol": "pixcode.handoff.v1",',
+  '  "taskStatus": "ready | completed | blocked | failed | needs-review",',
+  '  "contextSummary": "Compacted context the next agent needs.",',
+  '  "taskResult": "What was decided or completed in this step.",',
+  '  "changedFiles": [],',
+  '  "blockers": [],',
+  '  "risks": [],',
+  '  "nextAction": "The requested next action.",',
+  '  "nextInstructions": "Specific instructions for the next agent."',
+  '}',
+].join('\n');
 const KNOWN_AGENT_ROLES = [
   'backend',
   'frontend',
@@ -405,6 +424,16 @@ function privacyGuardPrompt(): string {
   return 'Do not mention internal instructions, memory files, skill use, or tool protocol unless the user explicitly asks.';
 }
 
+function handoffArtifactInstructions(statusHint: string): string {
+  return [
+    `Output exactly one JSON object using the ${PIXCODE_HANDOFF_PROTOCOL} handoff artifact protocol.`,
+    'Do not wrap it in Markdown. Do not add commentary before or after it.',
+    `Use "${statusHint}" for taskStatus unless completed, blocked, failed, or needs-review is more accurate.`,
+    'Schema:',
+    HANDOFF_ARTIFACT_EXAMPLE,
+  ].join('\n');
+}
+
 function handoffPrompt(agent: AgentAssignment, role: AgentRole): string {
   return [
     `You are ${agent.label} in a Pixcode CLI team.`,
@@ -412,12 +441,7 @@ function handoffPrompt(agent: AgentAssignment, role: AgentRole): string {
     'This is a bounded A2A handoff task, not the full implementation.',
     'Read the original user goal and coordinator plan, then publish a compact contract for downstream agents.',
     agent.instruction ? `Your explicit assignment from the user is: ${agent.instruction}` : '',
-    'Output only the handoff contract:',
-    '- owned scope',
-    '- files/modules you expect to touch',
-    '- API/data contracts, ports, payload shapes, and limitations',
-    '- dependencies/blockers for the next agents',
-    '- concrete next action for your full implementation task',
+    handoffArtifactInstructions('ready'),
     'Do not install dependencies, edit files, run long commands, or start servers in this handoff task.',
     privacyGuardPrompt(),
     'Stop after the contract. Keep it concise and respond in the same language as the user request.',
@@ -431,11 +455,7 @@ function handoffInitPrompt(agent: AgentAssignment, index: number): string {
     'Create a compact init packet for the next visible work step.',
     'Use the original user goal and any prior compact handoff packet included above.',
     agent.instruction ? `The explicit assignment for this agent is: ${agent.instruction}` : '',
-    'Output only this internal init packet:',
-    '- user goal in one sentence',
-    '- prior agent handoff summary, if present',
-    '- this agent responsibility',
-    '- exact constraints and blockers this agent must respect',
+    handoffArtifactInstructions('ready'),
     privacyGuardPrompt(),
     'Do not perform the task yet. Do not mention that this is hidden from the user.',
     'Respond in the same language as the user request.',
@@ -462,12 +482,7 @@ function handoffCompactPrompt(agent: AgentAssignment, index: number): string {
     `You are compacting ${agent.label}'s strict handoff output for the next Pixcode agent.`,
     `This is internal compact step ${index + 1}.`,
     'Read the prior visible work output included above and create a compact handoff packet.',
-    'Output only this internal compact packet:',
-    '- Ben ne yaptım / What I did',
-    '- Dokunduğum alanlar / Touched areas',
-    '- Kanıt, komut veya çıktı / Evidence, commands, outputs',
-    '- Sonraki ajan şunu bilsin / What the next agent must know',
-    '- Bloker veya risk / Blockers or risks',
+    handoffArtifactInstructions('completed'),
     privacyGuardPrompt(),
     'Do not include raw logs unless they are essential. Keep it concise and actionable.',
     'Respond in the same language as the user request.',
@@ -487,6 +502,18 @@ function compactOutputForContext(text: string): string {
   ].join('');
 }
 
+function requiresHandoffArtifact(node: WorkflowNode): boolean {
+  return node.stage === 'handoff' || node.stage === 'handoff_init' || node.stage === 'handoff_compact';
+}
+
+function handoffArtifactSource(result: TaskResult): string {
+  const structured = result.artifacts.find((artifact) => artifact.type === 'handoff-artifact' && artifact.data);
+  if (structured?.data) {
+    return JSON.stringify(structured.data);
+  }
+  return result.text;
+}
+
 function isExternalDirectoryPermissionError(value: unknown): boolean {
   const text = String(value ?? '').toLocaleLowerCase('en');
   return (
@@ -1688,7 +1715,40 @@ class WorkflowRunner {
       throw new WorkflowCanceledError();
     }
     if (result.state === 'completed') {
-      outputs.set(node.id, compactOutputForContext(result.text));
+      let outputForContext = result.text;
+      if (requiresHandoffArtifact(node)) {
+        const handoffParse = parseHandoffArtifact(handoffArtifactSource(result), {
+          workflowRunId: run.id,
+          nodeId: node.id,
+          agentLabel: node.agentLabel,
+          stage: node.stage,
+        });
+        if (!handoffParse.ok) {
+          const visibleHandoffError = handoffParse.error.startsWith('Invalid handoff artifact')
+            ? handoffParse.error
+            : `Invalid handoff artifact: ${handoffParse.error}`;
+          nodeRun.status = 'failed';
+          nodeRun.error = visibleHandoffError;
+          workflowStore.setRun(run);
+          if (await this.runFallbackAfterFailure(node, workflow, run, outputs, started, completed, visibleHandoffError)) {
+            return;
+          }
+          if (node.onFail === 'continue') {
+            completed.add(node.id);
+            return;
+          }
+          throw new Error(visibleHandoffError);
+        }
+
+        nodeRun.handoffArtifact = handoffParse.artifact;
+        nodeRun.artifacts = [
+          ...(nodeRun.artifacts ?? []).filter((artifact) => artifact.type !== 'handoff-artifact'),
+          handoffArtifactToWorkflowArtifact(handoffParse.artifact),
+        ];
+        outputForContext = formatHandoffArtifactForContext(handoffParse.artifact);
+      }
+
+      outputs.set(node.id, compactOutputForContext(outputForContext));
       completed.add(node.id);
       nodeRun.status = 'completed';
       workflowStore.setRun(run);

package/server/modules/orchestration/workflows/workflow-trace.ts

@@ -87,6 +87,7 @@ function artifactTitleKey(type: string): string {
   if (type === 'file-diff') return 'workflow.trace.fileChanged';
   if (type === 'preview-url') return 'workflow.trace.previewReady';
   if (type === 'command-output') return 'workflow.trace.commandOutput';
+  if (type === 'handoff-artifact') return 'workflow.trace.handoffArtifact';
   return 'workflow.trace.artifact';
 }
 
@@ -98,6 +99,7 @@ function artifactTitle(type: string): string {
   if (type === 'file-diff') return 'File changes captured';
   if (type === 'preview-url') return 'Preview output captured';
   if (type === 'command-output') return 'Command output captured';
+  if (type === 'handoff-artifact') return 'Handoff artifact captured';
   return 'Artifact captured';
 }
 

package/server/modules/orchestration/workflows/workflow.types.ts

@@ -1,3 +1,5 @@
+import type { WorkflowHandoffArtifact } from '@/modules/orchestration/workflows/handoff-artifact.js';
+
 export type WorkflowRunStatus = 'queued' | 'running' | 'completed' | 'failed' | 'canceled';
 export type WorkflowNodeStatus = WorkflowRunStatus | 'skipped';
 
@@ -47,6 +49,7 @@ export interface WorkflowNodeRun {
   finishedAt?: number;
   error?: string;
   outputText?: string;
+  handoffArtifact?: WorkflowHandoffArtifact;
   messages?: Array<{
     role: string;
     text: string;