@pixelbyte-software/pixcode 1.41.5 → 1.42.1

package/server/modules/orchestration/workflows/context-packet.ts

@@ -0,0 +1,186 @@
+import type { ResolvedWorkspaceTarget } from '@/modules/orchestration/workflows/workspace-target.js';
+
+export const PIXCODE_CONTEXT_PROTOCOL = 'pixcode.context.v1' as const;
+export const MAX_CONTEXT_PACKET_TEXT_CHARS = 16_000;
+
+export interface WorkflowContextPacket {
+  protocol: typeof PIXCODE_CONTEXT_PROTOCOL;
+  originalUserRequest: string;
+  project: {
+    kind: string;
+    label: string;
+    selectedProjectName?: string;
+  };
+  task: {
+    workflowId: string;
+    workflowRunId: string;
+    nodeId: string;
+    stage?: string;
+    assignment?: string;
+    stepInstructions: string;
+  };
+  constraints: {
+    adapterId?: string;
+    agentLabel?: string;
+    model?: string;
+    permissionMode?: string;
+    isolation?: string;
+    toolsSettings?: Record<string, unknown>;
+  };
+  upstreamArtifacts: Array<{
+    type: 'upstream-context';
+    text: string;
+    sourceNodeIds: string[];
+  }>;
+  runState: {
+    status: string;
+    startedAt: number;
+    nodeCount: number;
+    completedNodeIds: string[];
+    runningNodeIds: string[];
+  };
+  compaction: {
+    maxChars: number;
+    originalChars: number;
+    compactedChars: number;
+    omittedChars: number;
+    wasCompacted: boolean;
+  };
+  createdAt: string;
+}
+
+type ContextPacketRun = {
+  id: string;
+  workflowId: string;
+  status: string;
+  input?: string;
+  startedAt: number;
+  nodeRuns: Array<{
+    nodeId: string;
+    status: string;
+  }>;
+};
+
+type ContextPacketNode = {
+  id: string;
+  adapterId?: string;
+  agentLabel?: string;
+  assignment?: string;
+  prompt: string;
+  stage?: string;
+  model?: string;
+  permissionMode?: string;
+  toolsSettings?: Record<string, unknown>;
+  isolation?: string;
+};
+
+export type BuildWorkflowContextPacketInput = {
+  run: ContextPacketRun;
+  node: ContextPacketNode;
+  workspaceTarget: ResolvedWorkspaceTarget;
+  inputContext: string;
+  inputNodeIds: string[];
+};
+
+function compactContextText(text: string): {
+  text: string;
+  originalChars: number;
+  compactedChars: number;
+  omittedChars: number;
+  wasCompacted: boolean;
+} {
+  const originalChars = text.length;
+  if (originalChars <= MAX_CONTEXT_PACKET_TEXT_CHARS) {
+    return {
+      text,
+      originalChars,
+      compactedChars: originalChars,
+      omittedChars: 0,
+      wasCompacted: false,
+    };
+  }
+
+  const edge = Math.floor(MAX_CONTEXT_PACKET_TEXT_CHARS / 2);
+  const omittedChars = originalChars - MAX_CONTEXT_PACKET_TEXT_CHARS;
+  const compacted = [
+    text.slice(0, edge),
+    `\n\n[...${omittedChars} characters omitted from upstream context packet...]\n\n`,
+    text.slice(-edge),
+  ].join('');
+
+  return {
+    text: compacted,
+    originalChars,
+    compactedChars: compacted.length,
+    omittedChars,
+    wasCompacted: true,
+  };
+}
+
+export function buildWorkflowContextPacket({
+  run,
+  node,
+  workspaceTarget,
+  inputContext,
+  inputNodeIds,
+}: BuildWorkflowContextPacketInput): WorkflowContextPacket {
+  const compacted = compactContextText(inputContext);
+  return {
+    protocol: PIXCODE_CONTEXT_PROTOCOL,
+    originalUserRequest: run.input?.trim() || '(No original user request was provided.)',
+    project: {
+      kind: workspaceTarget.kind,
+      label: workspaceTarget.label,
+      selectedProjectName: workspaceTarget.selectedProjectName,
+    },
+    task: {
+      workflowId: run.workflowId,
+      workflowRunId: run.id,
+      nodeId: node.id,
+      stage: node.stage,
+      assignment: node.assignment,
+      stepInstructions: node.prompt,
+    },
+    constraints: {
+      adapterId: node.adapterId,
+      agentLabel: node.agentLabel,
+      model: node.model,
+      permissionMode: node.permissionMode,
+      isolation: node.isolation,
+      toolsSettings: node.toolsSettings,
+    },
+    upstreamArtifacts: compacted.text
+      ? [{
+        type: 'upstream-context',
+        text: compacted.text,
+        sourceNodeIds: inputNodeIds,
+      }]
+      : [],
+    runState: {
+      status: run.status,
+      startedAt: run.startedAt,
+      nodeCount: run.nodeRuns.length,
+      completedNodeIds: run.nodeRuns
+        .filter((nodeRun) => nodeRun.status === 'completed')
+        .map((nodeRun) => nodeRun.nodeId),
+      runningNodeIds: run.nodeRuns
+        .filter((nodeRun) => nodeRun.status === 'running')
+        .map((nodeRun) => nodeRun.nodeId),
+    },
+    compaction: {
+      maxChars: MAX_CONTEXT_PACKET_TEXT_CHARS,
+      originalChars: compacted.originalChars,
+      compactedChars: compacted.compactedChars,
+      omittedChars: compacted.omittedChars,
+      wasCompacted: compacted.wasCompacted,
+    },
+    createdAt: new Date().toISOString(),
+  };
+}
+
+export function formatContextPacketForPrompt(packet: WorkflowContextPacket): string {
+  return [
+    `Pixcode standardized init context packet (${PIXCODE_CONTEXT_PROTOCOL}):`,
+    JSON.stringify(packet, null, 2),
+  ].join('\n');
+}

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,16 @@ 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 {
+  buildWorkflowContextPacket,
+  formatContextPacketForPrompt,
+} from '@/modules/orchestration/workflows/context-packet.js';
 import {
   type ResolvedWorkspaceTarget,
   resolveWorkflowWorkspace,
@@ -28,6 +38,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 +428,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 +445,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 +459,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 +486,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 +506,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 (
@@ -1534,9 +1565,19 @@ class WorkflowRunner {
 
     const inputContext = node.inputs.map((input) => outputs.get(input)).filter(Boolean).join('\n\n');
     const workspaceTarget = resolveWorkflowWorkspace(run.metadata);
+    const contextPacket = buildWorkflowContextPacket({
+      run,
+      node,
+      workspaceTarget,
+      inputContext,
+      inputNodeIds: node.inputs,
+    });
+    nodeRun.contextPacket = contextPacket;
+    workflowStore.setRun(run);
     const prompt = [
       'Original user request (primary task; answer this directly even if the workspace is empty):',
       run.input?.trim() || '(No original user request was provided.)',
+      formatContextPacketForPrompt(contextPacket),
       inputContext
         ? `Upstream workflow context from prior agents:\n${inputContext}`
         : '',
@@ -1688,7 +1729,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';
 }
 
@@ -174,6 +176,28 @@ export function buildWorkflowTrace(run: WorkflowRun): WorkflowTraceEvent[] {
       });
     }
 
+    if (node.contextPacket) {
+      pushEvent(events, {
+        id: traceId([run.id, node.nodeId, 'context-packet']),
+        type: 'message',
+        severity: node.contextPacket.compaction.wasCompacted ? 'warning' : 'info',
+        status: node.status,
+        timestamp: timestamp + 1.5,
+        ...base,
+        title: 'Context packet prepared',
+        titleKey: 'workflow.trace.contextPacket',
+        summary: node.contextPacket.compaction.wasCompacted
+          ? `Context compacted by ${node.contextPacket.compaction.omittedChars} characters`
+          : 'Context packet prepared without compaction',
+        metadata: {
+          protocol: node.contextPacket.protocol,
+          compaction: node.contextPacket.compaction,
+          upstreamArtifactCount: node.contextPacket.upstreamArtifacts.length,
+          sourceNodeIds: node.contextPacket.upstreamArtifacts.flatMap((artifact) => artifact.sourceNodeIds),
+        },
+      });
+    }
+
     if (node.adapterId || node.model) {
       pushEvent(events, {
         id: traceId([run.id, node.nodeId, 'provider']),

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

@@ -1,3 +1,6 @@
+import type { WorkflowContextPacket } from '@/modules/orchestration/workflows/context-packet.js';
+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 +50,8 @@ export interface WorkflowNodeRun {
   finishedAt?: number;
   error?: string;
   outputText?: string;
+  contextPacket?: WorkflowContextPacket;
+  handoffArtifact?: WorkflowHandoffArtifact;
   messages?: Array<{
     role: string;
     text: string;