@replayio/app-building 1.3.0 → 1.5.0

package/README.md

@@ -33,15 +33,12 @@ const config: ContainerConfig = {
   flyApp: envVars.FLY_APP_NAME,
 };
 
-// Start a remote container (detached — will exit after processing all work)
+// 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 — the container will process it and exit when done
-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);
 
@@ -58,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`/`detached`. See [Webhooks](#webhooks) and [Container lifecycle](#container-lifecycle) 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. |
@@ -144,9 +141,10 @@ Each container runs an HTTP server that accepts the following requests:
 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. The container processes its initial message 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 /detach`.
+  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).
@@ -185,14 +183,14 @@ Every POST body has this shape:
 | Type | When | `data` fields |
 |---|---|---|
 | `container.started` | HTTP server is listening | `pushBranch`, `revision` |
-| `container.idle` | State transitions to idle | `pendingTasks`, `queueLength` |
-| `container.processing` | State transitions to processing | `iteration` |
-| `container.stopping` | State transitions to stopping | _(empty)_ |
-| `container.stopped` | State transitions to stopped | _(empty)_ |
+| `container.idle` | Container is waiting for work | `pendingTasks`, `queueLength` |
+| `container.stopping` | Container is shutting down | _(empty)_ |
+| `container.stopped` | Container has stopped | _(empty)_ |
 | `message.queued` | `POST /message` received | `messageId`, `prompt` |
+| `message.started` | Message processing begins | `iteration`, `prompt` |
 | `message.done` | Message processing complete | `messageId`, `cost_usd`, `duration_ms`, `num_turns` |
 | `message.error` | Message processing failed | `messageId`, `error` |
-| `task.started` | Task processing begins | `pendingTasks` |
+| `task.started` | Task processing begins | `iteration`, `pendingTasks` |
 | `task.done` | Task processing complete | `tasksProcessed`, `totalCost` |
 | `log` | Each log line | `line` |
 

package/dist/container.d.ts

@@ -17,6 +17,8 @@ export interface ContainerConfig {
     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

@@ -4,6 +4,10 @@ import { resolve } from "path";
 import { createMachine, waitForMachine, destroyMachine, listMachines } from "./fly";
 import { getImageRef } from "./image-ref";
 const IMAGE_NAME = "app-building";
+function debugLog(...args) {
+    if (process.env.DEBUG)
+        console.log("[container]", ...args);
+}
 export function loadDotEnv(projectRoot) {
     const envPath = resolve(projectRoot, ".env");
     if (!existsSync(envPath)) {
@@ -90,6 +94,16 @@ function buildContainerEnv(repo, envVars, extra = {}) {
     return env;
 }
 export async function startContainer(config, repo) {
+    debugLog("startContainer config:", {
+        projectRoot: config.projectRoot,
+        flyApp: config.flyApp,
+        imageRef: config.imageRef,
+        webhookUrl: config.webhookUrl,
+        detached: config.detached,
+        initialPrompt: config.initialPrompt ? `${config.initialPrompt.slice(0, 100)}...` : undefined,
+        envVarKeys: Object.keys(config.envVars),
+    });
+    debugLog("startContainer repo:", repo);
     buildImage(config);
     const uniqueId = Math.random().toString(36).slice(2, 8);
     const containerName = `app-building-${uniqueId}`;
@@ -102,6 +116,8 @@ export async function startContainer(config, repo) {
         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];
@@ -162,6 +178,16 @@ export async function startContainer(config, repo) {
     return agentState;
 }
 export async function startRemoteContainer(config, repo) {
+    debugLog("startRemoteContainer config:", {
+        projectRoot: config.projectRoot,
+        flyApp: config.flyApp,
+        imageRef: config.imageRef,
+        webhookUrl: config.webhookUrl,
+        detached: config.detached,
+        initialPrompt: config.initialPrompt ? `${config.initialPrompt.slice(0, 100)}...` : undefined,
+        envVarKeys: Object.keys(config.envVars),
+    });
+    debugLog("startRemoteContainer repo:", repo);
     if (!config.flyToken)
         throw new Error("flyToken is required for remote containers");
     if (!config.flyApp)
@@ -178,6 +204,8 @@ export async function startRemoteContainer(config, repo) {
         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.3.0",
+  "version": "1.5.0",
   "description": "Library for managing agentic app-building containers",
   "type": "module",
   "exports": {