@replayio/app-building 1.2.0 → 1.4.0

package/README.md

@@ -33,14 +33,12 @@ const config: ContainerConfig = {
   flyApp: envVars.FLY_APP_NAME,
 };
 
-// Start a remote container
+// Start a detached container with an initial prompt — it will process and exit when done
+config.detached = true;
+config.initialPrompt = "Build the app";
 const repo: RepoOptions = { repoUrl: "https://github.com/...", cloneBranch: "main", pushBranch: "main" };
 const state = await startRemoteContainer(config, repo);
 
-// Send a prompt and wait for completion
-const httpOpts = httpOptsFor(state);
-const { id } = await httpPost(`${state.baseUrl}/message`, { prompt: "Build the app" }, httpOpts);
-
 // Check status
 const status = await httpGet(`${state.baseUrl}/status`, httpOpts);
 
@@ -57,7 +55,7 @@ await stopRemoteContainer(config, state);
 
 | Export | Description |
 |---|---|
-| `ContainerConfig` | Interface bundling all external state: optional `projectRoot` (only needed for local Docker operations), `envVars`, `registry`, optional `flyToken`/`flyApp`/`imageRef`/`webhookUrl`. See [Webhooks](#webhooks) below. |
+| `ContainerConfig` | Interface bundling all external state: optional `projectRoot` (only needed for local Docker operations), `envVars`, `registry`, optional `flyToken`/`flyApp`/`imageRef`/`webhookUrl`/`detached`/`initialPrompt`. See [Webhooks](#webhooks) and [Container lifecycle](#container-lifecycle) below. |
 | `RepoOptions` | Per-invocation git settings: `repoUrl`, `cloneBranch`, `pushBranch`. |
 | `ContainerRegistry` | Interface for container registry storage. Methods: `log`, `markStopped`, `clearStopped`, `getRecent`, `find`, `findAlive`. |
 | `FileContainerRegistry` | Built-in file-backed implementation of `ContainerRegistry`, backed by a `.jsonl` file. |
@@ -123,9 +121,42 @@ await stopRemoteContainer(config, state);
 |---|---|
 | `getImageRef()` | Returns `CONTAINER_IMAGE_REF` env var, or `ghcr.io/replayio/app-building:latest` by default. Used by `startRemoteContainer`. |
 
+## Container HTTP API
+
+Each container runs an HTTP server that accepts the following requests:
+
+| Method | Path | Description |
+|---|---|---|
+| `POST /message` | `{ prompt: string }` | Queue a message for processing. Returns `{ id }`. |
+| `GET /message/:id` | | Poll message status. Returns `{ id, status, result, error }`. |
+| `POST /detach` | | Signal the container to exit once all queued messages and tasks are done. |
+| `POST /stop` | | Force-stop the container immediately. Interrupts any running work, commits remaining changes, then exits. |
+| `POST /interrupt` | | Kill the currently running Claude process without stopping the container. |
+| `GET /status` | | Container state, queue depth, iteration count, cost, revision, etc. |
+| `GET /events?offset=N` | | Stream of Claude events (JSON lines) since offset. |
+| `GET /logs?offset=N` | | Stream of log lines since offset. |
+
+### Container lifecycle
+
+A container stays running and accepts messages until it receives a **detach** or **stop** signal:
+
+- **Detached at startup** (`config.detached = true`): Set `detached` on `ContainerConfig` to start
+  the container in detached mode. Use `config.initialPrompt` to provide a prompt that is queued
+  before the HTTP server starts accepting requests. The container processes the initial prompt
+  and any queued tasks, then exits cleanly. This is the preferred way to run fire-and-forget
+  jobs — no race between container startup and a subsequent `POST /message` or `POST /detach`.
+- **Detach** (`POST /detach`): Signal a running container to exit once all in-flight and queued
+  work is done. In the CLI, interactive mode (`npm run agent -- -i`) sends `/detach` automatically
+  when the user disconnects (Ctrl+C/D).
+- **Stop** (`POST /stop`): The container exits immediately, interrupting any running Claude
+  process. It commits any remaining work before shutting down. This is the forced shutdown path.
+
+Without either signal, the container waits indefinitely for new messages — this is intentional
+so that interactive users can send follow-up messages at any time.
+
 ## Webhooks
 
-Set `webhookUrl` on `ContainerConfig` to receive real-time notifications of container activity. The container POSTs fire-and-forget JSON to that URL on key events (no retries, failures are silently ignored).
+Set `webhookUrl` on `ContainerConfig` to receive real-time notifications of container activity. The container POSTs JSON to that URL on key events (no retries; failures are logged to stderr). If `WEBHOOK_SECRET` is set in the environment, the container sends it as a `Bearer` token in the `Authorization` header.
 
 ### Payload format
 

package/dist/container.d.ts

@@ -15,6 +15,10 @@ export interface ContainerConfig {
     flyApp?: string;
     imageRef?: string;
     webhookUrl?: string;
+    /** Start the container in detached mode. It will exit after processing all messages and tasks. */
+    detached?: boolean;
+    /** Initial prompt to queue at container startup (before the HTTP server accepts external requests). */
+    initialPrompt?: string;
 }
 export interface RepoOptions {
     repoUrl: string;

package/dist/container.js

@@ -100,6 +100,10 @@ export async function startContainer(config, repo) {
     };
     if (config.webhookUrl)
         extra.WEBHOOK_URL = config.webhookUrl;
+    if (config.detached)
+        extra.DETACHED = "1";
+    if (config.initialPrompt)
+        extra.INITIAL_PROMPT = config.initialPrompt;
     const containerEnv = buildContainerEnv(repo, config.envVars, extra);
     // Build docker run args
     const args = ["run", "-d", "--rm", "--name", containerName];
@@ -174,6 +178,10 @@ export async function startRemoteContainer(config, repo) {
     };
     if (config.webhookUrl)
         remoteExtra.WEBHOOK_URL = config.webhookUrl;
+    if (config.detached)
+        remoteExtra.DETACHED = "1";
+    if (config.initialPrompt)
+        remoteExtra.INITIAL_PROMPT = config.initialPrompt;
     const containerEnv = buildContainerEnv(repo, config.envVars, remoteExtra);
     // Log existing machines (but don't destroy — multiple containers may run concurrently)
     const existing = await listMachines(config.flyApp, config.flyToken);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@replayio/app-building",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Library for managing agentic app-building containers",
   "type": "module",
   "exports": {