replicas-engine 0.1.440 → 0.1.442

package/dist/src/index.js

@@ -27,6 +27,21 @@ async function raceWithTimeout(promise, ms) {
   }
 }
 
+// ../shared/src/result.ts
+function createSuccessResult(data) {
+  return { ok: true, data };
+}
+function createErrorResult(error) {
+  return {
+    ok: false,
+    error: {
+      message: error.message,
+      code: error.code,
+      details: error.details
+    }
+  };
+}
+
 // ../shared/src/agent.ts
 var VALID_AGENT_PROVIDERS = ["claude", "codex", "cursor", "opencode", "relay"];
 var VALID_CODING_AGENT_PROVIDERS = VALID_AGENT_PROVIDERS.filter(
@@ -506,7 +521,7 @@ var WORKSPACE_SIZES = ["small", "large"];
 var INVALID_WORKSPACE_SIZE_ERROR = `Invalid size: must be one of ${WORKSPACE_SIZES.join(", ")}`;
 
 // ../shared/src/e2b.ts
-var E2B_TEMPLATE_NAME = "replicas-sandbox-2026-07-15-v5";
+var E2B_TEMPLATE_NAME = "replicas-sandbox-2026-07-16-v2";
 
 // ../shared/src/runtime-env.ts
 function shellQuotePosix(value) {
@@ -1968,24 +1983,18 @@ When you run services on ports \u2014 such as a web app, API server, or database
 
 ## Running Services for Preview
 
-Services must run as detached background processes so they survive after your command session ends. Do not leave them attached to a foreground terminal.
+Always start services with \`replicas service start\` (see \`REPLICAS.md\`, "Long-running services"). It daemonizes the process so it survives your turn ending and workspace sleep/wake \u2014 a service left attached to your shell or backgrounded with \`&\`/\`nohup\` dies when the workspace sleeps, leaving the preview broken for the user.
 
-Some potential methods:
 \`\`\`bash
-# Start a detached service with logging
-setsid -f bash -lc 'cd /path/to/app && exec yarn dev >> /tmp/app.log 2>&1'
-
-# For daemons like Docker
-nohup dockerd > /tmp/dockerd.log 2>&1 &
+replicas service start web "yarn dev" --cwd /path/to/app
 \`\`\`
 
 After starting a service:
-1. Verify the process is running: \`pgrep -af 'yarn dev'\`
-2. Check logs for readiness: \`tail -f /tmp/app.log\`
-3. Confirm it's actually serving: \`curl -s http://localhost:3000\` (or appropriate health check)
-4. Only create the preview after the service is healthy
+1. Check logs for readiness: \`replicas service logs web\`
+2. Confirm it's actually serving: \`curl -s http://localhost:3000\` (or appropriate health check)
+3. Only create the preview after the service is healthy
 
-If a prior detached process exists on the same port, stop it before restarting.
+\`replicas service start\` on the same name restarts the service, so you never need to hunt down stale processes on the port.
 
 ## Creating Previews
 
@@ -2058,7 +2067,8 @@ Use this when:
 - The user asks you to create, edit, run, or delete an automation
 - The user asks you to manage environments, environment variables, or environment files
 - The user asks "what envs / repos / automations do I have?"
-- The user asks you to scaffold a \`replicas.json\` / \`replicas.yaml\` in a repo`;
+- The user asks you to scaffold a \`replicas.json\` / \`replicas.yaml\` in a repo
+- You need to run a long-lived service (dev server, daemon) \u2014 always use \`replicas service start\` so it survives workspace sleep/wake`;
 var REFERENCE10 = `# Replicas (in-workspace CLI)
 
 This guide covers how to take action *with* Replicas itself from inside a Replicas workspace \u2014 managing automations, environments (and their variables/files), repos, previews, and the user's \`replicas.json\` config \u2014 using the pre-installed \`replicas\` CLI.
@@ -2094,6 +2104,7 @@ In agent mode the CLI hides commands that don't make sense for in-workspace agen
 | \`replicas environment ...\` | Manage environments, env vars, env files |
 | \`replicas automation ...\` | Manage automations (cron + GitHub/GitLab event triggers) |
 | \`replicas preview ...\` | Register / list preview URLs (covered in \`PREVIEWS.md\`) |
+| \`replicas service ...\` | Run long-lived services detached so they survive workspace sleep/wake (see below) |
 | \`replicas media ...\` | Upload screenshots, videos, audio (covered in \`MEDIA.md\`) |
 | \`replicas slack thread ...\` | Attach or switch Slack thread routing (covered in \`SLACK.md\`) |
 
@@ -2235,6 +2246,24 @@ replicas automation edit <id> \\
 
 \`replicas automation edit <id>\` with no flags drops into interactive mode.
 
+## Long-running services
+
+**Always use \`replicas service start\` to run anything that should keep running after your current command or turn ends** \u2014 dev servers, backend APIs, databases, daemons, watchers. Never leave them attached to your shell, and never rely on plain \`&\`, \`nohup\`, or your own backgrounding: processes started inside your session are torn down when your turn ends and the workspace goes to sleep, so the user finds them dead after waking the workspace. \`replicas service start\` daemonizes the process into its own session, which survives workspace sleep/wake.
+
+\`\`\`bash
+replicas service start <name> "<command>"        # start (or restart) a named service
+replicas service start web "bun run dev" --cwd ~/workspaces/app
+replicas service list                            # names, pids, running/stopped
+replicas service logs <name> [-n 100]            # tail the service log
+replicas service stop <name>                     # stop the whole process group
+\`\`\`
+
+Notes:
+- Quote the command if it contains shell operators: \`replicas service start web "cd app && bun dev"\`.
+- \`start\` on an existing name restarts it (the old process group is stopped first). It fails fast and prints the log tail if the service dies within the first second.
+- Logs stream to \`~/.replicas/services/<name>.log\`.
+- After starting, verify the service is actually healthy (check \`logs\`, then \`curl\` its port) before telling the user it's up or creating a preview for it.
+
 ## Repositories
 
 Read-only listing of repos connected to the org. Use when the user asks "what repos can I use?", or to validate a \`--repository\` value before passing it to \`environment create\` / \`automation create\`:
@@ -3317,7 +3346,7 @@ var MEDIA_KINDS = [MEDIA_KIND.IMAGE, MEDIA_KIND.VIDEO, MEDIA_KIND.AUDIO];
 var SKILL_REGISTRY_MANIFEST_VERSION = 1;
 
 // src/index.ts
-import { randomUUID as randomUUID6 } from "crypto";
+import { randomUUID as randomUUID7 } from "crypto";
 import { connect } from "net";
 
 // src/utils/exec.ts
@@ -8563,7 +8592,7 @@ var DEFAULT_CODEX_ARGS = ["app-server", "--listen", "stdio://"];
 var MIN_CODEX_CLI_VERSION = "0.144.0";
 var CODEX_UPGRADE_TIMEOUT_MS = 12e4;
 var codexCliVersionEnsured = null;
-var ENGINE_PACKAGE_VERSION = "0.1.440";
+var ENGINE_PACKAGE_VERSION = "0.1.442";
 var INITIALIZE_METHOD = "initialize";
 var INITIALIZED_NOTIFICATION = "initialized";
 var ACCOUNT_LOGIN_START_METHOD = "account/login/start";
@@ -14127,6 +14156,98 @@ ${combinedScript}` : combinedScript;
   return result;
 }
 
+// src/services/terminal-service.ts
+import { randomUUID as randomUUID6 } from "crypto";
+import { existsSync as existsSync9 } from "fs";
+import { spawn as spawn5 } from "node-pty";
+var MAX_REPLAY_CHARS = 1024 * 1024;
+var MAX_TERMINAL_SESSIONS = 8;
+var TerminalService = class {
+  sessions = /* @__PURE__ */ new Map();
+  nextTitleNumber = 1;
+  list() {
+    return [...this.sessions.values()].map(({ pty: _pty, replay: _replay, subscribers: _subscribers, ...session }) => session);
+  }
+  create(cwd, cols, rows) {
+    if (this.sessions.size >= MAX_TERMINAL_SESSIONS) {
+      return createErrorResult({
+        message: `Terminal session limit reached (${MAX_TERMINAL_SESSIONS})`,
+        code: "limit"
+      });
+    }
+    const id = randomUUID6();
+    const shell = process.env.SHELL && existsSync9(process.env.SHELL) ? process.env.SHELL : "/bin/bash";
+    const pty = spawn5(shell, ["-l"], {
+      name: "xterm-256color",
+      cols,
+      rows,
+      cwd,
+      env: {
+        ...process.env,
+        TERM: "xterm-256color",
+        COLORTERM: "truecolor"
+      }
+    });
+    const session = {
+      id,
+      title: `Terminal ${this.nextTitleNumber++}`,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      exited: false,
+      pty,
+      replay: "",
+      subscribers: /* @__PURE__ */ new Set()
+    };
+    this.sessions.set(id, session);
+    pty.onData((data) => {
+      session.replay = (session.replay + data).slice(-MAX_REPLAY_CHARS);
+      for (const subscriber of session.subscribers) subscriber(data);
+    });
+    pty.onExit(({ exitCode }) => {
+      session.exited = true;
+      session.exitCode = exitCode;
+      const data = `\r
+\x1B[2m[Process exited with code ${exitCode}]\x1B[0m\r
+`;
+      session.replay = (session.replay + data).slice(-MAX_REPLAY_CHARS);
+      for (const subscriber of session.subscribers) subscriber(data);
+    });
+    return createSuccessResult(this.publicSession(session));
+  }
+  write(id, data) {
+    const session = this.sessions.get(id);
+    if (!session || session.exited) return false;
+    session.pty.write(data);
+    return true;
+  }
+  resize(id, cols, rows) {
+    const session = this.sessions.get(id);
+    if (!session || session.exited) return false;
+    session.pty.resize(cols, rows);
+    return true;
+  }
+  subscribe(id, subscriber) {
+    const session = this.sessions.get(id);
+    if (!session) return null;
+    session.subscribers.add(subscriber);
+    return {
+      replay: session.replay,
+      unsubscribe: () => session.subscribers.delete(subscriber)
+    };
+  }
+  delete(id) {
+    const session = this.sessions.get(id);
+    if (!session) return false;
+    if (!session.exited) session.pty.kill();
+    this.sessions.delete(id);
+    return true;
+  }
+  publicSession(session) {
+    const { pty: _pty, replay: _replay, subscribers: _subscribers, ...value } = session;
+    return value;
+  }
+};
+var terminalService = new TerminalService();
+
 // src/v1-routes.ts
 var setWorkspaceNameSchema = z2.object({
   name: z2.string().min(1).max(48)
@@ -14142,6 +14263,13 @@ var createPreviewSchema = z2.object({
   port: z2.number().int().min(1).max(65535),
   publicUrl: z2.string().min(1)
 });
+var terminalSizeSchema = z2.object({
+  cols: z2.number().int().min(2).max(500),
+  rows: z2.number().int().min(1).max(200)
+});
+var writeTerminalSessionSchema = z2.object({
+  data: z2.string().max(64 * 1024)
+});
 var sendMessageSchema = z2.object({
   message: z2.string().min(1),
   model: z2.string().optional(),
@@ -14515,6 +14643,78 @@ function createV1Routes(deps) {
     }
     return c.json(result);
   });
+  app2.get("/terminal/sessions", (c) => {
+    return c.json({ sessions: terminalService.list() });
+  });
+  app2.post("/terminal/sessions", async (c) => {
+    const size = terminalSizeSchema.parse(await c.req.json());
+    const result = terminalService.create(gitService.getWorkspaceRoot(), size.cols, size.rows);
+    if (!result.ok) return c.json(jsonError(result.error.message), 429);
+    return c.json({
+      session: result.data
+    }, 201);
+  });
+  app2.post("/terminal/sessions/:id/input", async (c) => {
+    const body = writeTerminalSessionSchema.parse(await c.req.json());
+    if (!terminalService.write(c.req.param("id"), body.data)) {
+      return c.json(jsonError("Terminal session not found or exited"), 404);
+    }
+    return c.body(null, 204);
+  });
+  app2.post("/terminal/sessions/:id/resize", async (c) => {
+    const size = terminalSizeSchema.parse(await c.req.json());
+    if (!terminalService.resize(c.req.param("id"), size.cols, size.rows)) {
+      return c.json(jsonError("Terminal session not found or exited"), 404);
+    }
+    return c.body(null, 204);
+  });
+  app2.delete("/terminal/sessions/:id", (c) => {
+    if (!terminalService.delete(c.req.param("id"))) {
+      return c.json(jsonError("Terminal session not found"), 404);
+    }
+    return c.body(null, 204);
+  });
+  app2.get("/terminal/sessions/:id/stream", (c) => {
+    const encoder = new TextEncoder();
+    let cleanup = () => {
+    };
+    const stream = new ReadableStream({
+      start(controller) {
+        const subscription = terminalService.subscribe(c.req.param("id"), (data) => {
+          controller.enqueue(encoder.encode(`data: ${JSON.stringify(data)}
+
+`));
+        });
+        if (!subscription) {
+          controller.enqueue(encoder.encode(`event: error
+data: ${JSON.stringify("Terminal session not found")}
+
+`));
+          controller.close();
+          return;
+        }
+        if (subscription.replay) controller.enqueue(encoder.encode(`data: ${JSON.stringify(subscription.replay)}
+
+`));
+        const heartbeat = setInterval(() => controller.enqueue(encoder.encode(": keepalive\n\n")), 15e3);
+        cleanup = () => {
+          clearInterval(heartbeat);
+          subscription.unsubscribe();
+        };
+      },
+      cancel() {
+        cleanup();
+      }
+    });
+    c.req.raw.signal.addEventListener("abort", cleanup, { once: true });
+    return new Response(stream, {
+      headers: {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive"
+      }
+    });
+  });
   app2.get("/canvas", async (c) => {
     try {
       const items = await canvasService.listItems();
@@ -15125,7 +15325,7 @@ function startStatusBroadcaster() {
       if (serialized !== previousRepoStatus) {
         previousRepoStatus = serialized;
         eventService.publish({
-          id: randomUUID6(),
+          id: randomUUID7(),
           ts: (/* @__PURE__ */ new Date()).toISOString(),
           type: "repo.status.changed",
           payload: { repos }
@@ -15146,7 +15346,7 @@ function startStatusBroadcaster() {
       if (engineStatusJson !== previousEngineStatus) {
         previousEngineStatus = engineStatusJson;
         eventService.publish({
-          id: randomUUID6(),
+          id: randomUUID7(),
           ts: (/* @__PURE__ */ new Date()).toISOString(),
           type: "engine.status.changed",
           payload: { status: engineStatus }
@@ -15165,7 +15365,7 @@ function startStatusBroadcaster() {
         previousHookStatus = hookSnapshot;
         if (!lastHooksRunning && hooksRunning) {
           eventService.publish({
-            id: randomUUID6(),
+            id: randomUUID7(),
             ts: (/* @__PURE__ */ new Date()).toISOString(),
             type: "hooks.started",
             payload: { running: true, completed: false }
@@ -15174,7 +15374,7 @@ function startStatusBroadcaster() {
         }
         if (hooksRunning) {
           eventService.publish({
-            id: randomUUID6(),
+            id: randomUUID7(),
             ts: (/* @__PURE__ */ new Date()).toISOString(),
             type: "hooks.progress",
             payload: { running: true, completed: false }
@@ -15183,7 +15383,7 @@ function startStatusBroadcaster() {
         }
         if (lastHooksRunning && !hooksRunning && hooksCompleted && !hooksFailed) {
           eventService.publish({
-            id: randomUUID6(),
+            id: randomUUID7(),
             ts: (/* @__PURE__ */ new Date()).toISOString(),
             type: "hooks.completed",
             payload: { running: false, completed: true }
@@ -15192,7 +15392,7 @@ function startStatusBroadcaster() {
         }
         if (lastHooksRunning && !hooksRunning && hooksFailed) {
           eventService.publish({
-            id: randomUUID6(),
+            id: randomUUID7(),
             ts: (/* @__PURE__ */ new Date()).toISOString(),
             type: "hooks.failed",
             payload: { running: false, completed: hooksCompleted }
@@ -15200,7 +15400,7 @@ function startStatusBroadcaster() {
           });
         }
         eventService.publish({
-          id: randomUUID6(),
+          id: randomUUID7(),
           ts: (/* @__PURE__ */ new Date()).toISOString(),
           type: "hooks.status",
           payload: {
@@ -15252,20 +15452,20 @@ serve(
     }
     const repos = await gitService.listRepos();
     await eventService.publish({
-      id: randomUUID6(),
+      id: randomUUID7(),
       ts: (/* @__PURE__ */ new Date()).toISOString(),
       type: "repo.discovered",
       payload: { repos }
     });
     const repoStatuses = await gitService.listRepos();
     await eventService.publish({
-      id: randomUUID6(),
+      id: randomUUID7(),
       ts: (/* @__PURE__ */ new Date()).toISOString(),
       type: "repo.status.changed",
       payload: { repos: repoStatuses }
     });
     await eventService.publish({
-      id: randomUUID6(),
+      id: randomUUID7(),
       ts: (/* @__PURE__ */ new Date()).toISOString(),
       type: "engine.ready",
       payload: { version: "v1" }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replicas-engine",
-  "version": "0.1.440",
+  "version": "0.1.442",
   "description": "Lightweight API server for Replicas workspaces",
   "type": "module",
   "main": "dist/src/index.js",
@@ -43,6 +43,9 @@
     "yaml": "^2.8.2",
     "zod": "^4.0.0"
   },
+  "optionalDependencies": {
+    "node-pty": "1.2.0-beta.14"
+  },
   "devDependencies": {
     "@replicas/codex-asp-types": "file:../codex-asp-types",
     "@replicas/shared": "workspace:*",