@pixelbyte-software/pixcode 1.42.5 → 1.43.0

package/scripts/smoke/v143-remote-control.mjs

@@ -0,0 +1,76 @@
+#!/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 telegram = read('server/services/telegram/control-center.js');
+assert.match(telegram, /\/approvals/, 'Telegram control should expose an approvals command.');
+assert.match(telegram, /showApprovalQueue/, 'Telegram menu should render pending approval decisions.');
+assert.match(telegram, /approval_decide/, 'Telegram callbacks should allow approval decisions.');
+assert.match(telegram, /showControlRoom/, 'Telegram menu should expose the multi-project control room.');
+assert.match(telegram, /showWebhookMenu/, 'Telegram menu should expose webhook status.');
+
+const workflowRoutes = read('server/modules/orchestration/workflows/workflow.routes.ts');
+assert.match(workflowRoutes, /\/workflows\/approvals/, 'Orchestration should expose a global approval queue.');
+assert.match(workflowRoutes, /resolvePermissionApproval/, 'Global approval route should resolve permission approvals.');
+assert.match(workflowRoutes, /dispatchWebhookEvent/, 'Workflow routes should dispatch webhook events for remote automation.');
+
+const approvalQueue = read('server/modules/orchestration/workflows/approval-queue.ts');
+assert.match(approvalQueue, /listPendingApprovals/, 'Approval queue should list pending approvals across runs.');
+assert.match(approvalQueue, /resolvePermissionApproval/, 'Approval queue should resolve approval requests centrally.');
+assert.match(approvalQueue, /source: 'ui' \| 'telegram' \| 'api'/, 'Approval queue should preserve the decision source.');
+
+const webhooks = read('server/services/webhooks.js');
+assert.match(webhooks, /PIXCODE_WEBHOOK_EVENT_TYPES/, 'Webhook service should declare supported event taxonomy.');
+assert.match(webhooks, /run\.completed/, 'Webhook taxonomy should include run.completed.');
+assert.match(webhooks, /approval\.needed/, 'Webhook taxonomy should include approval.needed.');
+assert.match(webhooks, /deliverWebhookEvent/, 'Webhook service should deliver signed outbound events.');
+
+const webhookRoutes = read('server/routes/webhooks.js');
+assert.match(webhookRoutes, /router\.get\('\/'/, 'Webhook routes should list configured webhooks.');
+assert.match(webhookRoutes, /router\.post\('\/test'/, 'Webhook routes should support test delivery.');
+
+const remote = read('server/routes/remote.js');
+assert.match(remote, /\/control-room/, 'Remote API should expose the control room snapshot.');
+assert.match(remote, /\/console-layout/, 'Remote API should expose mobile console layout metadata.');
+
+const controlRoom = read('server/services/control-room.js');
+assert.match(controlRoom, /buildControlRoomSnapshot/, 'Control room should build a multi-project snapshot.');
+assert.match(controlRoom, /maxProjects = 4/, 'Control room should cap the live overview at four projects.');
+assert.match(controlRoom, /mobileFirst/, 'Control room should include mobile-first console metadata.');
+
+const publicApi = read('server/routes/public-api.js');
+assert.match(publicApi, /\/sdk\/typescript/, 'Public API should expose a TypeScript SDK starter.');
+assert.match(publicApi, /\/cookbook/, 'Public API should expose a curl cookbook.');
+
+const manifest = read('server/services/public-api-manifest.js');
+assert.match(manifest, /buildTypeScriptSdkStarter/, 'Public API manifest should generate typed TypeScript SDK examples.');
+assert.match(manifest, /webhooks/, 'Public API manifest should document webhook endpoints.');
+
+const appTypes = read('src/types/app.ts');
+assert.match(appTypes, /'remote'/, 'Frontend tabs should include the remote console.');
+
+const mainContent = read('src/components/main-content/view/MainContent.tsx');
+assert.match(mainContent, /RemoteConsole/, 'Main content should render the remote console tab.');
+
+const tabSwitcher = read('src/components/main-content/view/subcomponents/MainContentTabSwitcher.tsx');
+assert.match(tabSwitcher, /tabs\.remote/, 'Tab switcher should expose the remote console tab.');
+
+const remoteConsole = read('src/components/remote-console/RemoteConsole.tsx');
+assert.match(remoteConsole, /control-room/, 'Remote console should load control-room snapshots.');
+assert.match(remoteConsole, /approval queue/i, 'Remote console should show the approval queue.');
+assert.match(remoteConsole, /webhook/i, 'Remote console should show webhook health.');
+
+const docs = read('docs/self-hosted-agent-control-room.md');
+assert.match(docs, /Remote Control/, 'Docs should explain remote control workflows.');
+assert.match(docs, /Webhook/, 'Docs should explain webhook automation.');
+assert.match(docs, /Telegram/, 'Docs should explain Telegram control.');
+
+console.log('v1.43 remote control smoke passed');

package/server/index.js

@@ -78,6 +78,7 @@ import messagesRoutes from './routes/messages.js';
 import diagnosticsRoutes from './routes/diagnostics.js';
 import remoteRoutes from './routes/remote.js';
 import publicApiRoutes from './routes/public-api.js';
+import webhooksRoutes from './routes/webhooks.js';
 import liveViewRoutes, { createLiveViewPublicRouter } from './routes/live-view.js';
 import providerRoutes from './modules/providers/provider.routes.js';
 import {
@@ -406,6 +407,9 @@ app.use('/api/remote', authenticateToken, remoteRoutes);
 // Public automation manifest (protected so private host details only go to signed-in clients)
 app.use('/api/public', authenticateToken, publicApiRoutes);
 
+// Outbound webhook automation (protected)
+app.use('/api/webhooks', authenticateToken, webhooksRoutes);
+
 // Project Live View (protected control API + public share proxy)
 app.use('/api/live-view', authenticateToken, liveViewRoutes);
 

package/server/modules/orchestration/index.ts

@@ -31,6 +31,10 @@ export {
 export { createOrchestrationTaskRouter } from './tasks/orchestration-task.routes.js';
 export { orchestrationTaskService } from './tasks/orchestration-task.service.js';
 export { createWorkflowRouter } from './workflows/workflow.routes.js';
+export {
+  listPendingApprovals,
+  resolvePermissionApproval,
+} from './workflows/approval-queue.js';
 export {
   PIXCODE_WORKFLOW_TEMPLATE_PROTOCOL,
   applyWorkflowTemplateToMetadata,

package/server/modules/orchestration/workflows/approval-queue.ts

@@ -0,0 +1,106 @@
+import type { WorkflowRun } from '@/modules/orchestration/workflows/workflow.types.js';
+import { workflowStore } from '@/modules/orchestration/workflows/workflow-store.js';
+
+export type ApprovalDecisionSource = 'ui' | 'telegram' | 'api';
+
+export type ApprovalQueueItem = Record<string, unknown> & {
+  id: string;
+  runId: string;
+  workflowId: string;
+  status: string;
+  requestedAt?: number;
+};
+
+function readRunApprovals(run: WorkflowRun): Array<Record<string, unknown>> {
+  const approvals = run.metadata?.pendingPermissionApprovals;
+  return Array.isArray(approvals)
+    ? approvals.filter((approval): approval is Record<string, unknown> => Boolean(approval && typeof approval === 'object'))
+    : [];
+}
+
+function normalizeApproval(run: WorkflowRun, approval: Record<string, unknown>): ApprovalQueueItem | null {
+  const id = typeof approval.id === 'string' && approval.id.trim() ? approval.id : null;
+  if (!id) return null;
+
+  return {
+    ...approval,
+    id,
+    runId: run.id,
+    workflowId: run.workflowId,
+    status: typeof approval.status === 'string' ? approval.status : 'pending',
+    requestedAt: typeof approval.requestedAt === 'number' ? approval.requestedAt : run.startedAt,
+  };
+}
+
+export function listPendingApprovals(options: {
+  projectId?: string;
+  includeResolved?: boolean;
+} = {}): ApprovalQueueItem[] {
+  const items: ApprovalQueueItem[] = [];
+  for (const run of workflowStore.listRuns()) {
+    if (options.projectId && run.metadata?.projectId !== options.projectId) continue;
+    for (const approval of readRunApprovals(run)) {
+      const item = normalizeApproval(run, approval);
+      if (!item) continue;
+      if (!options.includeResolved && item.status !== 'pending') continue;
+      items.push(item);
+    }
+  }
+
+  return items.sort((a, b) => Number(b.requestedAt ?? 0) - Number(a.requestedAt ?? 0));
+}
+
+export function resolvePermissionApproval({
+  approvalId,
+  allow,
+  source = 'api',
+  resolvedBy,
+  message,
+}: {
+  approvalId: string;
+  allow: boolean;
+  source?: ApprovalDecisionSource; // source: 'ui' | 'telegram' | 'api'
+  resolvedBy?: string | number | null;
+  message?: string;
+}): {
+  runId: string;
+  pendingApprovals: ApprovalQueueItem[];
+  approvalHistory: ApprovalQueueItem[];
+} | null {
+  for (const run of workflowStore.listRuns()) {
+    const approvals = readRunApprovals(run);
+    let changed = false;
+    const nextApprovals = approvals.map((approval) => {
+      if (approval.id !== approvalId) return approval;
+      changed = true;
+      return {
+        ...approval,
+        status: allow ? 'allowed' : 'denied',
+        resolvedAt: Date.now(),
+        resolvedBy: resolvedBy ?? null,
+        decisionSource: source,
+        resolutionMessage: typeof message === 'string' && message.trim() ? message.trim() : undefined,
+      };
+    });
+
+    if (!changed) continue;
+
+    run.metadata = {
+      ...run.metadata,
+      pendingPermissionApprovals: nextApprovals,
+    };
+    workflowStore.setRun(run);
+
+    const queueItems = nextApprovals
+      .map((approval) => normalizeApproval(run, approval))
+      .filter((approval): approval is ApprovalQueueItem => Boolean(approval));
+
+    return {
+      runId: run.id,
+      pendingApprovals: queueItems.filter((approval) => approval.status === 'pending'),
+      approvalHistory: queueItems.filter((approval) => approval.status !== 'pending'),
+    };
+  }
+
+  return null;
+}

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

@@ -49,6 +49,8 @@ import {
   notifyRunStopped,
   notifyUserIfEnabled,
 } from '@/services/notification-orchestrator.js';
+// @ts-ignore — plain-JS service
+import { dispatchWebhookEvent } from '@/services/webhooks.js';
 
 const TERMINAL = new Set(['completed', 'failed', 'canceled']);
 const SKIPPED = 'skipped';
@@ -1655,6 +1657,20 @@ class WorkflowRunner {
       workflowStore.setRun(run);
       orchestrationTaskService.updateFromWorkflowRun(run);
       notifyWorkflowRunFinished(run);
+      const webhookRunStatus = String(run.status);
+      dispatchWebhookEvent({
+        type: webhookRunStatus === 'completed'
+          ? 'run.completed'
+          : webhookRunStatus === 'canceled'
+            ? 'run.canceled'
+            : 'run.failed',
+        payload: {
+          runId: run.id,
+          workflowId: run.workflowId,
+          status: webhookRunStatus,
+          error: readString(run.metadata?.error),
+        },
+      });
       this.cancelingRuns.delete(run.id);
     }
   }
@@ -1687,6 +1703,15 @@ class WorkflowRunner {
 
     if (decision.approvalRequest) {
       notifyPermissionApprovalRequested(run, decision);
+      dispatchWebhookEvent({
+        type: 'approval.needed',
+        payload: {
+          runId: run.id,
+          workflowId: run.workflowId,
+          approvalId: decision.approvalRequest.id,
+          capabilities: decision.capabilities,
+        },
+      });
     }
   }
 

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

@@ -14,6 +14,11 @@ import {
 import { workflowStore } from '@/modules/orchestration/workflows/workflow-store.js';
 import { buildWorkflowTrace } from '@/modules/orchestration/workflows/workflow-trace.js';
 import { findPixcodeAppRoot } from '@/modules/orchestration/workflows/workspace-target.js';
+import {
+  listPendingApprovals,
+  resolvePermissionApproval,
+  type ApprovalDecisionSource,
+} from '@/modules/orchestration/workflows/approval-queue.js';
 import {
   DEFAULT_PERMISSION_POLICY,
   PERMISSION_CAPABILITIES,
@@ -22,6 +27,7 @@ import {
   evaluatePermissionRequest,
   normalizePermissionPolicy,
 } from '@/modules/orchestration/security/permission-policy.js';
+import { dispatchWebhookEvent } from '@/services/webhooks.js';
 
 const TERMINAL_RUN_STATES = new Set(['completed', 'failed', 'canceled']);
 
@@ -254,6 +260,55 @@ export function createWorkflowRouter(): Router {
     });
   });
 
+  router.get('/workflows/approvals', (req, res) => {
+    res.json({
+      pendingApprovals: listPendingApprovals({
+        projectId: readOptionalString(req.query.projectId),
+        includeResolved: readBooleanFlag(req.query.includeResolved),
+      }),
+    });
+  });
+
+  router.post('/workflows/approvals/:approvalId', (req, res) => {
+    const allow = req.body?.allow === true;
+    const deny = req.body?.allow === false;
+    if (!allow && !deny) {
+      res.status(400).json({
+        error: {
+          code: 'PERMISSION_DECISION_REQUIRED',
+          message: 'Approval queue decisions require allow=true or allow=false.',
+        },
+      });
+      return;
+    }
+
+    const source = ['ui', 'telegram', 'api'].includes(req.body?.source)
+      ? req.body.source as ApprovalDecisionSource
+      : 'api';
+    const result = resolvePermissionApproval({
+      approvalId: req.params.approvalId,
+      allow,
+      source,
+      resolvedBy: readRequestUserId(req),
+      message: readOptionalString(req.body?.message),
+    });
+    if (!result) {
+      res.status(404).json({ error: { code: 'APPROVAL_NOT_FOUND', message: req.params.approvalId } });
+      return;
+    }
+
+    dispatchWebhookEvent({
+      type: 'approval.resolved',
+      payload: {
+        approvalId: req.params.approvalId,
+        allow,
+        source,
+        runId: result.runId,
+      },
+    });
+    res.json(result);
+  });
+
   router.post('/workflows/runs/:runId/permission-approvals/:requestId', (req, res) => {
     const run = workflowStore.getRun(req.params.runId);
     if (!run) {
@@ -285,6 +340,15 @@ export function createWorkflowRouter(): Router {
     }
 
     workflowStore.setRun(run);
+    dispatchWebhookEvent({
+      type: 'approval.resolved',
+      payload: {
+        approvalId: req.params.requestId,
+        allow,
+        source: 'ui',
+        runId: run.id,
+      },
+    });
     res.json({
       runId: run.id,
       pendingApprovals: readRunArray(run, 'pendingPermissionApprovals')
@@ -359,6 +423,14 @@ export function createWorkflowRouter(): Router {
           },
         },
       );
+      dispatchWebhookEvent({
+        type: 'run.started',
+        payload: {
+          runId: replayRun.id,
+          workflowId: replayRun.workflowId,
+          replayOf: run.id,
+        },
+      });
       res.status(202).json({
         run: replayRun,
         replayPlan,
@@ -424,6 +496,13 @@ export function createWorkflowRouter(): Router {
       res.status(404).json({ error: { code: 'RUN_NOT_FOUND', message: req.params.runId } });
       return;
     }
+    dispatchWebhookEvent({
+      type: 'run.canceled',
+      payload: {
+        runId: run.id,
+        workflowId: run.workflowId,
+      },
+    });
     res.json(run);
   });
 
@@ -443,6 +522,14 @@ export function createWorkflowRouter(): Router {
           workflowName: workflow.name,
         },
       );
+      dispatchWebhookEvent({
+        type: 'run.started',
+        payload: {
+          runId: run.id,
+          workflowId: run.workflowId,
+          workflowName: workflow.name,
+        },
+      });
       res.status(202).json(run);
     } catch (error) {
       res.status(400).json({
@@ -476,6 +563,14 @@ export function createWorkflowRouter(): Router {
           workflowName: workflow.name,
         },
       );
+      dispatchWebhookEvent({
+        type: 'run.started',
+        payload: {
+          runId: run.id,
+          workflowId: run.workflowId,
+          templateId: template.id,
+        },
+      });
       res.status(202).json(run);
     } catch (error) {
       res.status(400).json({

package/server/routes/public-api.js

@@ -1,6 +1,11 @@
 import express from 'express';
 
-import { buildOpenApiFragment, buildPublicApiManifest } from '../services/public-api-manifest.js';
+import {
+  buildCurlCookbook,
+  buildOpenApiFragment,
+  buildPublicApiManifest,
+  buildTypeScriptSdkStarter,
+} from '../services/public-api-manifest.js';
 
 const router = express.Router();
 
@@ -18,4 +23,12 @@ router.get('/openapi', (req, res) => {
   res.json(buildOpenApiFragment({ baseUrl: requestBaseUrl(req) }));
 });
 
+router.get('/sdk/typescript', (req, res) => {
+  res.type('text/typescript').send(buildTypeScriptSdkStarter({ baseUrl: requestBaseUrl(req) }));
+});
+
+router.get('/cookbook', (req, res) => {
+  res.json(buildCurlCookbook({ baseUrl: requestBaseUrl(req) }));
+});
+
 export default router;

package/server/routes/remote.js

@@ -5,6 +5,10 @@ import {
   getPublicRemoteConnectionConfig,
   saveRemoteConnectionConfig,
 } from '../services/remote-connection.js';
+import {
+  buildControlRoomSnapshot,
+  buildMobileConsoleLayout,
+} from '../services/control-room.js';
 
 const router = express.Router();
 
@@ -30,4 +34,22 @@ router.post('/check', async (req, res) => {
   }
 });
 
+router.get('/control-room', async (_req, res) => {
+  try {
+    res.json({
+      success: true,
+      controlRoom: await buildControlRoomSnapshot(),
+    });
+  } catch (error) {
+    res.status(500).json({ success: false, error: error.message });
+  }
+});
+
+router.get('/console-layout', (_req, res) => {
+  res.json({
+    success: true,
+    layout: buildMobileConsoleLayout(),
+  });
+});
+
 export default router;

package/server/routes/webhooks.js

@@ -0,0 +1,63 @@
+import express from 'express';
+
+import {
+  PIXCODE_WEBHOOK_EVENT_TYPES,
+  deleteWebhook,
+  deliverWebhookEvent,
+  listWebhooks,
+  upsertWebhook,
+} from '../services/webhooks.js';
+
+const router = express.Router();
+
+router.get('/', (_req, res) => {
+  res.json({
+    success: true,
+    eventTypes: PIXCODE_WEBHOOK_EVENT_TYPES,
+    webhooks: listWebhooks(),
+  });
+});
+
+router.post('/', (req, res) => {
+  try {
+    const webhook = upsertWebhook(req.body || {});
+    res.status(201).json({ success: true, webhook });
+  } catch (error) {
+    res.status(400).json({ success: false, error: error.message });
+  }
+});
+
+router.patch('/:id', (req, res) => {
+  try {
+    const webhook = upsertWebhook({ ...(req.body || {}), id: req.params.id });
+    res.json({ success: true, webhook });
+  } catch (error) {
+    res.status(400).json({ success: false, error: error.message });
+  }
+});
+
+router.delete('/:id', (req, res) => {
+  if (!deleteWebhook(req.params.id)) {
+    res.status(404).json({ success: false, error: 'Webhook not found.' });
+    return;
+  }
+  res.json({ success: true });
+});
+
+router.post('/test', async (req, res) => {
+  try {
+    const result = await deliverWebhookEvent({
+      type: req.body?.type || 'run.completed',
+      payload: {
+        test: true,
+        message: 'Pixcode webhook test delivery',
+        sentBy: req.user?.id ?? null,
+      },
+    });
+    res.json({ success: true, result });
+  } catch (error) {
+    res.status(500).json({ success: false, error: error.message });
+  }
+});
+
+export default router;

package/server/services/control-room.js

@@ -0,0 +1,102 @@
+import { listPendingApprovals, workflowStore } from '../modules/orchestration/index.js';
+import { getProjects } from '../projects.js';
+
+import { listWebhooks } from './webhooks.js';
+
+const TERMINAL_RUN_STATES = new Set(['completed', 'failed', 'canceled']);
+
+function projectPath(project) {
+  return project.fullPath || project.path || '';
+}
+
+function runBelongsToProject(run, project) {
+  const projectId = run.metadata?.projectId;
+  const path = run.metadata?.projectPath;
+  return projectId === project.name || path === projectPath(project);
+}
+
+function countSessions(project) {
+  return [
+    project.sessions,
+    project.codexSessions,
+    project.cursorSessions,
+    project.geminiSessions,
+    project.qwenSessions,
+    project.opencodeSessions,
+  ].reduce((total, sessions) => total + (Array.isArray(sessions) ? sessions.length : 0), 0);
+}
+
+function summarizeProject(project, runs, approvals) {
+  const projectRuns = runs.filter((run) => runBelongsToProject(run, project));
+  const runningRuns = projectRuns.filter((run) => !TERMINAL_RUN_STATES.has(run.status));
+  const failedRuns = projectRuns.filter((run) => run.status === 'failed');
+  const projectApprovals = approvals.filter((approval) => (
+    approval.runId && projectRuns.some((run) => run.id === approval.runId)
+  ));
+
+  return {
+    id: project.name,
+    name: project.displayName || project.name,
+    path: projectPath(project),
+    sessionCount: countSessions(project),
+    activeRunCount: runningRuns.length,
+    failedRunCount: failedRuns.length,
+    pendingApprovalCount: projectApprovals.length,
+    latestRuns: projectRuns.slice(0, 4).map((run) => ({
+      id: run.id,
+      workflowId: run.workflowId,
+      status: run.status,
+      startedAt: run.startedAt,
+      finishedAt: run.finishedAt,
+    })),
+  };
+}
+
+export async function buildControlRoomSnapshot({ maxProjects = 4 } = {}) {
+  const projects = await getProjects();
+  const runs = workflowStore.listRuns();
+  const pendingApprovals = listPendingApprovals();
+  const webhooks = listWebhooks();
+  const projectCards = projects
+    .map((project) => summarizeProject(project, runs, pendingApprovals))
+    .sort((a, b) => (
+      b.pendingApprovalCount - a.pendingApprovalCount ||
+      b.activeRunCount - a.activeRunCount ||
+      b.failedRunCount - a.failedRunCount ||
+      a.name.localeCompare(b.name)
+    ))
+    .slice(0, maxProjects);
+
+  return {
+    protocol: 'pixcode.control-room.v1',
+    generatedAt: new Date().toISOString(),
+    maxProjects,
+    mobileFirst: true,
+    totals: {
+      projects: projects.length,
+      activeRuns: runs.filter((run) => !TERMINAL_RUN_STATES.has(run.status)).length,
+      failedRuns: runs.filter((run) => run.status === 'failed').length,
+      pendingApprovals: pendingApprovals.length,
+      webhooks: webhooks.length,
+      enabledWebhooks: webhooks.filter((webhook) => webhook.enabled).length,
+    },
+    projects: projectCards,
+    approvals: pendingApprovals.slice(0, 20),
+    webhooks,
+  };
+}
+
+export function buildMobileConsoleLayout() {
+  return {
+    protocol: 'pixcode.remote-console-layout.v1',
+    mobileFirst: true,
+    sections: [
+      { id: 'projects', title: 'Projects', priority: 1 },
+      { id: 'approvals', title: 'Approval queue', priority: 2 },
+      { id: 'runs', title: 'Runs', priority: 3 },
+      { id: 'webhooks', title: 'Webhooks', priority: 4 },
+      { id: 'api', title: 'API SDK', priority: 5 },
+    ],
+    maxVisibleProjects: 4,
+  };
+}