@pixelbyte-software/pixcode 1.41.4 → 1.42.0

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;

package/server/routes/live-view.js

@@ -31,6 +31,29 @@ function buildUrls(req, session) {
   };
 }
 
+function buildEnvironmentTunnel(tunnel, urls) {
+  const active = Boolean(tunnel?.running && urls?.external);
+  return {
+    status: active ? 'active' : 'local-only',
+    url: active ? urls.external : null,
+    localUrl: urls?.local || null,
+    preferredUrl: urls?.preferred || urls?.local || null,
+  };
+}
+
+function attachEnvironmentRuntimeState(environment, urls, tunnel) {
+  if (!environment) return environment;
+  return {
+    ...environment,
+    urls,
+    tunnel: buildEnvironmentTunnel(tunnel, urls),
+    diagnostics: {
+      ...environment.diagnostics,
+      publicTunnelReady: Boolean(tunnel?.running && urls?.external),
+    },
+  };
+}
+
 function escapeHtml(value) {
   return String(value ?? '')
     .replaceAll('&', '&')
@@ -202,10 +225,13 @@ router.get('/:projectName/status', async (req, res) => {
     const { projectName } = req.params;
     const projectPath = await resolveProjectPath(projectName);
     const state = await getLiveViewState(projectName, projectPath);
+    const urls = buildUrls(req, state.session);
+    const tunnel = getTunnelState();
     res.json({
       ...state,
-      urls: buildUrls(req, state.session),
-      tunnel: getTunnelState(),
+      urls,
+      tunnel,
+      environment: attachEnvironmentRuntimeState(state.environment, urls, tunnel),
     });
   } catch (error) {
     res.status(error.statusCode || 500).json({ error: error.message || 'Failed to read Live View state' });
@@ -217,11 +243,15 @@ router.post('/:projectName/start', async (req, res) => {
     const { projectName } = req.params;
     const projectPath = await resolveProjectPath(projectName);
     const session = await startLiveView(projectName, projectPath, req.body || {});
+    const state = await getLiveViewState(projectName, projectPath);
+    const urls = buildUrls(req, session);
+    const tunnel = getTunnelState();
     res.json({
       success: true,
       session,
-      urls: buildUrls(req, session),
-      tunnel: getTunnelState(),
+      urls,
+      tunnel,
+      environment: attachEnvironmentRuntimeState(state.environment, urls, tunnel),
     });
   } catch (error) {
     const status = error.code === 'LIVE_VIEW_NOT_AVAILABLE' ? 422 : 500;
@@ -234,11 +264,15 @@ router.post('/:projectName/restart', async (req, res) => {
     const { projectName } = req.params;
     const projectPath = await resolveProjectPath(projectName);
     const session = await restartLiveView(projectName, projectPath, req.body || {});
+    const state = await getLiveViewState(projectName, projectPath);
+    const urls = buildUrls(req, session);
+    const tunnel = getTunnelState();
     res.json({
       success: true,
       session,
-      urls: buildUrls(req, session),
-      tunnel: getTunnelState(),
+      urls,
+      tunnel,
+      environment: attachEnvironmentRuntimeState(state.environment, urls, tunnel),
     });
   } catch (error) {
     res.status(500).json({ error: error.message || 'Failed to restart Live View' });
@@ -248,11 +282,14 @@ router.post('/:projectName/restart', async (req, res) => {
 router.post('/:projectName/stop', async (req, res) => {
   try {
     const session = await stopLiveView(req.params.projectName);
+    const urls = buildUrls(req, session);
+    const tunnel = getTunnelState();
     res.json({
       success: true,
       session,
-      urls: buildUrls(req, session),
-      tunnel: getTunnelState(),
+      urls,
+      tunnel,
+      environment: attachEnvironmentRuntimeState(null, urls, tunnel),
     });
   } catch (error) {
     res.status(500).json({ error: error.message || 'Failed to stop Live View' });

package/server/services/live-view.js

@@ -294,6 +294,91 @@ function buildManagedPhpCommand(runtimeStatus) {
   };
 }
 
+function publicCommand(command) {
+  if (!command) return null;
+  return {
+    id: command.id,
+    label: command.label,
+    displayCommand: command.displayCommand,
+    custom: command.custom === true || command.id === 'custom',
+  };
+}
+
+function liveViewEnvironmentMode(target, session) {
+  const kind = session?.kind || target?.kind || 'none';
+  if (kind === 'static') return 'static';
+  if (kind === 'process') return 'local-process';
+  return 'unavailable';
+}
+
+function liveViewEnvironmentStatus(target, session) {
+  if (session?.status) return session.status;
+  if (target?.available) return 'ready';
+  return 'unavailable';
+}
+
+function liveViewEnvironmentCommand(target, session) {
+  return publicCommand(session?.command) || publicCommand(target?.command);
+}
+
+function liveViewEnvironmentLogs(session) {
+  return Array.isArray(session?.log) ? session.log.slice(-40) : [];
+}
+
+function liveViewEnvironmentRuntime(target, session) {
+  return session?.runtime || target?.runtime || null;
+}
+
+function liveViewEnvironmentManagedRuntime(target, session) {
+  return session?.managedRuntime || target?.managedRuntime || target?.command?.managedRuntime || null;
+}
+
+export function buildLiveViewEnvironment({ target = null, session = null } = {}) {
+  const mode = liveViewEnvironmentMode(target, session);
+  const status = liveViewEnvironmentStatus(target, session);
+  const command = liveViewEnvironmentCommand(target, session);
+  const framework = session?.framework || target?.framework || null;
+  const label = session?.label || target?.label || framework || 'Live View';
+  const runtime = liveViewEnvironmentRuntime(target, session);
+  const managedRuntime = liveViewEnvironmentManagedRuntime(target, session);
+  const logs = liveViewEnvironmentLogs(session);
+  const reason = session?.error || target?.reason || null;
+
+  return {
+    id: mode === 'unavailable' ? 'live-view-unavailable' : `live-view-${mode}`,
+    mode,
+    status,
+    framework,
+    label,
+    command,
+    runtime,
+    managedRuntime,
+    port: session?.port ?? null,
+    upstreamUrl: session?.upstreamUrl ?? null,
+    sharePath: session?.sharePath ?? null,
+    logs,
+    diagnostics: {
+      runnerKind: session?.kind || target?.kind || 'none',
+      targetAvailable: Boolean(target?.available || session),
+      reason,
+      error: session?.error || null,
+      exitCode: session?.exitCode ?? null,
+      exitSignal: session?.exitSignal ?? null,
+      spawnErrorCode: session?.spawnErrorCode ?? null,
+      startedAt: session?.startedAt || null,
+      stoppedAt: session?.stoppedAt || null,
+      readyTimeoutMs: READY_TIMEOUT_MS,
+      staticServing: mode === 'static',
+      customCommand: command?.custom === true,
+      publicTunnelReady: false,
+    },
+    tunnel: {
+      status: 'local-only',
+      url: null,
+    },
+  };
+}
+
 function detectPackageCommand(packageJson, packageManager) {
   const scripts = packageJson.scripts || {};
   const devScript = String(scripts.dev || '');
@@ -648,11 +733,7 @@ function publicSession(session) {
     kind: session.kind,
     framework: session.framework,
     label: session.label,
-    command: session.command ? {
-      id: session.command.id,
-      label: session.command.label,
-      displayCommand: session.command.displayCommand,
-    } : null,
+    command: publicCommand(session.command),
     runtime: session.runtime || null,
     managedRuntime: session.managedRuntime || null,
     port: session.port,
@@ -670,9 +751,11 @@ function publicSession(session) {
 export async function getLiveViewState(projectName, projectPath) {
   const target = await detectLiveViewTarget(projectPath);
   const session = sessionsByProject.get(projectName) ?? null;
+  const publicLiveViewSession = publicSession(session);
   return {
     target,
-    session: publicSession(session),
+    session: publicLiveViewSession,
+    environment: buildLiveViewEnvironment({ target, session: publicLiveViewSession }),
   };
 }
 
@@ -697,6 +780,7 @@ export async function startLiveView(projectName, projectPath, options = {}) {
         command: customCommand,
         args: [],
         displayCommand: customCommand,
+        custom: true,
         shell: true,
       },
     }