@pablopunk/webr 0.1.1

package/src/server/transport/herdr-target.ts

@@ -0,0 +1,148 @@
+import type { TargetAdapter, LaunchLocation, TerminalDirection } from '../runtime/target';
+import type { TargetProfile } from './registry';
+import { localSocket } from './registry';
+import { SocketApi } from '../protocol/socket';
+import { nativeSnapshot, nativeWorkspace, nativeTab, nativePane } from '../protocol/native';
+import { openCliStream } from '../terminal/cli';
+import { boundedProcess } from './process';
+import { SshForward, sshOptions, remoteCommand, quoteShell } from './ssh';
+import type { LaunchInput } from '../../shared/runtime';
+import type { Machine } from '../../lib/machines';
+import { harnessName } from '../../lib/models';
+import { acceptsModelFlag, herdrAgentKinds, isHerdrAgentKind } from '../../shared/agent-kinds';
+import { modelListings, parseModelListing } from './model-discovery';
+import { HerdrActions } from '../runtime/herdr-actions';
+import { readApprovedIcon, type Icon } from './icons';
+import { targetFingerprint } from './identity';
+import { scopedProjectId } from '../../shared/projects';
+import { validateInstalledSchema } from '../protocol/validate';
+import { ensureLocalSession } from './local-session';
+import { nativeLocations } from './native-locations';
+
+const MODEL_LISTING_TIMEOUT_MS = 15_000;
+const MODEL_LISTING_LIMIT = 4 * 1024 * 1024;
+type Dependencies = { process: typeof boundedProcess; cli: typeof openCliStream };
+export class HerdrTarget implements TargetAdapter {
+  readonly id; readonly name; readonly session; readonly locations: LaunchLocation[];
+  readonly fingerprint; configVersion = 1;
+  get enabled() { return this.profile.enabled; }
+  get writable() { return this.compatible; }
+  get acceptsLocalFiles() { return this.profile.transport === 'local'; }
+  private api?: SocketApi;
+  private forwarding?: SshForward;
+  private compatible = false;
+  private connecting?: Promise<SocketApi>;
+  private streams = new Set<ReturnType<typeof openCliStream>>();
+  private icons = new Map<string, { expires: number; value: Promise<Icon | undefined> }>();
+  constructor(private profile: TargetProfile, private dependencies: Dependencies = { process: boundedProcess, cli: openCliStream }) {
+    this.id = profile.id; this.name = profile.name; this.session = profile.session;
+    this.fingerprint = targetFingerprint(profile);
+    this.locations = profile.locations.map((location) => ({ ...location, localId: location.projectId, logicalId: location.logicalId ?? location.projectId, projectId: scopedProjectId(profile.id, location.projectId) }));
+  }
+  private command(args: string[]) {
+    const env: NodeJS.ProcessEnv = { ...process.env, HERDR_SOCKET_PATH: this.profile.socket ?? localSocket(this.profile) };
+    delete env.HERDR_SESSION;
+    return this.profile.transport === 'local'
+      ? { command: this.profile.executable ?? 'herdr', args, env }
+      : { command: 'ssh', args: [...sshOptions, this.profile.host!, remoteCommand(this.profile.socket!, this.profile.executable ?? 'herdr', args)], env: process.env };
+  }
+  private async connect() {
+    if (this.connecting) return this.connecting;
+    if (this.api) return this.api;
+    this.connecting ??= (async () => {
+      if (!this.profile.enabled || !(this.profile.automatic && this.profile.transport === 'local') && process.env.WEBR_CONNECT !== '1') throw new Error('connection_not_approved');
+      if (this.profile.automatic && this.profile.transport === 'local') await ensureLocalSession(this.profile);
+      if (this.profile.transport === 'ssh') {
+        this.forwarding = new SshForward(this.profile.host!, this.profile.socket!);
+        this.api = await this.forwarding.open();
+      } else this.api = new SocketApi(localSocket(this.profile));
+      const ping = await this.api.request('ping');
+      const command = this.command(['--version']);
+      const version = await this.dependencies.process(command.command, command.args, command.env);
+      const compatible = ping.protocol === 22 && ping.version === '0.9.3' && /^herdr 0\.9\.3\s*$/.test(version);
+      if (!compatible) throw new Error('unsupported_herdr_version');
+      const schemaCommand = this.command(['api', 'schema', '--json']);
+      const schema = JSON.parse(await this.dependencies.process(schemaCommand.command, schemaCommand.args, schemaCommand.env, 5000, 2 * 1024 * 1024));
+      if (validateInstalledSchema(schema).length) { this.compatible = false; throw new Error('unsupported_herdr_schema'); }
+      this.compatible = true;
+      return this.api;
+    })();
+    try { return await this.connecting; }
+    catch (error) { await this.disconnect(); throw error; }
+    finally { this.connecting = undefined; }
+  }
+  async subscribe(onEvent: () => void, onClose: (reason: string) => void, paneIds: string[] = []) {
+    return (await this.connect()).subscribe(onEvent, (reason) => { this.api?.close(); this.api = undefined; this.compatible = false; void this.forwarding?.close(); this.forwarding = undefined; onClose(reason); }, paneIds);
+  }
+  async snapshot() {
+    const snapshot = nativeSnapshot.parse((await (await this.connect()).request('session.snapshot')).snapshot);
+    if (snapshot.version !== '0.9.3') { this.compatible = false; throw new Error('unsupported_herdr_version'); }
+    if (this.profile.automatic && this.profile.transport === 'local') this.locations.splice(0, this.locations.length, ...nativeLocations(this.id, snapshot));
+    return snapshot;
+  }
+  async createWorkspace(path: string, label: string, requestId: string) {
+    if (this.profile.transport !== 'local' || !this.profile.automatic || !this.compatible) throw new Error('workspace_creation_unavailable');
+    const result = await (await this.connect()).request('workspace.create', { cwd: path, label, focus: false }, { timeoutMs: 30_000, requestId });
+    const workspace = nativeWorkspace.parse(result.workspace); const tab = nativeTab.parse(result.tab); const pane = nativePane.parse(result.root_pane);
+    if (tab.workspace_id !== workspace.workspace_id || pane.workspace_id !== workspace.workspace_id || pane.tab_id !== tab.tab_id) throw new Error('workspace_identity_mismatch');
+    return { workspaceId: workspace.workspace_id, tabId: tab.tab_id, terminalId: pane.terminal_id };
+  }
+  async catalog(_projectId?: string): Promise<Machine> {
+    const api = await this.connect();
+    await api.request('ping');
+    const run = (command: string, args: string[]) => this.profile.transport === 'local'
+      ? this.dependencies.process(command, args, undefined, MODEL_LISTING_TIMEOUT_MS, MODEL_LISTING_LIMIT)
+      : this.dependencies.process('ssh', [...sshOptions, this.profile.host!, [command, ...args].map(quoteShell).join(' ')], undefined, MODEL_LISTING_TIMEOUT_MS, MODEL_LISTING_LIMIT);
+    const isPresent = (kind: string) => run('/bin/sh', ['-c', 'command -v "$1" >/dev/null', 'sh', kind]).then(() => true, () => false);
+    const listModels = (kind: string) => modelListings[kind] ? run(kind, modelListings[kind].args).then((output) => parseModelListing(kind, output), () => []) : Promise.resolve([]);
+    const present = (await Promise.all(herdrAgentKinds.map(async (kind) => (await isPresent(kind)) ? kind : undefined))).filter((kind): kind is string => !!kind);
+    const discovered = await Promise.all(present.map(listModels));
+    return { id: this.id, name: this.name, session: this.session, connected: true, writable: this.writable, configVersion: this.configVersion, projectPaths: Object.fromEntries(this.locations.map((location) => [location.projectId, location.path])), harnesses: present.map((id, index) => ({ id, name: harnessName(id), models: ['Default', ...discovered[index]], customModels: acceptsModelFlag(id), launchEnabled: true })) };
+  }
+  async icon(projectId: string) {
+    const location = this.locations.find((location) => location.projectId === projectId);
+    if (this.profile.transport !== 'local' || !location) return;
+    const cached = this.icons.get(projectId);
+    if (cached && cached.expires > Date.now()) return cached.value;
+    const value = readApprovedIcon(location.path);
+    this.icons.set(projectId, { expires: Date.now() + 60_000, value }); return value;
+  }
+  openTerminal: TargetAdapter['openTerminal'] = (terminalId, mode, cols, rows, takeover, onFrame, onClose) => {
+    if (!this.compatible || mode === 'control' && !this.writable || mode === 'observe' && takeover) throw new Error('terminal_control_unavailable');
+    const command = this.command(['terminal', 'session', mode, terminalId, '--cols', String(cols), '--rows', String(rows), ...(takeover ? ['--takeover'] : [])]);
+    const stream = this.dependencies.cli(command.command, command.args, { env: command.env }, onFrame, (reason) => { this.streams.delete(stream); onClose(reason); });
+    this.streams.add(stream); return stream;
+  };
+  async create(input: LaunchInput, threadId: string) { return this.actions().create(input, threadId); }
+  canLaunch(input: LaunchInput) { return this.compatible && isHerdrAgentKind(input.agent) && this.locations.some((location) => location.projectId === input.projectId); }
+  async start(input: LaunchInput, paneId: string, threadId: string) { return this.actions().start(input, paneId, threadId); }
+  async prompt(paneId: string, prompt: string, terminalId: string, threadId: string, input: LaunchInput) { return this.actions().prompt(paneId, prompt, terminalId, threadId, input.agent, input); }
+  async worktrees(projectId: string) { return this.actions().worktrees(this.workspaceOf(projectId)); }
+  async openWorktree(projectId: string, path: string) { return this.actions().openWorktree(this.workspaceOf(projectId), path); }
+  private workspaceOf(projectId: string) {
+    const location = this.locations.find((location) => location.projectId === projectId);
+    if (!location) throw new Error('unknown_project_location');
+    return location.workspaceId;
+  }
+  /** 'app' when a full-screen program, not the shell, owns the pane and has no history to scroll through. */
+  async scrollMode(terminalId: string): Promise<'scrollback' | 'app'> {
+    const pane = (await this.snapshot()).panes.find((candidate) => candidate.terminal_id === terminalId);
+    if (!pane || (pane.scroll?.max_offset_from_bottom ?? 0) > 0) return 'scrollback';
+    const info = (await (await this.connect()).request('pane.process_info', { pane_id: pane.pane_id })).process_info as { foreground_process_group_id?: number; shell_pid?: number } | undefined;
+    return info?.foreground_process_group_id !== undefined && info.foreground_process_group_id !== info.shell_pid ? 'app' : 'scrollback';
+  }
+  async focusPane(paneId: string) { return this.actions().focus(paneId); }
+  async renameTab(tabId: string, label: string, renameWorkspace: boolean) { return this.actions().renameTab(await this.snapshot(), tabId, label, renameWorkspace); }
+  async splitTerminal(paneId: string, direction: TerminalDirection) { return this.actions().splitTerminal(await this.snapshot(), paneId, direction); }
+  async closePane(paneId: string) { return this.actions().closePane(paneId); }
+  async discardTab(tabId: string, removeWorktree: boolean) { return this.actions().discardTab(await this.snapshot(), tabId, removeWorktree); }
+  private actions() {
+    return new HerdrActions({ request: async (method, params, options) => {
+      const api = await this.connect(); const ping = await api.request('ping');
+      if (ping.version !== '0.9.3' || ping.protocol !== 22) { this.compatible = false; throw new Error('unsupported_herdr_version'); }
+      return api.request(method, params, options);
+    } }, this.locations, (input) => { if (!input || !this.canLaunch(input)) throw new Error('launch_unavailable'); });
+  }
+  close() { this.compatible = false; this.api?.close(); this.api = undefined; for (const stream of this.streams) stream.close(); void this.forwarding?.close(); }
+  private async disconnect() { this.compatible = false; this.api?.close(); this.api = undefined; await this.forwarding?.close(); this.forwarding = undefined; }
+}

package/src/server/transport/icons.ts

@@ -0,0 +1,65 @@
+import { readdir, realpath, stat, readFile } from 'node:fs/promises';
+import { basename, dirname, extname, isAbsolute, join, relative, sep } from 'node:path';
+
+const contentTypes: Record<string, string> = { '.ico': 'image/x-icon', '.png': 'image/png', '.svg': 'image/svg+xml', '.webp': 'image/webp' };
+const directories = ['', 'public', 'static', 'assets', 'web/public', 'app/public', 'src/assets', 'src/app', 'frontend/public'];
+export type Icon = { bytes: Buffer; contentType: string };
+
+function withinRoot(root: string, path: string) {
+  const part = relative(root, path);
+  return part !== '..' && !part.startsWith(`..${sep}`) && !isAbsolute(part);
+}
+
+function rank(name: string) {
+  const extension = extname(name).toLowerCase();
+  if (!contentTypes[extension]) return Infinity;
+  const stem = name.slice(0, -extension.length).toLowerCase();
+  if (stem === 'favicon') return 0;
+  if (stem.startsWith('favicon-')) return 1;
+  if (stem.startsWith('apple-touch-icon')) return 2;
+  if (stem === 'icon' || stem === 'app-icon') return 3;
+  if (stem.startsWith('icon-') || stem === 'logo' || stem === 'brand' || stem === 'mark') return 4;
+  if (stem.startsWith('logo-') || stem.startsWith('brand-')) return 5;
+  return Infinity;
+}
+
+async function iconInDirectory(root: string, directory: string): Promise<Icon | undefined> {
+  let actual: string;
+  try { actual = await realpath(directory); } catch { return; }
+  if (!withinRoot(root, actual)) return;
+  let entries;
+  try { entries = await readdir(actual, { withFileTypes: true }); } catch { return; }
+  entries = entries
+    .filter((entry) => (entry.isFile() || entry.isSymbolicLink()) && Number.isFinite(rank(entry.name)))
+    .sort((a, b) => rank(a.name) - rank(b.name) || a.name.localeCompare(b.name));
+  for (const entry of entries) {
+    try {
+      const file = await realpath(join(actual, entry.name));
+      if (!withinRoot(root, file)) continue;
+      const info = await stat(file);
+      if (!info.isFile() || info.size <= 0 || info.size > 1024 * 1024) continue;
+      const bytes = await readFile(file);
+      if (bytes.length <= 1024 * 1024) return { bytes, contentType: contentTypes[extname(entry.name).toLowerCase()] };
+    } catch {}
+  }
+}
+
+async function appDirectories(root: string) {
+  let apps: string;
+  try { apps = await realpath(join(root, 'apps')); } catch { return []; }
+  if (!withinRoot(root, apps)) return [];
+  const brand = (basename(root) === 'monorepo' ? basename(dirname(root)) : basename(root)).toLowerCase();
+  let entries;
+  try { entries = (await readdir(apps, { withFileTypes: true })).filter((entry) => entry.isDirectory()); } catch { return []; }
+  return entries.sort((a, b) => Number(!a.name.toLowerCase().includes(brand)) - Number(!b.name.toLowerCase().includes(brand)) || a.name.localeCompare(b.name))
+    .slice(0, 32).flatMap((entry) => ['public', 'static', 'assets', 'src/assets', 'src/app'].map((part) => join(apps, entry.name, part)));
+}
+
+export async function readApprovedIcon(path: string): Promise<Icon | undefined> {
+  let root: string;
+  try { root = await realpath(path); } catch { return; }
+  for (const directory of [...directories.map((part) => join(root, part)), ...await appDirectories(root)]) {
+    const icon = await iconInDirectory(root, directory);
+    if (icon) return icon;
+  }
+}

package/src/server/transport/identity.ts

@@ -0,0 +1,5 @@
+import { createHash } from 'node:crypto';
+import { localSocket, type TargetProfile } from './registry';
+export function targetFingerprint(profile: TargetProfile) {
+  return createHash('sha256').update(JSON.stringify({ id: profile.id, transport: profile.transport, host: profile.transport === 'ssh' ? profile.host : 'local', socket: profile.transport === 'ssh' ? profile.socket : localSocket(profile), session: profile.session, executable: profile.executable ?? 'herdr' })).digest('hex');
+}

package/src/server/transport/local-session.ts

@@ -0,0 +1,65 @@
+import { spawn } from 'node:child_process';
+import { lstat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+import { SocketApi } from '../protocol/socket';
+import { boundedProcess } from './process';
+import { localSocket, profileSchema, type TargetProfile } from './registry';
+
+const sessionName = z.string().regex(/^[A-Za-z0-9_.-]{1,64}$/).refine((name) => !['.', '..'].includes(name));
+const sessionsResult = z.object({ sessions: z.array(z.object({ name: sessionName, default: z.boolean(), running: z.boolean(), socket_path: z.string().startsWith('/') })).min(1).max(1000) });
+const pathExists = async (path: string) => { try { await lstat(path); return true; } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false; throw error; } };
+const ping = async (socket: string) => { const api = new SocketApi(socket); try { return await api.request('ping'); } finally { api.close(); } };
+const start = async (profile: TargetProfile) => {
+  const env: NodeJS.ProcessEnv = { ...process.env, HERDR_SOCKET_PATH: localSocket(profile), HERDR_SESSION: profile.session };
+  delete env.HERDR_CLIENT_SOCKET_PATH;
+  delete env.HERDR_STARTUP_CWD;
+  const child = spawn(profile.executable ?? 'herdr', ['server'], { env, detached: true, stdio: 'ignore' });
+  await new Promise<void>((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject); });
+  child.unref();
+};
+export type LocalSessionDependencies = { process: typeof boundedProcess; exists: typeof pathExists; ping: typeof ping; start: typeof start; sleep: (ms: number) => Promise<void> };
+const defaults: LocalSessionDependencies = { process: boundedProcess, exists: pathExists, ping, start, sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)) };
+
+export async function discoverLocalSession(env = process.env, runProcess = boundedProcess, exists = pathExists): Promise<TargetProfile> {
+  const base = { id: 'local', name: 'Local', session: env.HERDR_SESSION ?? 'default', enabled: true, transport: 'local', locations: [], automatic: true };
+  if (env.HERDR_SOCKET_PATH) return profileSchema.parse({ ...base, socket: env.HERDR_SOCKET_PATH });
+  if (env.HERDR_SESSION) return profileSchema.parse(base);
+  const { sessions } = sessionsResult.parse(JSON.parse(await runProcess('herdr', ['session', 'list', '--json'], env)));
+  const running = sessions.filter((session) => session.running);
+  const selected = running.find((session) => session.default) ?? (running.length === 1 ? running[0] : undefined);
+  if (running.length && !selected) throw new Error('multiple_herdr_sessions: start the app from the desired Herdr session');
+  const current = selected ?? sessions.find((session) => session.default);
+  if (!current) throw new Error('missing_default_session');
+  if (!selected) for (const session of sessions) {
+    if (await exists(session.socket_path) || await exists(join(dirname(session.socket_path), 'herdr-client.sock'))) throw new Error('herdr_session_unreachable');
+  }
+  return profileSchema.parse({ ...base, session: current.name, socket: current.socket_path });
+}
+
+export function localSessionBootstrap(dependencies: LocalSessionDependencies = defaults) {
+  const pending = new Map<string, Promise<void>>();
+  return (profile: TargetProfile): Promise<void> => {
+    const socket = localSocket(profile);
+    const existing = pending.get(socket);
+    if (existing) return existing;
+    const promise = (async () => {
+      try { await dependencies.ping(socket); return; }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+      if (await dependencies.exists(socket) || await dependencies.exists(join(dirname(socket), 'herdr-client.sock'))) throw new Error('herdr_session_unreachable');
+      const version = await dependencies.process(profile.executable ?? 'herdr', ['--version']);
+      if (version.trim() !== 'herdr 0.9.3') throw new Error('unsupported_herdr_version');
+      await dependencies.start(profile);
+      for (let attempt = 0; attempt < 100; attempt++) {
+        try { await dependencies.ping(socket); return; }
+        catch (error) { if (!['ENOENT', 'ECONNREFUSED'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error; }
+        await dependencies.sleep(100);
+      }
+      throw new Error('herdr_session_start_unknown');
+    })();
+    pending.set(socket, promise);
+    return promise;
+  };
+}
+
+export const ensureLocalSession = localSessionBootstrap();

package/src/server/transport/model-discovery.ts

@@ -0,0 +1,18 @@
+const lines = (output: string) => output.split('\n').map((line) => line.trim()).filter(Boolean);
+const codexSlugs = (output: string) => (JSON.parse(output).models as { slug: string }[]).map((model) => model.slug);
+const piIds = (output: string) => lines(output).slice(1).map((line) => line.split(/\s+/)).map(([provider, model]) => provider + '/' + model);
+const firstColumn = (output: string) => lines(output).map((line) => line.split('\t')).filter((columns) => columns.length > 1).map(([id]) => id);
+
+export const modelListings: Record<string, { args: string[]; parse: (output: string) => string[] }> = {
+  opencode: { args: ['models'], parse: lines },
+  pi: { args: ['--list-models'], parse: piIds },
+  codex: { args: ['debug', 'models'], parse: codexSlugs },
+  agy: { args: ['models'], parse: firstColumn },
+};
+const validModel = /^[A-Za-z0-9_/.:+-]{1,120}$/;
+
+export function parseModelListing(kind: string, output: string): string[] {
+  const listing = modelListings[kind];
+  if (!listing) return [];
+  try { return [...new Set(listing.parse(output).filter((id) => validModel.test(id)))]; } catch { return []; }
+}

package/src/server/transport/native-locations.ts

@@ -0,0 +1,17 @@
+import type { NativeSnapshot } from '../protocol/native';
+import type { LaunchLocation } from '../runtime/target';
+import { projectIdentity } from '../runtime/reconcile';
+import { scopedProjectId } from '../../shared/projects';
+
+export function nativeLocations(machineId: string, snapshot: NativeSnapshot): LaunchLocation[] {
+  const locations = new Map<string, LaunchLocation>();
+  for (const workspace of snapshot.workspaces) {
+    const path = workspace.worktree?.repo_root ?? snapshot.panes.find((pane) => pane.workspace_id === workspace.workspace_id)?.cwd;
+    if (!path?.startsWith('/')) continue;
+    const logicalId = workspace.worktree?.repo_key ?? path;
+    const localId = projectIdentity(machineId, logicalId);
+    const projectId = scopedProjectId(machineId, localId);
+    if (!locations.has(projectId) || !workspace.worktree?.is_linked_worktree) locations.set(projectId, { projectId, localId, logicalId, path, workspaceId: workspace.workspace_id });
+  }
+  return [...locations.values()];
+}

package/src/server/transport/process.ts

@@ -0,0 +1,21 @@
+import { spawn } from 'node:child_process';
+
+export function boundedProcess(command: string, args: string[], env?: NodeJS.ProcessEnv, timeout = 5000, limit = 64 * 1024): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { env, shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
+    const chunks: Buffer[] = [];
+    let size = 0;
+    let stderrSize = 0;
+    let finished = false;
+    const finish = (error?: Error) => {
+      if (finished) return;
+      finished = true; clearTimeout(timer);
+      if (error) { child.kill('SIGTERM'); reject(error); } else resolve(Buffer.concat(chunks).toString('utf8'));
+    };
+    const timer = setTimeout(() => finish(new Error('process_timeout')), timeout);
+    child.stdout.on('data', (chunk: Buffer) => { size += chunk.length; if (size > limit) finish(new Error('process_output_limit')); else chunks.push(chunk); });
+    child.stderr.on('data', (chunk: Buffer) => { stderrSize += chunk.length; if (stderrSize > limit) finish(new Error('process_stderr_limit')); });
+    child.on('error', () => finish(new Error('process_unavailable')));
+    child.on('exit', (code) => finish(code === 0 ? undefined : new Error('process_failed')));
+  });
+}

package/src/server/transport/registry.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+
+export const profileSchema = z.object({
+  id: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/), name: z.string().min(1).max(80), session: z.string().regex(/^[A-Za-z0-9_.-]{1,64}$/).refine((name) => !['.', '..'].includes(name)), enabled: z.boolean(),
+  automatic: z.boolean().optional(),
+  transport: z.enum(['local', 'ssh']), host: z.string().regex(/^[A-Za-z0-9_][A-Za-z0-9_.@-]{0,200}$/).optional(),
+  socket: z.string().regex(/^\/[A-Za-z0-9_./-]+$/).optional(),
+  executable: z.string().regex(/^(?:\/[A-Za-z0-9_./-]+|[A-Za-z0-9_.-]+)$/).optional(),
+  locations: z.array(z.object({ projectId: z.string().regex(/^[A-Za-z0-9_-]+$/), logicalId: z.string().regex(/^[A-Za-z0-9_.-]{1,128}$/).optional(), path: z.string().startsWith('/').max(1000), workspaceId: z.string().min(1).max(160) }).strict()).max(100),
+}).strict().superRefine((value, context) => { if (value.transport === 'ssh' && (!value.host || !value.socket)) context.addIssue({ code: 'custom', message: 'SSH requires a host and a verified absolute socket' }); });
+export type TargetProfile = z.infer<typeof profileSchema>;
+export async function loadRegistry(path?: string): Promise<TargetProfile[]> {
+  if (!path) return [await (await import('./local-session')).discoverLocalSession()];
+  const profiles = z.array(profileSchema).max(32).parse(JSON.parse(await readFile(path, 'utf8')));
+  if (new Set(profiles.map((profile) => profile.id)).size !== profiles.length) throw new Error('duplicate_target');
+  if (profiles.some((profile) => new Set(profile.locations.map((location) => location.projectId)).size !== profile.locations.length)) throw new Error('duplicate_project_location');
+  return profiles;
+}
+export function localSocket(profile: TargetProfile) {
+  if (profile.transport !== 'local') throw new Error('not_local');
+  if (profile.socket) return profile.socket;
+  const config = process.env.HERDR_CONFIG_PATH ? join(process.env.HERDR_CONFIG_PATH, '..') : join(process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'herdr');
+  return profile.session === 'default' ? join(config, 'herdr.sock') : join(config, 'sessions', profile.session, 'herdr.sock');
+}

package/src/server/transport/ssh.ts

@@ -0,0 +1,47 @@
+import { spawn, type ChildProcess } from 'node:child_process';
+import { mkdtemp, chmod, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { SocketApi } from '../protocol/socket';
+
+export const quoteShell = (value: string) => "'" + value.replaceAll("'", "'\\''") + "'";
+export const sshOptions = ['-T', '-o', 'BatchMode=yes', '-o', 'StrictHostKeyChecking=yes', '-o', 'ConnectTimeout=5', '-o', 'ServerAliveInterval=5', '-o', 'ServerAliveCountMax=2', '-o', 'ExitOnForwardFailure=yes', '-o', 'ForwardAgent=no'];
+export function remoteCommand(socket: string, command: string, args: string[]) {
+  if (/[\0\r\n]/.test(socket + command + args.join(''))) throw new Error('invalid_remote_command');
+  return ['env', 'HERDR_SOCKET_PATH=' + socket, command, ...args].map(quoteShell).join(' ');
+}
+
+export class SshForward {
+  private process?: ChildProcess;
+  private directory?: string;
+  private api?: SocketApi;
+  constructor(private host: string, private remoteSocket: string) {
+    if (!/^[A-Za-z0-9_][A-Za-z0-9_.@-]{0,200}$/.test(host) || !/^\/[A-Za-z0-9_./-]+$/.test(remoteSocket)) throw new Error('invalid_ssh_target');
+  }
+  async open() {
+    if (this.api) return this.api;
+    this.directory = await mkdtemp(join(tmpdir(), 'hw-'));
+    await chmod(this.directory, 0o700);
+    const path = join(this.directory, 'a.sock');
+    if (Buffer.byteLength(path) > 103) { await this.close(); throw new Error('socket_path_limit'); }
+    const child = spawn('ssh', [...sshOptions, '-N', '-L', `${path}:${this.remoteSocket}`, this.host], { stdio: ['ignore', 'ignore', 'pipe'] });
+    this.process = child;
+    const api = new SocketApi(path);
+    let failed = false;
+    let stderrBytes = 0;
+    child.on('error', () => { failed = true; });
+    child.on('exit', () => { failed = true; api.close(); this.api = undefined; });
+    child.stderr?.on('data', (chunk: Buffer) => { stderrBytes += chunk.length; if (stderrBytes > 16 * 1024) child.kill('SIGTERM'); });
+    const end = Date.now() + 5000;
+    while (!failed && Date.now() < end) {
+      try { await api.request('ping'); this.api = api; return api; } catch { await new Promise((resolve) => setTimeout(resolve, 50)); }
+    }
+    await this.close(); throw new Error('ssh_forward_failed');
+  }
+  async close() {
+    this.api?.close(); this.api = undefined;
+    this.process?.kill('SIGTERM'); this.process = undefined;
+    if (this.directory) await rm(this.directory, { recursive: true, force: true });
+    this.directory = undefined;
+  }
+}

package/src/server/uploads.ts

@@ -0,0 +1,40 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+export const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+const UPLOAD_LIFETIME_MS = 7 * 24 * 60 * 60 * 1000;
+const startsWith = (bytes: Buffer, signature: number[], offset = 0) => signature.every((byte, index) => bytes[offset + index] === byte);
+const ascii = (text: string) => [...text].map((character) => character.charCodeAt(0));
+const imageTypes: Record<string, { extension: string; matches: (bytes: Buffer) => boolean }> = {
+  'image/png': { extension: 'png', matches: (bytes) => startsWith(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]) },
+  'image/jpeg': { extension: 'jpg', matches: (bytes) => startsWith(bytes, [0xff, 0xd8, 0xff]) },
+  'image/gif': { extension: 'gif', matches: (bytes) => startsWith(bytes, ascii('GIF87a')) || startsWith(bytes, ascii('GIF89a')) },
+  'image/webp': { extension: 'webp', matches: (bytes) => startsWith(bytes, ascii('RIFF')) && startsWith(bytes, ascii('WEBP'), 8) },
+};
+export const uploadContentTypes = Object.keys(imageTypes);
+
+export function imageExtension(contentType: string | undefined, bytes: Buffer) {
+  const type = imageTypes[contentType?.split(';')[0].trim().toLowerCase() ?? ''];
+  if (!type || !bytes.length || !type.matches(bytes)) throw new Error('unsupported_image');
+  return type.extension;
+}
+
+export class UploadStore {
+  constructor(readonly directory = resolve(process.env.WEBR_UPLOADS ?? '.data/uploads'), private lifetimeMs = UPLOAD_LIFETIME_MS) {}
+  async save(contentType: string | undefined, bytes: Buffer) {
+    const extension = imageExtension(contentType, bytes);
+    await mkdir(this.directory, { recursive: true, mode: 0o700 });
+    const path = join(this.directory, `image-${randomUUID()}.${extension}`);
+    await writeFile(path, bytes, { mode: 0o600, flag: 'wx' });
+    void this.removeExpired().catch(() => {});
+    return path;
+  }
+  async removeExpired(now = Date.now()) {
+    for (const name of await readdir(this.directory).catch(() => [] as string[])) {
+      if (!/^image-[0-9a-f-]{36}\.(png|jpg|gif|webp)$/.test(name)) continue;
+      const path = join(this.directory, name);
+      if (now - (await stat(path)).mtimeMs > this.lifetimeMs) await rm(path, { force: true });
+    }
+  }
+}

package/src/server/websockets.ts

@@ -0,0 +1,62 @@
+import type { FastifyInstance } from 'fastify';
+import type { WebSocket } from 'ws';
+import type { RuntimeManager } from './runtime/manager';
+import { TerminalHub } from './terminal/hub';
+import { terminalAction } from '../shared/runtime';
+import { z } from 'zod';
+
+export function registerWebsockets(app: FastifyInstance, manager: RuntimeManager) {
+  const hub = new TerminalHub(manager);
+  const pairs = new Map<string, { metadata?: WebSocket; terminal?: WebSocket; close: () => void }>();
+  for (const kind of ['metadata', 'terminal'] as const) {
+    app.get(`/api/ws/${kind}`, { websocket: true }, (socket, request) => {
+      const parsed = z.object({ instance: z.uuid() }).strict().safeParse(request.query);
+      if (!parsed.success) { socket.close(1008); return; }
+      const owner = parsed.data.instance;
+      let pair = pairs.get(owner);
+      if (!pair) {
+        if (pairs.size >= 32) { socket.close(1013); return; }
+        let pairing: ReturnType<typeof setTimeout> | undefined;
+        const publish = (projection: unknown) => {
+          if (!pair?.metadata || pair.metadata.readyState !== 1) return;
+          const value = JSON.stringify({ type: 'projection', projection });
+          if (Buffer.byteLength(value) + pair.metadata.bufferedAmount > 2 * 1024 * 1024) { pair.close(); return; }
+          pair.metadata.send(value);
+        };
+        const close = () => {
+          if (!pairs.has(owner)) return;
+          pairs.delete(owner); clearTimeout(pairing);
+          manager.off('projection', publish); hub.detach(owner);
+          pair?.metadata?.close(1008); pair?.terminal?.close(1008);
+        };
+        pair = { close }; pairs.set(owner, pair);
+        manager.on('projection', publish);
+        pairing = setTimeout(() => { if (!pair?.metadata || !pair.terminal) close(); }, 5000);
+        pairing.unref();
+      }
+      if (pair[kind]) { socket.close(1008); return; }
+      pair[kind] = socket;
+      if (kind === 'terminal') hub.attach(owner, socket);
+      let pending = 0;
+      let commands = Promise.resolve();
+      socket.on('message', (data, binary) => {
+        if (binary || kind !== 'terminal' || ++pending > 16) { pair!.close(); return; }
+        let value: unknown;
+        try { value = JSON.parse(data.toString()); } catch { pair!.close(); return; }
+        const validated = terminalAction.safeParse(value);
+        if (!validated.success) { pair!.close(); return; }
+        commands = commands.then(async () => {
+          if (!pairs.has(owner)) return;
+          if (!pair?.metadata || !pair.terminal) { pair!.close(); return; }
+          try { hub.action(owner, validated.data); }
+          catch (error) { if (socket.readyState === 1) socket.send(JSON.stringify({ type: 'stream.error', streamId: validated.data.streamId, generation: validated.data.generation, reason: error instanceof Error ? error.message : 'action_failed' })); }
+        }).catch(() => pair!.close()).finally(() => { --pending; });
+      });
+      socket.on('error', () => pair!.close());
+      socket.on('close', () => pair!.close());
+      if (kind === 'metadata') for (const projection of manager.bootstrap().projections) socket.send(JSON.stringify({ type: 'projection', projection }));
+    });
+  }
+  app.addHook('onClose', async () => { for (const pair of pairs.values()) pair.close(); hub.close(); });
+  return hub;
+}

package/src/shared/agent-kinds.ts

@@ -0,0 +1,4 @@
+export const herdrAgentKinds = ['pi', 'claude', 'codex', 'gemini', 'cursor', 'devin', 'agy', 'cline', 'omp', 'mastracode', 'opencode', 'copilot', 'kimi', 'kiro', 'droid', 'amp', 'grok', 'hermes', 'kilo', 'qodercli', 'qwen', 'letta', 'maki', 'muse'];
+const kindsWithModelFlag = ['claude', 'codex', 'opencode', 'pi', 'agy', 'hermes'];
+export const isHerdrAgentKind = (kind: string) => herdrAgentKinds.includes(kind);
+export const acceptsModelFlag = (kind: string) => kindsWithModelFlag.includes(kind);

package/src/shared/frame.ts

@@ -0,0 +1,38 @@
+export const HEADER_SIZE = 32;
+export const MAX_FRAME_BYTES = 256 * 1024;
+export type Frame = { streamId: number; generation: number; seq: number; width: number; height: number; full: boolean; bytes: Uint8Array };
+
+export function encodeFrame(frame: Frame): Uint8Array {
+  if (frame.bytes.length > MAX_FRAME_BYTES) throw new Error('frame_limit');
+  const packet = new Uint8Array(HEADER_SIZE + frame.bytes.length);
+  const view = new DataView(packet.buffer);
+  view.setUint32(0, 0x48445231);
+  view.setUint32(4, frame.streamId);
+  view.setUint32(8, frame.generation);
+  view.setBigUint64(12, BigInt(frame.seq));
+  view.setUint16(20, frame.width);
+  view.setUint16(22, frame.height);
+  view.setUint32(24, frame.bytes.length);
+  view.setUint8(28, frame.full ? 1 : 0);
+  packet.set(frame.bytes, HEADER_SIZE);
+  return packet;
+}
+
+export function decodeFrame(packet: Uint8Array): Frame {
+  if (packet.length < HEADER_SIZE) throw new Error('short_frame');
+  const view = new DataView(packet.buffer, packet.byteOffset, packet.byteLength);
+  const seq = Number(view.getBigUint64(12));
+  if (view.getUint32(0) !== 0x48445231 || view.getUint32(24) !== packet.length - HEADER_SIZE || packet.length - HEADER_SIZE > MAX_FRAME_BYTES || !Number.isSafeInteger(seq) || view.getUint8(28) > 1 || view.getUint8(29) || view.getUint16(30)) throw new Error('invalid_frame');
+  const frame = { streamId: view.getUint32(4), generation: view.getUint32(8), seq, width: view.getUint16(20), height: view.getUint16(22), full: !!view.getUint8(28), bytes: packet.subarray(HEADER_SIZE) };
+  if (!frame.streamId || !frame.generation || !frame.width || frame.width > 500 || !frame.height || frame.height > 300) throw new Error('invalid_dimensions');
+  return frame;
+}
+
+export class FrameSequence {
+  private seq: number | undefined;
+  accept(frame: Frame) {
+    if (this.seq === undefined && !frame.full) throw new Error('baseline_required');
+    if (this.seq !== undefined && frame.seq !== this.seq + 1) throw new Error('sequence_gap');
+    this.seq = frame.seq;
+  }
+}

package/src/shared/projects.ts

@@ -0,0 +1 @@
+export const scopedProjectId = (machineId: string, localId: string) => `${machineId}:${localId}`;

package/src/shared/retry.ts

@@ -0,0 +1 @@
+export const retryDelay = (attempt: number, random = Math.random) => Math.min(30_000, Math.round(Math.min(25_000, 1000 * 2 ** Math.min(attempt, 5)) * (0.8 + random() * 0.4)));

package/src/shared/runtime.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import type { Project, Thread } from '../lib/models';
+import type { Machine } from '../lib/machines';
+
+export const opaqueId = z.string().min(1).max(160).regex(/^[A-Za-z0-9_:.-]+$/);
+export const launchInput = z.object({
+  machineId: opaqueId, projectId: opaqueId,
+  prompt: z.string().trim().min(1).max(8000).refine((text) => !/[\x00\x1b]/.test(text)),
+  agent: z.string().regex(/^[a-z][a-z0-9_-]{0,31}$/),
+  model: z.string().trim().min(1).max(120).regex(/^[A-Za-z0-9_/.:+-]+$/),
+  worktree: z.boolean(),
+}).strict();
+export type LaunchInput = z.infer<typeof launchInput>;
+export type Rect = { x: number; y: number; width: number; height: number };
+export type Layout = { workspaceId: string; tabId: string; area: Rect; panes: { paneId: string; rect: Rect }[] };
+export type Projection = {
+  machineId: string; generation: string; revision: number; freshAt: string | null;
+  connected: boolean; error?: string; threads: Thread[]; projects: Project[]; layouts: Layout[];
+  availableTabs?: { tabId: string; workspaceId: string; label: string; bound: boolean; panes: { id: string; terminalId: string; title: string }[] }[];
+  machine?: Machine;
+};
+export type Bootstrap = { projections: Projection[]; machines: Machine[]; projects: Project[]; threads: Thread[] };
+const streamRef = { streamId: z.number().int().min(1).max(0xffffffff), generation: z.number().int().min(1).max(0xffffffff) };
+export const terminalAction = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('open'), ...streamRef, machineId: opaqueId, threadId: z.uuid(), terminalId: opaqueId, cols: z.number().int().min(2).max(500), rows: z.number().int().min(1).max(300), mode: z.enum(['observe', 'control']), takeover: z.boolean() }).strict(),
+  z.object({ type: z.literal('ack'), ...streamRef, seq: z.number().int().nonnegative() }).strict(),
+  z.object({ type: z.literal('release'), ...streamRef }).strict(),
+  z.object({ type: z.literal('input'), ...streamRef, text: z.string().min(1).max(8192), paste: z.boolean() }).strict(),
+  z.object({ type: z.literal('resize'), ...streamRef, cols: z.number().int().min(2).max(500), rows: z.number().int().min(1).max(300) }).strict(),
+  z.object({ type: z.literal('scroll'), ...streamRef, direction: z.enum(['up', 'down']), lines: z.number().int().min(1).max(100), column: z.number().int().min(1).max(500).optional(), row: z.number().int().min(1).max(300).optional() }).strict(),
+  z.object({ type: z.literal('mouse'), ...streamRef, action: z.enum(['down', 'up', 'drag', 'move']), button: z.enum(['left', 'right', 'middle']), column: z.number().int().min(0).max(499), row: z.number().int().min(0).max(299), modifiers: z.number().int().min(0).max(7) }).strict(),
+]);
+export type TerminalAction = z.infer<typeof terminalAction>;