Implement agent runtime services and WebSocket realtime

Expand heartbeat service with full run executor, wakeup coordinator,
and adapter lifecycle. Add run-log-store for pluggable log persistence.
Add live-events service and WebSocket handler for realtime updates.
Expand agent and issue routes with runtime operations. Add ws dependency.

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

server/src/services/activity-log.ts

@@ -1,5 +1,6 @@
 import type { Db } from "@paperclip/db";
 import { activityLog } from "@paperclip/db";
+import { publishLiveEvent } from "./live-events.js";
 
 export interface LogActivityInput {
   companyId: string;
@@ -23,4 +24,18 @@ export async function logActivity(db: Db, input: LogActivityInput) {
     agentId: input.agentId ?? null,
     details: input.details ?? null,
   });
+
+  publishLiveEvent({
+    companyId: input.companyId,
+    type: "activity.logged",
+    payload: {
+      actorType: input.actorType,
+      actorId: input.actorId,
+      action: input.action,
+      entityType: input.entityType,
+      entityId: input.entityId,
+      agentId: input.agentId ?? null,
+      details: input.details ?? null,
+    },
+  });
 }

server/src/services/index.ts

@@ -9,3 +9,4 @@ export { costService } from "./costs.js";
 export { heartbeatService } from "./heartbeat.js";
 export { dashboardService } from "./dashboard.js";
 export { logActivity, type LogActivityInput } from "./activity-log.js";
+export { publishLiveEvent, subscribeCompanyLiveEvents } from "./live-events.js";

server/src/services/live-events.ts

@@ -0,0 +1,40 @@
+import { EventEmitter } from "node:events";
+import type { LiveEvent, LiveEventType } from "@paperclip/shared";
+
+type LiveEventPayload = Record<string, unknown>;
+type LiveEventListener = (event: LiveEvent) => void;
+
+const emitter = new EventEmitter();
+emitter.setMaxListeners(0);
+
+let nextEventId = 0;
+
+function toLiveEvent(input: {
+  companyId: string;
+  type: LiveEventType;
+  payload?: LiveEventPayload;
+}): LiveEvent {
+  nextEventId += 1;
+  return {
+    id: nextEventId,
+    companyId: input.companyId,
+    type: input.type,
+    createdAt: new Date().toISOString(),
+    payload: input.payload ?? {},
+  };
+}
+
+export function publishLiveEvent(input: {
+  companyId: string;
+  type: LiveEventType;
+  payload?: LiveEventPayload;
+}) {
+  const event = toLiveEvent(input);
+  emitter.emit(input.companyId, event);
+  return event;
+}
+
+export function subscribeCompanyLiveEvents(companyId: string, listener: LiveEventListener) {
+  emitter.on(companyId, listener);
+  return () => emitter.off(companyId, listener);
+}

server/src/services/run-log-store.ts

@@ -0,0 +1,159 @@
+import { createReadStream, createWriteStream, promises as fs } from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { notFound } from "../errors.js";
+
+export type RunLogStoreType = "local_file";
+
+export interface RunLogHandle {
+  store: RunLogStoreType;
+  logRef: string;
+}
+
+export interface RunLogReadOptions {
+  offset?: number;
+  limitBytes?: number;
+}
+
+export interface RunLogReadResult {
+  content: string;
+  nextOffset?: number;
+}
+
+export interface RunLogFinalizeSummary {
+  bytes: number;
+  sha256?: string;
+  compressed: boolean;
+}
+
+export interface RunLogStore {
+  begin(input: { companyId: string; agentId: string; runId: string }): Promise<RunLogHandle>;
+  append(
+    handle: RunLogHandle,
+    event: { stream: "stdout" | "stderr" | "system"; chunk: string; ts: string },
+  ): Promise<void>;
+  finalize(handle: RunLogHandle): Promise<RunLogFinalizeSummary>;
+  read(handle: RunLogHandle, opts?: RunLogReadOptions): Promise<RunLogReadResult>;
+}
+
+function safeSegments(...segments: string[]) {
+  return segments.map((segment) => segment.replace(/[^a-zA-Z0-9._-]/g, "_"));
+}
+
+function resolveWithin(basePath: string, relativePath: string) {
+  const resolved = path.resolve(basePath, relativePath);
+  const base = path.resolve(basePath) + path.sep;
+  if (!resolved.startsWith(base) && resolved !== path.resolve(basePath)) {
+    throw new Error("Invalid log path");
+  }
+  return resolved;
+}
+
+function createLocalFileRunLogStore(basePath: string): RunLogStore {
+  async function ensureDir(relativeDir: string) {
+    const dir = resolveWithin(basePath, relativeDir);
+    await fs.mkdir(dir, { recursive: true });
+  }
+
+  async function readFileRange(filePath: string, offset: number, limitBytes: number): Promise<RunLogReadResult> {
+    const stat = await fs.stat(filePath).catch(() => null);
+    if (!stat) throw notFound("Run log not found");
+
+    const start = Math.max(0, Math.min(offset, stat.size));
+    const end = Math.max(start, Math.min(start + limitBytes - 1, stat.size - 1));
+
+    if (start > end) {
+      return { content: "", nextOffset: start };
+    }
+
+    const chunks: Buffer[] = [];
+    await new Promise<void>((resolve, reject) => {
+      const stream = createReadStream(filePath, { start, end });
+      stream.on("data", (chunk) => {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      });
+      stream.on("error", reject);
+      stream.on("end", () => resolve());
+    });
+
+    const content = Buffer.concat(chunks).toString("utf8");
+    const nextOffset = end + 1 < stat.size ? end + 1 : undefined;
+    return { content, nextOffset };
+  }
+
+  async function sha256File(filePath: string): Promise<string> {
+    return new Promise<string>((resolve, reject) => {
+      const hash = createHash("sha256");
+      const stream = createReadStream(filePath);
+      stream.on("data", (chunk) => hash.update(chunk));
+      stream.on("error", reject);
+      stream.on("end", () => resolve(hash.digest("hex")));
+    });
+  }
+
+  return {
+    async begin(input) {
+      const [companyId, agentId] = safeSegments(input.companyId, input.agentId);
+      const runId = safeSegments(input.runId)[0]!;
+      const relDir = path.join(companyId, agentId);
+      const relPath = path.join(relDir, `${runId}.ndjson`);
+      await ensureDir(relDir);
+
+      const absPath = resolveWithin(basePath, relPath);
+      await fs.writeFile(absPath, "", "utf8");
+
+      return { store: "local_file", logRef: relPath };
+    },
+
+    async append(handle, event) {
+      if (handle.store !== "local_file") return;
+      const absPath = resolveWithin(basePath, handle.logRef);
+      const line = JSON.stringify({
+        ts: event.ts,
+        stream: event.stream,
+        chunk: event.chunk,
+      });
+      await new Promise<void>((resolve, reject) => {
+        const stream = createWriteStream(absPath, { flags: "a", encoding: "utf8" });
+        stream.on("error", reject);
+        stream.end(`${line}\n`, () => resolve());
+      });
+    },
+
+    async finalize(handle) {
+      if (handle.store !== "local_file") {
+        return { bytes: 0, compressed: false };
+      }
+      const absPath = resolveWithin(basePath, handle.logRef);
+      const stat = await fs.stat(absPath).catch(() => null);
+      if (!stat) throw notFound("Run log not found");
+
+      const hash = await sha256File(absPath);
+      return {
+        bytes: stat.size,
+        sha256: hash,
+        compressed: false,
+      };
+    },
+
+    async read(handle, opts) {
+      if (handle.store !== "local_file") {
+        throw notFound("Run log not found");
+      }
+      const absPath = resolveWithin(basePath, handle.logRef);
+      const offset = opts?.offset ?? 0;
+      const limitBytes = opts?.limitBytes ?? 256_000;
+      return readFileRange(absPath, offset, limitBytes);
+    },
+  };
+}
+
+let cachedStore: RunLogStore | null = null;
+
+export function getRunLogStore() {
+  if (cachedStore) return cachedStore;
+  const basePath = process.env.RUN_LOG_BASE_PATH ?? path.resolve(process.cwd(), "data/run-logs");
+  cachedStore = createLocalFileRunLogStore(basePath);
+  return cachedStore;
+}
+