feat(backend): scaffold PodMan agent pipeline + token server

Express server with /health and a LiveKit token endpoint. Module skeletons
for the full loop: vision (Gemini), GitHub fusion, collision detector (pure,
testable), intervention engine, and continual-learning memory store. Approve
native build scripts (esbuild/genai/protobufjs) at the workspace root.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

backend/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@podman/backend",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@google/genai": "^2.10.0",
+    "@podman/shared": "workspace:*",
+    "cors": "^2.8.6",
+    "dotenv": "^17.4.2",
+    "express": "^5.2.1",
+    "livekit-server-sdk": "^2.15.5",
+    "octokit": "^5.0.5"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "tsx": "^4.22.4"
+  }
+}

backend/src/collision/detector.ts

@@ -0,0 +1,50 @@
+import type { Collision, EngineerContext, GithubStateSnapshot } from '@podman/shared';
+
+/**
+ * Fuse live engineer contexts (from vision) with GitHub state to find overlaps:
+ * two or more engineers editing the same file — especially when unpushed.
+ *
+ * Pure function: easy to unit-test, no I/O. Callers supply the GitHub snapshot.
+ */
+export function detectCollisions(
+  contexts: EngineerContext[],
+  githubStateByFile: Record<string, GithubStateSnapshot> = {},
+  now: string = new Date().toISOString(),
+): Collision[] {
+  const byFile = new Map<string, EngineerContext[]>();
+  for (const ctx of contexts) {
+    if (!ctx.currentFile) continue;
+    const list = byFile.get(ctx.currentFile) ?? [];
+    list.push(ctx);
+    byFile.set(ctx.currentFile, list);
+  }
+
+  const collisions: Collision[] = [];
+  for (const [file, group] of byFile) {
+    if (group.length < 2) continue;
+
+    const engineers = [...new Set(group.map((g) => g.engineerId))];
+    if (engineers.length < 2) continue;
+
+    const github = githubStateByFile[file];
+    const unpushed = group.some((g) => g.hasUnpushedChanges) || github?.unpushed === true;
+    const sharedSymbol = group.every(
+      (g) => g.currentSymbol && g.currentSymbol === group[0]!.currentSymbol,
+    )
+      ? group[0]!.currentSymbol
+      : undefined;
+
+    collisions.push({
+      id: `${group[0]!.podId}:${file}:${engineers.sort().join(',')}`,
+      podId: group[0]!.podId,
+      file,
+      symbol: sharedSymbol,
+      engineers,
+      severity: unpushed ? 'critical' : sharedSymbol ? 'warn' : 'info',
+      githubState: github,
+      detectedAt: now,
+    });
+  }
+
+  return collisions;
+}

backend/src/env.ts

@@ -0,0 +1,39 @@
+import 'dotenv/config';
+
+/** Reads an env var, throwing if it is required but missing. */
+function read(name: string, required = false): string {
+  const value = process.env[name] ?? '';
+  if (required && !value) {
+    throw new Error(`Missing required env var: ${name}`);
+  }
+  return value;
+}
+
+export const env = {
+  port: Number(process.env.PORT ?? 8787),
+
+  livekit: {
+    url: read('LIVEKIT_URL'),
+    apiKey: read('LIVEKIT_API_KEY'),
+    apiSecret: read('LIVEKIT_API_SECRET'),
+  },
+
+  gemini: {
+    apiKey: read('GEMINI_API_KEY'),
+    visionModel: process.env.GEMINI_VISION_MODEL ?? 'gemini-3.5-flash',
+    liveModel: process.env.GEMINI_LIVE_MODEL ?? '',
+  },
+
+  github: {
+    token: read('GITHUB_TOKEN'),
+    repo: read('GITHUB_REPO'),
+  },
+
+  mongo: {
+    uri: read('MONGODB_URI'),
+  },
+
+  voyage: {
+    apiKey: read('VOYAGE_API_KEY'),
+  },
+} as const;

backend/src/github/client.ts

@@ -0,0 +1,25 @@
+import { Octokit } from 'octokit';
+import type { GithubStateSnapshot } from '@podman/shared';
+import { env } from '../env.js';
+
+export const octokit: Octokit = new Octokit({ auth: env.github.token });
+
+/**
+ * Pull the GitHub state relevant to a file in the pod's repo: open branches
+ * and PRs touching it. Fused with vision contexts by the collision detector.
+ *
+ * TODO(github): list branches/PRs, diff files, map commits -> engineer logins.
+ */
+export async function getStateForFile(_file: string): Promise<GithubStateSnapshot> {
+  return { branches: {}, openPrs: [], unpushed: false };
+}
+
+/** Open a draft "sync PR" between two engineers' branches — the suggested action. */
+export async function openSyncPr(_params: {
+  base: string;
+  head: string;
+  title: string;
+}): Promise<{ number: number; url: string } | null> {
+  // TODO(github): octokit.rest.pulls.create({ ...env.github.repo, draft: true })
+  return null;
+}

backend/src/index.ts

@@ -0,0 +1,35 @@
+import express from 'express';
+import cors from 'cors';
+import { env } from './env.js';
+import { createPodToken } from './livekit/token.js';
+
+const app = express();
+app.use(cors());
+app.use(express.json());
+
+app.get('/health', (_req, res) => {
+  res.json({ ok: true, service: 'podman-backend' });
+});
+
+/**
+ * Mint a LiveKit token for an engineer to join a pod room.
+ * POST /pods/:podId/token  { identity, name }
+ */
+app.post('/pods/:podId/token', async (req, res) => {
+  const { podId } = req.params;
+  const { identity, name } = req.body ?? {};
+  if (!identity) {
+    res.status(400).json({ error: 'identity is required' });
+    return;
+  }
+  try {
+    const token = await createPodToken(podId, identity, name);
+    res.json({ token, url: env.livekit.url });
+  } catch (err) {
+    res.status(500).json({ error: (err as Error).message });
+  }
+});
+
+app.listen(env.port, () => {
+  console.log(`[podman] backend listening on http://localhost:${env.port}`);
+});

backend/src/intervention/engine.ts

@@ -0,0 +1,27 @@
+import type { Collision, Intervention } from '@podman/shared';
+
+/**
+ * Compose PodMan's intervention for a collision — the message it speaks and the
+ * action it offers (e.g. "open a sync PR"). Severity drives voice vs card.
+ *
+ * TODO(brain): use Gemini to phrase the message naturally from the team model;
+ * tune thresholds from outcomes (the continual-learning policy).
+ */
+export function composeIntervention(
+  collision: Collision,
+  now: string = new Date().toISOString(),
+): Intervention {
+  const kind = collision.severity === 'critical' ? 'voice' : 'card';
+  return {
+    id: `intervention:${collision.id}`,
+    collisionId: collision.id,
+    podId: collision.podId,
+    kind,
+    message: `Heads up — ${collision.engineers.join(' and ')} are both in ${collision.file}.`,
+    suggestedAction: {
+      kind: collision.severity === 'critical' ? 'open_sync_pr' : 'ping_teammate',
+    },
+    status: 'pending',
+    createdAt: now,
+  };
+}

backend/src/livekit/token.ts

@@ -0,0 +1,25 @@
+import { AccessToken } from 'livekit-server-sdk';
+import { env } from '../env.js';
+
+/**
+ * Mint a LiveKit access token so an engineer's browser can join a pod room
+ * and publish screen + mic + cam tracks.
+ */
+export async function createPodToken(
+  podId: string,
+  identity: string,
+  name?: string,
+): Promise<string> {
+  const at = new AccessToken(env.livekit.apiKey, env.livekit.apiSecret, {
+    identity,
+    name,
+  });
+  at.addGrant({
+    room: podId,
+    roomJoin: true,
+    canPublish: true,
+    canSubscribe: true,
+    canPublishData: true,
+  });
+  return at.toJwt();
+}

backend/src/memory/store.ts

@@ -0,0 +1,27 @@
+import type { EngineerContext, Intervention } from '@podman/shared';
+
+/**
+ * Continual-learning memory: persist observations + intervention outcomes to
+ * MongoDB Atlas and embed file/feature notes into Voyage vectors so later
+ * sessions are sharper ("more useful the more you use it").
+ *
+ * TODO(memory): connect Atlas, store observations, record outcomes, embed via
+ * Voyage, and expose retrieval for the PodMan brain.
+ */
+export interface PodMemory {
+  recordObservation(ctx: EngineerContext): Promise<void>;
+  recordOutcome(intervention: Intervention, accepted: boolean): Promise<void>;
+}
+
+/** In-memory stub so the rest of the pipeline can run before Atlas is wired. */
+export function createInMemoryStore(): PodMemory {
+  const observations: EngineerContext[] = [];
+  return {
+    async recordObservation(ctx) {
+      observations.push(ctx);
+    },
+    async recordOutcome() {
+      /* no-op until Atlas is wired */
+    },
+  };
+}

backend/src/vision/gemini.ts

@@ -0,0 +1,20 @@
+import type { EngineerContext } from '@podman/shared';
+
+/**
+ * Turn a sampled screen frame into a structured EngineerContext using Gemini
+ * vision. This is the headline capability: it produces the pre-push signal
+ * (which file/symbol an engineer is editing) that GitHub cannot see.
+ *
+ * TODO(vision): wire @google/genai, downscale frames, sample ~1fps/on-change.
+ */
+export async function frameToContext(
+  _frame: Uint8Array,
+  meta: { engineerId: string; podId: string },
+): Promise<EngineerContext> {
+  return {
+    engineerId: meta.engineerId,
+    podId: meta.podId,
+    confidence: 0,
+    observedAt: new Date().toISOString(),
+  };
+}

backend/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "lib": ["ES2023"],
+    "types": ["node"]
+  },
+  "include": ["src/**/*"]
+}