@cospacehq/server 0.1.0

package/src/server.ts

@@ -0,0 +1,1548 @@
+import fs from "node:fs/promises";
+import crypto from "node:crypto";
+import path from "node:path";
+import { URL } from "node:url";
+import Fastify from "fastify";
+import cors from "@fastify/cors";
+import { WebSocketServer } from "ws";
+import {
+  AgentCreateInputSchema,
+  AgentBindingUpdateInputSchema,
+  BootstrapPayloadSchema,
+  ClientMessageInputSchema,
+  FileDeleteInputSchema,
+  FileListInputSchema,
+  FileMkdirInputSchema,
+  FileRenameInputSchema,
+  FileReadInputSchema,
+  FileWriteInputSchema,
+  ProjectAgentAssignmentInputSchema,
+  ProjectCreateInputSchema,
+  ProviderConnectionTestInputSchema,
+  TaskCreateInputSchema,
+  TaskStatusUpdateInputSchema,
+  ProviderUpsertInputSchema,
+  type CoSpaceConfig,
+  type ProviderConfig,
+  type Task,
+  type TaskEvent,
+  type TaskApprovalStatus,
+  type TaskActionType,
+  type TaskActionPayload
+} from "@cospacehq/shared";
+import { AgentRuntime, type ServerEvent } from "./agent-runtime.js";
+import { resolveConfig, type ResolvedConfig } from "./config.js";
+import { CoSpaceStore, type ProviderRecord } from "./db.js";
+import { OpenAICompatibleModelClient, type ProviderRuntimeConfig } from "./model-client.js";
+import {
+  decryptProviderSecret,
+  encryptProviderSecret,
+  encryptionSecretFromToken
+} from "./provider-crypto.js";
+import { listSandboxFiles, resolveSandboxPath } from "./sandbox.js";
+
+export type StartServerOptions = {
+  config: CoSpaceConfig;
+  configPath: string;
+  webDistPath?: string;
+  host?: string;
+};
+
+export type StartedServer = {
+  localUrl: string;
+  resolvedConfig: ResolvedConfig;
+  stop: () => Promise<void>;
+};
+
+function readTokenFromRequest(urlPath: string): string | null {
+  const parsed = new URL(urlPath, "http://127.0.0.1");
+  return parsed.searchParams.get("token");
+}
+
+function readPasscodeFromRequest(urlPath: string): string | null {
+  const parsed = new URL(urlPath, "http://127.0.0.1");
+  return parsed.searchParams.get("passcode");
+}
+
+function passcodeHashFromRaw(rawPasscode: string): string {
+  return crypto.createHash("sha256").update(rawPasscode, "utf8").digest("hex");
+}
+
+function eventEnvelope(event: ServerEvent): string {
+  return JSON.stringify(event);
+}
+
+function maybeWebDist(webDistPath: string | undefined): string | null {
+  if (!webDistPath) {
+    return null;
+  }
+  return path.resolve(webDistPath);
+}
+
+function mimeTypeForStaticFile(filePath: string): string | null {
+  switch (path.extname(filePath).toLowerCase()) {
+    case ".css":
+      return "text/css; charset=utf-8";
+    case ".html":
+      return "text/html; charset=utf-8";
+    case ".js":
+    case ".mjs":
+      return "text/javascript; charset=utf-8";
+    case ".json":
+    case ".map":
+      return "application/json; charset=utf-8";
+    case ".ico":
+      return "image/x-icon";
+    case ".jpeg":
+    case ".jpg":
+      return "image/jpeg";
+    case ".png":
+      return "image/png";
+    case ".svg":
+      return "image/svg+xml";
+    case ".txt":
+      return "text/plain; charset=utf-8";
+    case ".woff":
+      return "font/woff";
+    case ".woff2":
+      return "font/woff2";
+    default:
+      return null;
+  }
+}
+
+function sanitizeProviderKey(rawValue: string): string {
+  const trimmed = rawValue.trim();
+  if (!/^[a-zA-Z0-9._-]{2,64}$/.test(trimmed)) {
+    throw new Error("Provider key must be 2-64 chars and contain only letters, numbers, ., _, -");
+  }
+  return trimmed;
+}
+
+function mapProviderRecordToPublic(record: ProviderRecord): ProviderConfig {
+  return {
+    id: record.id,
+    providerKey: record.providerKey,
+    label: record.label,
+    kind: record.kind,
+    baseUrl: record.baseUrl,
+    defaultModel: record.defaultModel,
+    hasApiKey: Boolean(record.encryptedApiKey),
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt
+  };
+}
+
+function toProviderRuntimeConfig(
+  record: ProviderRecord,
+  encryptionSecret: string,
+  overrideApiKey?: string,
+  overrideBaseUrl?: string,
+  overrideKind?: ProviderRecord["kind"]
+): ProviderRuntimeConfig {
+  const apiKey = overrideApiKey ?? (record.encryptedApiKey ? decryptProviderSecret(record.encryptedApiKey, encryptionSecret) : null);
+
+  if (!apiKey) {
+    throw new Error(`Provider ${record.providerKey} does not have an API key configured`);
+  }
+
+  return {
+    providerKey: record.providerKey,
+    label: record.label,
+    kind: overrideKind ?? record.kind,
+    baseUrl: overrideBaseUrl ?? record.baseUrl,
+    apiKey
+  };
+}
+
+export async function startCoSpaceServer(options: StartServerOptions): Promise<StartedServer> {
+  const resolvedConfig = resolveConfig(options.config, options.configPath);
+
+  await fs.mkdir(resolvedConfig.workspaceRoot, { recursive: true });
+  await fs.mkdir(resolvedConfig.dataDir, { recursive: true });
+
+  const app = Fastify({ logger: true });
+  await app.register(cors, { origin: true });
+
+  const store = new CoSpaceStore(path.join(resolvedConfig.dataDir, "cospace.db"), {
+    projectName: resolvedConfig.projectName
+  });
+
+  let sessionToken = resolvedConfig.auth.token;
+  let sessionPasscodeHash = resolvedConfig.auth.passcodeHash ?? null;
+
+  const sockets = new Set<WebSocket>();
+  const wss = new WebSocketServer({ noServer: true });
+
+  const emit = (event: ServerEvent): void => {
+    const payload = eventEnvelope(event);
+
+    for (const socket of sockets) {
+      if (socket.readyState === socket.OPEN) {
+        socket.send(payload);
+      }
+    }
+  };
+
+  const emitTaskUpdated = (task: Task): void => {
+    emit({ type: "task.updated", data: task });
+  };
+
+  const emitTaskEvent = (event: TaskEvent): void => {
+    emit({ type: "task.event", data: event });
+  };
+
+  const recordAndEmitTaskEvent = (input: {
+    taskId: string;
+    projectId: string;
+    eventType: TaskEvent["eventType"];
+    actorId: string;
+    detail: string | null;
+  }): void => {
+    const event = store.recordTaskEvent(input);
+    emitTaskEvent(event);
+  };
+
+  const emitTaskMessage = (task: Task, body: string, trace: string): void => {
+    const assignee = task.assigneeAgentId ? store.getAgentById(task.assigneeAgentId) : null;
+    const senderId = assignee?.id ?? "task-system";
+    const senderName = assignee ? `${assignee.name} (${assignee.title})` : "Task System";
+    const internalTrace = assignee?.traceEnabled ? trace : null;
+
+    const message = store.createAgentMessage({
+      projectId: task.projectId,
+      senderId,
+      senderName,
+      body,
+      internalTrace
+    });
+
+    emit({ type: "message.created", data: message });
+
+    if (assignee?.seenEnabled) {
+      store.createSeenReceipt({
+        messageId: message.id,
+        agentId: assignee.id,
+        agentName: assignee.name,
+        model: assignee.model
+      });
+      emit({
+        type: "seen.updated",
+        data: {
+          messageId: message.id,
+          receipts: store.listReceiptsForMessage(message.id)
+        }
+      });
+    }
+  };
+
+  const taskActorId = (task: Task): string => task.assigneeAgentId ?? "task-system";
+
+  const taskPathFromPayload = (task: Task): string | null => {
+    const raw = task.actionPayload?.path?.trim() ?? null;
+    return raw && raw.length > 0 ? raw : null;
+  };
+
+  const normalizePolicyPath = (value: string | null): string | null => {
+    if (!value) {
+      return null;
+    }
+    return value.replace(/^\/+/g, "");
+  };
+
+  const policyPrefixMatch = (targetPath: string | null, prefixes: string[]): boolean => {
+    const normalized = normalizePolicyPath(targetPath);
+    if (!normalized) {
+      return false;
+    }
+    return prefixes.some((prefix) => normalized.startsWith(prefix));
+  };
+
+  const resolveApprovalPolicy = (task: Task): { approvalStatus: TaskApprovalStatus; reason: string } => {
+    const actionType = task.actionType;
+    const pathValue = taskPathFromPayload(task);
+    const assignee = task.assigneeAgentId ? store.getAgentById(task.assigneeAgentId) : null;
+    const assigneeTitle = assignee?.title.toLowerCase() ?? "";
+
+    if (actionType === "none") {
+      return { approvalStatus: "not_required", reason: "Non-file task auto-executes." };
+    }
+
+    if (actionType === "file_delete" || actionType === "file_rename") {
+      return { approvalStatus: "pending", reason: "High-risk file action always requires approval." };
+    }
+
+    const backendTrusted =
+      assigneeTitle.includes("backend") &&
+      policyPrefixMatch(pathValue, ["trusted/backend/", "automation/backend/"]);
+    const uiTrusted =
+      (assigneeTitle.includes("ui") || assigneeTitle.includes("design")) &&
+      policyPrefixMatch(pathValue, ["trusted/ui/", "automation/ui/"]);
+
+    if (backendTrusted || uiTrusted) {
+      return {
+        approvalStatus: "approved",
+        reason: "Trusted agent and trusted path matched auto-approval policy."
+      };
+    }
+
+    return { approvalStatus: "pending", reason: "Task requires manual approval by default policy." };
+  };
+
+  const executeTaskAction = async (task: Task): Promise<string> => {
+    const payload: TaskActionPayload = task.actionPayload ?? {};
+
+    switch (task.actionType) {
+      case "none":
+        return "No file action requested.";
+      case "file_write": {
+        const filePath = payload.path?.trim();
+        if (!filePath) {
+          throw new Error("Task payload missing path for file_write");
+        }
+        const content = payload.content ?? "";
+
+        try {
+          const absolutePath = resolveSandboxPath(resolvedConfig.workspaceRoot, filePath);
+          await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+          await fs.writeFile(absolutePath, content, "utf8");
+          store.recordFileAction({
+            actorId: taskActorId(task),
+            action: "write",
+            targetPath: filePath,
+            status: "ok",
+            errorMessage: null
+          });
+          return `Wrote /${filePath}`;
+        } catch (error) {
+          const message = error instanceof Error ? error.message : "Unknown write error";
+          store.recordFileAction({
+            actorId: taskActorId(task),
+            action: "write",
+            targetPath: filePath,
+            status: "error",
+            errorMessage: message
+          });
+          throw error;
+        }
+      }
+      case "file_mkdir": {
+        const directoryPath = payload.path?.trim();
+        if (!directoryPath) {
+          throw new Error("Task payload missing path for file_mkdir");
+        }
+
+        try {
+          const absolutePath = resolveSandboxPath(resolvedConfig.workspaceRoot, directoryPath);
+          await fs.mkdir(absolutePath, { recursive: true });
+          store.recordFileAction({
+            actorId: taskActorId(task),
+            action: "mkdir",
+            targetPath: directoryPath,
+            status: "ok",
+            errorMessage: null
+          });
+          return `Created folder /${directoryPath}`;
+        } catch (error) {
+          const message = error instanceof Error ? error.message : "Unknown mkdir error";
+          store.recordFileAction({
+            actorId: taskActorId(task),
+            action: "mkdir",
+            targetPath: directoryPath,
+            status: "error",
+            errorMessage: message
+          });
+          throw error;
+        }
+      }
+      case "file_rename": {
+        const currentPath = payload.path?.trim();
+        const nextPath = payload.nextPath?.trim();
+        if (!currentPath || !nextPath) {
+          throw new Error("Task payload missing path/nextPath for file_rename");
+        }
+        if (currentPath === "." || nextPath === ".") {
+          throw new Error("Cannot rename workspace root");
+        }
+
+        try {
+          const fromPath = resolveSandboxPath(resolvedConfig.workspaceRoot, currentPath);
+          const toPath = resolveSandboxPath(resolvedConfig.workspaceRoot, nextPath);
+          try {
+            await fs.access(toPath);
+            throw new Error(`Destination already exists: ${nextPath}`);
+          } catch (accessError) {
+            const code = (accessError as NodeJS.ErrnoException).code;
+            if (code !== "ENOENT") {
+              throw accessError;
+            }
+          }
+          await fs.mkdir(path.dirname(toPath), { recursive: true });
+          await fs.rename(fromPath, toPath);
+          store.recordFileAction({
+            actorId: taskActorId(task),
+            action: "rename",
+            targetPath: `${currentPath} -> ${nextPath}`,
+            status: "ok",
+            errorMessage: null
+          });
+          return `Renamed /${currentPath} to /${nextPath}`;
+        } catch (error) {
+          const message = error instanceof Error ? error.message : "Unknown rename error";
+          store.recordFileAction({
+            actorId: taskActorId(task),
+            action: "rename",
+            targetPath: `${currentPath} -> ${nextPath}`,
+            status: "error",
+            errorMessage: message
+          });
+          throw error;
+        }
+      }
+      case "file_delete": {
+        const targetPath = payload.path?.trim();
+        if (!targetPath) {
+          throw new Error("Task payload missing path for file_delete");
+        }
+        if (targetPath === ".") {
+          throw new Error("Cannot delete workspace root");
+        }
+
+        try {
+          const absolutePath = resolveSandboxPath(resolvedConfig.workspaceRoot, targetPath);
+          const stats = await fs.lstat(absolutePath);
+          if (stats.isDirectory()) {
+            await fs.rm(absolutePath, { recursive: true, force: false });
+          } else {
+            await fs.unlink(absolutePath);
+          }
+          store.recordFileAction({
+            actorId: taskActorId(task),
+            action: "delete",
+            targetPath,
+            status: "ok",
+            errorMessage: null
+          });
+          return `Deleted /${targetPath}`;
+        } catch (error) {
+          const message = error instanceof Error ? error.message : "Unknown delete error";
+          store.recordFileAction({
+            actorId: taskActorId(task),
+            action: "delete",
+            targetPath,
+            status: "error",
+            errorMessage: message
+          });
+          throw error;
+        }
+      }
+      default:
+        throw new Error(`Unsupported task action type: ${task.actionType}`);
+    }
+  };
+
+  const executeTask = async (
+    task: Task,
+    approvalStatusOverride?: TaskApprovalStatus,
+    actorId = "task-system"
+  ): Promise<{ task: Task; error: string | null }> => {
+    const approvalStatus = approvalStatusOverride ?? task.approvalStatus;
+
+    const inProgress = store.updateTaskState({
+      taskId: task.id,
+      status: "in_progress",
+      approvalStatus,
+      errorMessage: null,
+      completedAt: null
+    });
+    emitTaskUpdated(inProgress);
+    recordAndEmitTaskEvent({
+      taskId: inProgress.id,
+      projectId: inProgress.projectId,
+      eventType: "execution_started",
+      actorId,
+      detail: `Execution started (${approvalStatus.replace(/_/g, " ")}).`
+    });
+
+    try {
+      const resultSummary = await executeTaskAction(inProgress);
+      const completed = store.updateTaskState({
+        taskId: task.id,
+        status: "done",
+        approvalStatus,
+        errorMessage: null
+      });
+      emitTaskUpdated(completed);
+      recordAndEmitTaskEvent({
+        taskId: completed.id,
+        projectId: completed.projectId,
+        eventType: "execution_succeeded",
+        actorId,
+        detail: resultSummary
+      });
+      emitTaskMessage(
+        completed,
+        `Task completed: ${completed.title}. ${resultSummary}`,
+        `Approval: ${approvalStatus.replace(/_/g, " ")}\nAction: ${completed.actionType}\nResult: ${resultSummary}`
+      );
+      return { task: completed, error: null };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const blocked = store.updateTaskState({
+        taskId: task.id,
+        status: "blocked",
+        approvalStatus,
+        errorMessage: message,
+        completedAt: null
+      });
+      emitTaskUpdated(blocked);
+      recordAndEmitTaskEvent({
+        taskId: blocked.id,
+        projectId: blocked.projectId,
+        eventType: "execution_failed",
+        actorId,
+        detail: message
+      });
+      emitTaskMessage(
+        blocked,
+        `Task failed: ${blocked.title}. ${message}`,
+        `Approval: ${approvalStatus.replace(/_/g, " ")}\nAction: ${blocked.actionType}\nFailure: ${message}`
+      );
+      return { task: blocked, error: message };
+    }
+  };
+
+  const encryptionSecret = encryptionSecretFromToken(
+    resolvedConfig.auth.encryptionSecret ?? resolvedConfig.auth.token
+  );
+  const modelClient = new OpenAICompatibleModelClient();
+
+  const buildBootstrapPayload = (preferredProjectId?: string) => {
+    const projects = store.listProjectThreads();
+
+    if (projects.length === 0) {
+      throw new Error("No projects available");
+    }
+
+    const selectedThread = preferredProjectId
+      ? projects.find((projectThread) => projectThread.id === preferredProjectId) ?? projects[0]
+      : projects[0];
+
+    const activeProject = store.getProjectById(selectedThread.id);
+    if (!activeProject) {
+      throw new Error(`Project ${selectedThread.id} not found`);
+    }
+
+    return BootstrapPayloadSchema.parse({
+      project: activeProject,
+      projects,
+      projectAgentIds: store.listProjectAgentIds(activeProject.id),
+      projectAgentIdsByProject: store.listProjectAgentIdsByProject(),
+      agents: store.listAgents(),
+      providers: store.listProviderRecords().map(mapProviderRecordToPublic),
+      messages: store.listMessages(activeProject.id),
+      receiptsByMessage: store.listReceiptsByProject(activeProject.id),
+      tasks: store.listTasksByProject(activeProject.id),
+      taskEventsByTask: store.listTaskEventsByProject(activeProject.id)
+    });
+  };
+
+  const runtime = new AgentRuntime(
+    store,
+    emit,
+    async ({ agent, latestMessages }) => {
+      if (!agent.providerKey) {
+        return {
+          body: "I need a configured provider before I can generate real model responses. Set one in Integrations.",
+          trace: "Provider missing\nAction: open Settings > Integrations and bind a provider to this agent.",
+          model: agent.model
+        };
+      }
+
+      const providerRecord = store.getProviderRecord(agent.providerKey);
+      if (!providerRecord) {
+        return {
+          body: `My assigned provider '${agent.providerKey}' is missing. Please reconfigure agent routing.`,
+          trace: `Provider lookup failed for key: ${agent.providerKey}`,
+          model: agent.model
+        };
+      }
+
+      const provider = toProviderRuntimeConfig(providerRecord, encryptionSecret);
+
+      const generated = await modelClient.generateAgentReply({
+        provider,
+        model: agent.model,
+        agentName: agent.name,
+        agentTitle: agent.title,
+        agentInstruction: agent.systemPrompt,
+        latestMessages,
+        includeTrace: agent.traceEnabled
+      });
+
+      return {
+        body: generated.body,
+        trace: generated.trace,
+        model: agent.model
+      };
+    },
+    async (delegatedTask) => {
+      const latestTask = store.getTaskById(delegatedTask.id);
+      if (!latestTask) {
+        return;
+      }
+
+      const policy = resolveApprovalPolicy(latestTask);
+      let policyTask = latestTask;
+      if (policy.approvalStatus !== latestTask.approvalStatus) {
+        policyTask = store.updateTaskState({
+          taskId: latestTask.id,
+          approvalStatus: policy.approvalStatus,
+          errorMessage: null
+        });
+        emitTaskUpdated(policyTask);
+      }
+
+      recordAndEmitTaskEvent({
+        taskId: policyTask.id,
+        projectId: policyTask.projectId,
+        eventType: "policy_applied",
+        actorId: "policy-engine",
+        detail: policy.reason
+      });
+
+      if (policyTask.approvalStatus === "pending") {
+        return;
+      }
+
+      await executeTask(policyTask, policyTask.approvalStatus, "policy-engine");
+    }
+  );
+
+  const persistAuthConfig = async (): Promise<void> => {
+    const raw = await fs.readFile(options.configPath, "utf8");
+    const parsed = JSON.parse(raw) as CoSpaceConfig;
+    parsed.auth = {
+      ...parsed.auth,
+      token: sessionToken,
+      passcodeHash: sessionPasscodeHash ?? undefined
+    };
+    await fs.writeFile(options.configPath, `${JSON.stringify(parsed, null, 2)}\n`, "utf8");
+  };
+
+  app.addHook("onRequest", async (request, reply) => {
+    if (!request.url.startsWith("/api")) {
+      return;
+    }
+
+    const token = request.headers["x-cospace-token"];
+    if (typeof token !== "string" || token !== sessionToken) {
+      reply.code(401).send({ error: "Unauthorized" });
+      return;
+    }
+
+    const allowWithoutPasscode = request.url.startsWith("/api/session/challenge");
+    if (sessionPasscodeHash && !allowWithoutPasscode) {
+      const provided = request.headers["x-cospace-passcode"];
+      if (typeof provided !== "string" || passcodeHashFromRaw(provided) !== sessionPasscodeHash) {
+        reply.code(401).send({ error: "Passcode required" });
+        return;
+      }
+    }
+  });
+
+  app.get("/api/session/challenge", async () => {
+    return {
+      passcodeRequired: Boolean(sessionPasscodeHash),
+      warning: sessionPasscodeHash
+        ? "Passcode required for API and WebSocket access."
+        : "Passcode not configured. Recommended when using public tunnel."
+    };
+  });
+
+  app.post("/api/session/passcode", async (request, reply) => {
+    const body = request.body as { passcode?: string | null };
+    const provided = typeof body?.passcode === "string" ? body.passcode.trim() : "";
+
+    if (provided.length > 0 && provided.length < 6) {
+      reply.code(400);
+      return { error: "Passcode must be at least 6 characters" };
+    }
+
+    sessionPasscodeHash = provided.length > 0 ? passcodeHashFromRaw(provided) : null;
+    await persistAuthConfig();
+
+    for (const socket of sockets) {
+      socket.close();
+    }
+
+    return {
+      ok: true,
+      passcodeRequired: Boolean(sessionPasscodeHash)
+    };
+  });
+
+  app.post("/api/session/rotate-token", async () => {
+    sessionToken = crypto.randomBytes(18).toString("hex");
+    await persistAuthConfig();
+
+    for (const socket of sockets) {
+      socket.close();
+    }
+
+    const host = options.host ?? "127.0.0.1";
+    const base = `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${resolvedConfig.port}`;
+    return {
+      ok: true,
+      token: sessionToken,
+      localUrl: `${base}?token=${encodeURIComponent(sessionToken)}`
+    };
+  });
+
+  app.get("/api/bootstrap", async (request, reply) => {
+    const query = request.query as { projectId?: string };
+
+    if (query.projectId && !store.getProjectById(query.projectId)) {
+      reply.code(404);
+      return { error: `Project ${query.projectId} not found` };
+    }
+
+    return buildBootstrapPayload(query.projectId);
+  });
+
+  app.get("/api/projects", async () => {
+    return { projects: store.listProjectThreads() };
+  });
+
+  app.post("/api/projects", async (request, reply) => {
+    const parsed = ProjectCreateInputSchema.parse(request.body);
+    const project = store.createProject({ name: parsed.name });
+    reply.code(201);
+    return {
+      project,
+      projects: store.listProjectThreads()
+    };
+  });
+
+  app.put("/api/projects/:projectId/agents", async (request, reply) => {
+    const params = request.params as { projectId: string };
+    const parsed = ProjectAgentAssignmentInputSchema.parse(request.body);
+    const project = store.getProjectById(params.projectId);
+
+    if (!project) {
+      reply.code(404);
+      return { error: `Project ${params.projectId} not found` };
+    }
+
+    const knownAgentIds = new Set(store.listAgents().map((agent) => agent.id));
+    const unknownAgentId = parsed.agentIds.find((agentId) => !knownAgentIds.has(agentId));
+
+    if (unknownAgentId) {
+      reply.code(400);
+      return { error: `Unknown agent id: ${unknownAgentId}` };
+    }
+
+    const projectAgentIds = store.setProjectAgentIds(project.id, parsed.agentIds);
+    return {
+      projectAgentIds,
+      projects: store.listProjectThreads(),
+      projectAgentIdsByProject: store.listProjectAgentIdsByProject()
+    };
+  });
+
+  app.get("/api/projects/:projectId/tasks", async (request, reply) => {
+    const params = request.params as { projectId: string };
+    const project = store.getProjectById(params.projectId);
+    if (!project) {
+      reply.code(404);
+      return { error: `Project ${params.projectId} not found` };
+    }
+
+    return { tasks: store.listTasksByProject(project.id) };
+  });
+
+  app.get("/api/projects/:projectId/task-events", async (request, reply) => {
+    const params = request.params as { projectId: string };
+    const project = store.getProjectById(params.projectId);
+    if (!project) {
+      reply.code(404);
+      return { error: `Project ${params.projectId} not found` };
+    }
+
+    return { taskEventsByTask: store.listTaskEventsByProject(project.id) };
+  });
+
+  app.post("/api/projects/:projectId/tasks", async (request, reply) => {
+    const params = request.params as { projectId: string };
+    const parsed = TaskCreateInputSchema.parse(request.body);
+    const project = store.getProjectById(params.projectId);
+
+    if (!project) {
+      reply.code(404);
+      return { error: `Project ${params.projectId} not found` };
+    }
+
+    const assigneeAgentId = parsed.assigneeAgentId?.trim() ?? null;
+    if (assigneeAgentId) {
+      const assigneeAgent = store.getAgentById(assigneeAgentId);
+      if (!assigneeAgent) {
+        reply.code(400);
+        return { error: `Unknown assignee agent ${assigneeAgentId}` };
+      }
+    }
+
+    const requestedApprovalStatus =
+      parsed.approvalStatus ?? (parsed.actionType === "none" ? "not_required" : "pending");
+    let task = store.createTask({
+      projectId: project.id,
+      title: parsed.title,
+      description: parsed.description?.trim() || null,
+      status: "queued",
+      approvalStatus: requestedApprovalStatus,
+      actionType: parsed.actionType,
+      actionPayload: parsed.actionPayload ?? null,
+      assigneeAgentId,
+      delegatedByMessageId: null,
+      createdBy: "web-user"
+    });
+
+    emitTaskUpdated(task);
+    recordAndEmitTaskEvent({
+      taskId: task.id,
+      projectId: task.projectId,
+      eventType: "created",
+      actorId: "web-user",
+      detail: "Task created from web panel."
+    });
+    const policy = resolveApprovalPolicy(task);
+    if (policy.approvalStatus !== task.approvalStatus) {
+      task = store.updateTaskState({
+        taskId: task.id,
+        approvalStatus: policy.approvalStatus,
+        errorMessage: null
+      });
+      emitTaskUpdated(task);
+    }
+    recordAndEmitTaskEvent({
+      taskId: task.id,
+      projectId: task.projectId,
+      eventType: "policy_applied",
+      actorId: "policy-engine",
+      detail: policy.reason
+    });
+
+    if (task.approvalStatus !== "pending") {
+      const execution = await executeTask(task, task.approvalStatus, "web-user");
+      task = execution.task;
+    }
+
+    reply.code(201);
+    return { task };
+  });
+
+  app.post("/api/tasks/:taskId/approve", async (request, reply) => {
+    const params = request.params as { taskId: string };
+    const task = store.getTaskById(params.taskId);
+    if (!task) {
+      reply.code(404);
+      return { error: `Task ${params.taskId} not found` };
+    }
+
+    if (task.approvalStatus !== "pending") {
+      reply.code(400);
+      return { error: `Task ${params.taskId} is not awaiting approval` };
+    }
+
+    recordAndEmitTaskEvent({
+      taskId: task.id,
+      projectId: task.projectId,
+      eventType: "approved",
+      actorId: "web-user",
+      detail: "Task approved by user."
+    });
+
+    const result = await executeTask(task, "approved", "web-user");
+    if (result.error) {
+      reply.code(500);
+      return { error: result.error, task: result.task };
+    }
+    return { task: result.task };
+  });
+
+  app.post("/api/tasks/:taskId/retry", async (request, reply) => {
+    const params = request.params as { taskId: string };
+    const task = store.getTaskById(params.taskId);
+    if (!task) {
+      reply.code(404);
+      return { error: `Task ${params.taskId} not found` };
+    }
+
+    if (task.status === "in_progress") {
+      reply.code(409);
+      return { error: `Task ${params.taskId} is currently running` };
+    }
+
+    if (task.status === "done") {
+      reply.code(400);
+      return { error: `Task ${params.taskId} is already completed` };
+    }
+
+    if (task.status !== "blocked" && task.status !== "cancelled") {
+      reply.code(400);
+      return { error: `Task ${params.taskId} cannot be retried from status ${task.status}` };
+    }
+
+    const nextApprovalStatus: TaskApprovalStatus =
+      task.actionType === "none"
+        ? "not_required"
+        : task.approvalStatus === "rejected"
+          ? "pending"
+          : task.approvalStatus;
+
+    const retried = store.updateTaskState({
+      taskId: task.id,
+      status: "queued",
+      approvalStatus: nextApprovalStatus,
+      errorMessage: null,
+      completedAt: null
+    });
+    emitTaskUpdated(retried);
+    recordAndEmitTaskEvent({
+      taskId: retried.id,
+      projectId: retried.projectId,
+      eventType: "retry_requested",
+      actorId: "web-user",
+      detail: "Retry requested by user."
+    });
+
+    if (retried.approvalStatus === "pending") {
+      emitTaskMessage(
+        retried,
+        `Task retried: ${retried.title}. Awaiting approval in the Tasks panel.`,
+        `Approval: pending\nAction: ${retried.actionType}\nReason: retry requested`
+      );
+      return { task: retried };
+    }
+
+    const result = await executeTask(retried, nextApprovalStatus, "web-user");
+    if (result.error) {
+      reply.code(500);
+      return { error: result.error, task: result.task };
+    }
+    return { task: result.task };
+  });
+
+  app.post("/api/tasks/:taskId/cancel", async (request, reply) => {
+    const params = request.params as { taskId: string };
+    const task = store.getTaskById(params.taskId);
+    if (!task) {
+      reply.code(404);
+      return { error: `Task ${params.taskId} not found` };
+    }
+
+    if (task.status === "done" || task.status === "cancelled") {
+      reply.code(400);
+      return { error: `Task ${params.taskId} cannot be cancelled from status ${task.status}` };
+    }
+
+    if (task.status === "in_progress") {
+      reply.code(409);
+      return { error: `Task ${params.taskId} is currently running` };
+    }
+
+    const cancelled = store.updateTaskState({
+      taskId: task.id,
+      status: "cancelled",
+      approvalStatus: task.approvalStatus === "pending" ? "rejected" : task.approvalStatus,
+      errorMessage: "Cancelled by user"
+    });
+    emitTaskUpdated(cancelled);
+    recordAndEmitTaskEvent({
+      taskId: cancelled.id,
+      projectId: cancelled.projectId,
+      eventType: "cancelled",
+      actorId: "web-user",
+      detail: "Task cancelled by user."
+    });
+    emitTaskMessage(
+      cancelled,
+      `Task cancelled: ${cancelled.title}.`,
+      `Approval: ${cancelled.approvalStatus.replace(/_/g, " ")}\nAction: ${cancelled.actionType}\nReason: cancelled by user`
+    );
+    return { task: cancelled };
+  });
+
+  app.post("/api/tasks/:taskId/reject", async (request, reply) => {
+    const params = request.params as { taskId: string };
+    const task = store.getTaskById(params.taskId);
+    if (!task) {
+      reply.code(404);
+      return { error: `Task ${params.taskId} not found` };
+    }
+
+    if (task.approvalStatus !== "pending") {
+      reply.code(400);
+      return { error: `Task ${params.taskId} is not awaiting approval` };
+    }
+
+    const blocked = store.updateTaskState({
+      taskId: task.id,
+      status: "blocked",
+      approvalStatus: "rejected",
+      errorMessage: "Rejected by user",
+      completedAt: null
+    });
+    emitTaskUpdated(blocked);
+    recordAndEmitTaskEvent({
+      taskId: blocked.id,
+      projectId: blocked.projectId,
+      eventType: "rejected",
+      actorId: "web-user",
+      detail: "Task rejected by user."
+    });
+    emitTaskMessage(
+      blocked,
+      `Task rejected: ${blocked.title}. Waiting for an updated instruction.`,
+      `Approval: rejected\nAction: ${blocked.actionType}\nReason: user rejected task`
+    );
+    return { task: blocked };
+  });
+
+  app.post("/api/tasks/:taskId/status", async (request, reply) => {
+    const params = request.params as { taskId: string };
+    const parsed = TaskStatusUpdateInputSchema.parse(request.body);
+    const task = store.getTaskById(params.taskId);
+    if (!task) {
+      reply.code(404);
+      return { error: `Task ${params.taskId} not found` };
+    }
+
+    const updated = store.updateTaskState({
+      taskId: task.id,
+      status: parsed.status,
+      completedAt: parsed.status === "done" || parsed.status === "cancelled" ? undefined : null
+    });
+    emitTaskUpdated(updated);
+    recordAndEmitTaskEvent({
+      taskId: updated.id,
+      projectId: updated.projectId,
+      eventType: "status_changed",
+      actorId: "web-user",
+      detail: `Status changed to ${updated.status}.`
+    });
+    return { task: updated };
+  });
+
+  app.get("/api/providers", async () => {
+    return { providers: store.listProviderRecords().map(mapProviderRecordToPublic) };
+  });
+
+  app.put("/api/providers/:providerKey", async (request, reply) => {
+    const params = request.params as { providerKey: string };
+    const parsed = ProviderUpsertInputSchema.parse(request.body);
+
+    let providerKey: string;
+    try {
+      providerKey = sanitizeProviderKey(params.providerKey);
+    } catch (error) {
+      reply.code(400);
+      return { error: error instanceof Error ? error.message : String(error) };
+    }
+
+    const encryptedApiKey = parsed.clearApiKey
+      ? null
+      : parsed.apiKey
+        ? encryptProviderSecret(parsed.apiKey, encryptionSecret)
+        : undefined;
+
+    const updated = store.upsertProviderRecord({
+      providerKey,
+      label: parsed.label,
+      kind: parsed.kind,
+      baseUrl: parsed.baseUrl,
+      defaultModel: parsed.defaultModel,
+      encryptedApiKey
+    });
+
+    return { provider: mapProviderRecordToPublic(updated) };
+  });
+
+  app.post("/api/providers/test", async (request, reply) => {
+    const parsed = ProviderConnectionTestInputSchema.parse(request.body);
+
+    let provider: ProviderRuntimeConfig;
+
+    if (parsed.providerKey) {
+      const providerKey = sanitizeProviderKey(parsed.providerKey);
+      const record = store.getProviderRecord(providerKey);
+      if (!record) {
+        reply.code(404);
+        return { ok: false, error: `Provider ${providerKey} not found` };
+      }
+
+      try {
+        provider = toProviderRuntimeConfig(
+          record,
+          encryptionSecret,
+          parsed.apiKey,
+          parsed.baseUrl,
+          parsed.kind
+        );
+      } catch (error) {
+        reply.code(400);
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    } else {
+      provider = {
+        providerKey: "adhoc",
+        label: "Ad hoc",
+        kind: parsed.kind,
+        baseUrl: parsed.baseUrl as string,
+        apiKey: parsed.apiKey as string
+      };
+    }
+
+    const startedAt = Date.now();
+    try {
+      const result = await modelClient.testConnection({
+        provider,
+        model: parsed.model
+      });
+
+      return {
+        ok: true,
+        latencyMs: Date.now() - startedAt,
+        preview: result.preview
+      };
+    } catch (error) {
+      reply.code(502);
+      return {
+        ok: false,
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  });
+
+  app.get("/api/agents", async () => {
+    return { agents: store.listAgents() };
+  });
+
+  app.post("/api/agents", async (request, reply) => {
+    const parsed = AgentCreateInputSchema.parse(request.body);
+
+    const providerKey = parsed.providerKey ?? null;
+    if (providerKey) {
+      const provider = store.getProviderRecord(providerKey);
+      if (!provider) {
+        reply.code(400);
+        return { error: `Provider ${providerKey} is not configured` };
+      }
+    }
+
+    const projectId = parsed.projectId?.trim();
+    if (projectId) {
+      const project = store.getProjectById(projectId);
+      if (!project) {
+        reply.code(404);
+        return { error: `Project ${projectId} not found` };
+      }
+    }
+
+    const agent = store.createAgent({
+      name: parsed.name,
+      title: parsed.title,
+      model: parsed.model,
+      providerKey,
+      systemPrompt: parsed.systemPrompt ?? null,
+      seenEnabled: parsed.seenEnabled,
+      traceEnabled: parsed.traceEnabled,
+      projectId
+    });
+
+    reply.code(201);
+    return {
+      agent,
+      agents: store.listAgents(),
+      projects: store.listProjectThreads(),
+      projectAgentIdsByProject: store.listProjectAgentIdsByProject(),
+      projectAgentIds: projectId ? store.listProjectAgentIds(projectId) : undefined
+    };
+  });
+
+  app.put("/api/agents/:agentId/config", async (request, reply) => {
+    const params = request.params as { agentId: string };
+    const parsed = AgentBindingUpdateInputSchema.parse(request.body);
+
+    const existingAgent = store.listAgents().find((agent) => agent.id === params.agentId);
+    if (!existingAgent) {
+      reply.code(404);
+      return { error: `Agent ${params.agentId} not found` };
+    }
+
+    const providerKey = parsed.providerKey ?? null;
+    const model = parsed.model ?? null;
+    const seenEnabled = parsed.seenEnabled ?? existingAgent.seenEnabled;
+    const traceEnabled = parsed.traceEnabled ?? existingAgent.traceEnabled;
+
+    if (providerKey) {
+      const configuredProvider = store.getProviderRecord(providerKey);
+      if (!configuredProvider) {
+        reply.code(400);
+        return { error: `Provider ${providerKey} is not configured` };
+      }
+    }
+
+    store.setAgentBinding({
+      agentId: params.agentId,
+      providerKey,
+      model
+    });
+    store.setAgentVisibility({
+      agentId: params.agentId,
+      seenEnabled,
+      traceEnabled
+    });
+
+    const updatedAgent = store.listAgents().find((agent) => agent.id === params.agentId);
+    if (!updatedAgent) {
+      reply.code(500);
+      return { error: "Agent update failed" };
+    }
+
+    return { agent: updatedAgent };
+  });
+
+  app.post("/api/projects/:projectId/messages", async (request, reply) => {
+    const params = request.params as { projectId: string };
+    const parsedBody = ClientMessageInputSchema.parse(request.body);
+    const project = store.getProjectById(params.projectId);
+
+    if (!project) {
+      reply.code(404);
+      return { error: `Project ${params.projectId} not found` };
+    }
+
+    const message = store.createHumanMessage({
+      projectId: params.projectId,
+      body: parsedBody.body,
+      senderName: parsedBody.senderName
+    });
+
+    const agents = store.listAgentsForProject(params.projectId);
+    for (const agent of agents) {
+      if (!agent.seenEnabled) {
+        continue;
+      }
+      store.createSeenReceipt({
+        messageId: message.id,
+        agentId: agent.id,
+        agentName: agent.name,
+        model: agent.model
+      });
+    }
+
+    emit({ type: "message.created", data: message });
+    emit({
+      type: "seen.updated",
+      data: {
+        messageId: message.id,
+        receipts: store.listReceiptsForMessage(message.id)
+      }
+    });
+
+    void runtime.reactToHumanMessage(message);
+
+    reply.code(201);
+    return { message };
+  });
+
+  app.post("/api/files/read", async (request) => {
+    const input = FileReadInputSchema.parse(request.body);
+    const actorId = input.actorId ?? "manual";
+
+    try {
+      const absolutePath = resolveSandboxPath(resolvedConfig.workspaceRoot, input.path);
+      const content = await fs.readFile(absolutePath, "utf8");
+      store.recordFileAction({
+        actorId,
+        action: "read",
+        targetPath: input.path,
+        status: "ok",
+        errorMessage: null
+      });
+      return { path: input.path, content };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown read error";
+      store.recordFileAction({
+        actorId,
+        action: "read",
+        targetPath: input.path,
+        status: "error",
+        errorMessage: message
+      });
+      throw error;
+    }
+  });
+
+  app.post("/api/files/write", async (request) => {
+    const input = FileWriteInputSchema.parse(request.body);
+    const actorId = input.actorId ?? "manual";
+
+    try {
+      const absolutePath = resolveSandboxPath(resolvedConfig.workspaceRoot, input.path);
+      await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+      await fs.writeFile(absolutePath, input.content, "utf8");
+      store.recordFileAction({
+        actorId,
+        action: "write",
+        targetPath: input.path,
+        status: "ok",
+        errorMessage: null
+      });
+      return { ok: true };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown write error";
+      store.recordFileAction({
+        actorId,
+        action: "write",
+        targetPath: input.path,
+        status: "error",
+        errorMessage: message
+      });
+      throw error;
+    }
+  });
+
+  app.post("/api/files/mkdir", async (request) => {
+    const input = FileMkdirInputSchema.parse(request.body);
+    const actorId = input.actorId ?? "manual";
+
+    try {
+      const absolutePath = resolveSandboxPath(resolvedConfig.workspaceRoot, input.path);
+      await fs.mkdir(absolutePath, { recursive: true });
+      store.recordFileAction({
+        actorId,
+        action: "mkdir",
+        targetPath: input.path,
+        status: "ok",
+        errorMessage: null
+      });
+      return { ok: true, path: input.path };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown mkdir error";
+      store.recordFileAction({
+        actorId,
+        action: "mkdir",
+        targetPath: input.path,
+        status: "error",
+        errorMessage: message
+      });
+      throw error;
+    }
+  });
+
+  app.post("/api/files/rename", async (request) => {
+    const input = FileRenameInputSchema.parse(request.body);
+    const actorId = input.actorId ?? "manual";
+
+    if (input.path === "." || input.nextPath === ".") {
+      throw new Error("Cannot rename the workspace root");
+    }
+
+    try {
+      const fromPath = resolveSandboxPath(resolvedConfig.workspaceRoot, input.path);
+      const toPath = resolveSandboxPath(resolvedConfig.workspaceRoot, input.nextPath);
+      try {
+        await fs.access(toPath);
+        throw new Error(`Destination already exists: ${input.nextPath}`);
+      } catch (accessError) {
+        const code = (accessError as NodeJS.ErrnoException).code;
+        if (code !== "ENOENT") {
+          throw accessError;
+        }
+      }
+      await fs.mkdir(path.dirname(toPath), { recursive: true });
+      await fs.rename(fromPath, toPath);
+      store.recordFileAction({
+        actorId,
+        action: "rename",
+        targetPath: `${input.path} -> ${input.nextPath}`,
+        status: "ok",
+        errorMessage: null
+      });
+      return { ok: true, path: input.path, nextPath: input.nextPath };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown rename error";
+      store.recordFileAction({
+        actorId,
+        action: "rename",
+        targetPath: `${input.path} -> ${input.nextPath}`,
+        status: "error",
+        errorMessage: message
+      });
+      throw error;
+    }
+  });
+
+  app.post("/api/files/delete", async (request) => {
+    const input = FileDeleteInputSchema.parse(request.body);
+    const actorId = input.actorId ?? "manual";
+
+    if (input.path === ".") {
+      throw new Error("Cannot delete the workspace root");
+    }
+
+    try {
+      const absolutePath = resolveSandboxPath(resolvedConfig.workspaceRoot, input.path);
+      const stats = await fs.lstat(absolutePath);
+      if (stats.isDirectory()) {
+        await fs.rm(absolutePath, { recursive: true, force: false });
+      } else {
+        await fs.unlink(absolutePath);
+      }
+
+      store.recordFileAction({
+        actorId,
+        action: "delete",
+        targetPath: input.path,
+        status: "ok",
+        errorMessage: null
+      });
+      return { ok: true, path: input.path };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown delete error";
+      store.recordFileAction({
+        actorId,
+        action: "delete",
+        targetPath: input.path,
+        status: "error",
+        errorMessage: message
+      });
+      throw error;
+    }
+  });
+
+  app.post("/api/files/list", async (request) => {
+    const input = FileListInputSchema.parse(request.body);
+    const actorId = input.actorId ?? "manual";
+
+    try {
+      const files = await listSandboxFiles(resolvedConfig.workspaceRoot, input.path);
+      store.recordFileAction({
+        actorId,
+        action: "list",
+        targetPath: input.path,
+        status: "ok",
+        errorMessage: null
+      });
+      return { files };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown list error";
+      store.recordFileAction({
+        actorId,
+        action: "list",
+        targetPath: input.path,
+        status: "error",
+        errorMessage: message
+      });
+      throw error;
+    }
+  });
+
+  const webDistRoot = maybeWebDist(options.webDistPath);
+  if (webDistRoot) {
+    app.get("/", async (_, reply) => {
+      try {
+        const html = await fs.readFile(path.join(webDistRoot, "index.html"), "utf8");
+        reply.type("text/html").send(html);
+      } catch {
+        reply
+          .type("text/html")
+          .send(
+            "<h1>CoSpace is running</h1><p>Web bundle missing. Build apps/web and restart. Example: <code>pnpm --filter @cospacehq/web build</code>.</p>"
+          );
+      }
+    });
+
+    app.get("/*", async (request, reply) => {
+      const requested = (request.params as { "*": string })["*"];
+      const staticPath = path.resolve(webDistRoot, requested);
+      const inDist = staticPath.startsWith(webDistRoot);
+
+      if (inDist) {
+        try {
+          const buffer = await fs.readFile(staticPath);
+          const mimeType = mimeTypeForStaticFile(staticPath);
+          if (mimeType) {
+            reply.type(mimeType);
+          }
+          return reply.send(buffer);
+        } catch {
+          if (path.extname(requested)) {
+            reply.code(404);
+            return { error: "Asset not found" };
+          }
+          const html = await fs.readFile(path.join(webDistRoot, "index.html"), "utf8");
+          reply.type("text/html").send(html);
+          return;
+        }
+      }
+
+      reply.code(404).send({ error: "Not found" });
+    });
+  }
+
+  app.server.on("upgrade", (request, socket, head) => {
+    const token = readTokenFromRequest(request.url ?? "");
+    const passcode = readPasscodeFromRequest(request.url ?? "");
+
+    if (token !== sessionToken) {
+      socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+
+    if (sessionPasscodeHash && (!passcode || passcodeHashFromRaw(passcode) !== sessionPasscodeHash)) {
+      socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+
+    wss.handleUpgrade(request, socket, head, (ws) => {
+      wss.emit("connection", ws);
+    });
+  });
+
+  wss.on("connection", (socket) => {
+    sockets.add(socket as unknown as WebSocket);
+
+    socket.send(
+      JSON.stringify({
+        type: "bootstrap",
+        data: buildBootstrapPayload()
+      })
+    );
+
+    socket.on("close", () => {
+      sockets.delete(socket as unknown as WebSocket);
+    });
+  });
+
+  const host = options.host ?? "127.0.0.1";
+  await app.listen({ port: resolvedConfig.port, host });
+
+  const localUrl = `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${resolvedConfig.port}`;
+
+  return {
+    localUrl,
+    resolvedConfig,
+    stop: async () => {
+      for (const socket of sockets) {
+        socket.close();
+      }
+      wss.close();
+      store.close();
+      await app.close();
+    }
+  };
+}