@replayio/app-building 1.0.3 → 1.1.0

package/README.md

@@ -13,10 +13,9 @@ npm install @replayio/app-building
 ```ts
 import {
   loadDotEnv,
-  ContainerRegistry,
+  FileContainerRegistry,
   type ContainerConfig,
   type RepoOptions,
-  startContainer,
   startRemoteContainer,
   stopRemoteContainer,
   httpGet,
@@ -27,9 +26,9 @@ import {
 // Assemble config once at startup
 const envVars = loadDotEnv("/path/to/project");
 const config: ContainerConfig = {
-  projectRoot: "/path/to/project",
+  projectRoot: "/path/to/project",  // optional — only needed for local Docker operations
   envVars,
-  registry: new ContainerRegistry("/path/to/.container-registry.jsonl"),
+  registry: new FileContainerRegistry("/path/to/.container-registry.jsonl"),
   flyToken: envVars.FLY_API_TOKEN,
   flyApp: envVars.FLY_APP_NAME,
 };
@@ -58,9 +57,10 @@ await stopRemoteContainer(config, state);
 
 | Export | Description |
 |---|---|
-| `ContainerConfig` | Interface bundling all external state: `projectRoot`, `envVars`, `registry`, optional `flyToken`/`flyApp`/`imageRef`. |
+| `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. |
 | `RepoOptions` | Per-invocation git settings: `repoUrl`, `cloneBranch`, `pushBranch`. |
-| `ContainerRegistry` | Class encapsulating `.container-registry.jsonl` persistence. Methods: `log`, `markStopped`, `clearStopped`, `getRecent`, `find`, `findAlive`. |
+| `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. |
 
 ### Container lifecycle
 
@@ -76,7 +76,7 @@ await stopRemoteContainer(config, state);
 
 **Types:** `AgentState`, `ContainerConfig`, `RepoOptions`
 
-### Container registry (`ContainerRegistry` class)
+### Container registry (`ContainerRegistry` interface / `FileContainerRegistry` class)
 
 | Method | Description |
 |---|---|
@@ -122,3 +122,54 @@ await stopRemoteContainer(config, state);
 | Export | Description |
 |---|---|
 | `getImageRef()` | Returns `CONTAINER_IMAGE_REF` env var, or `ghcr.io/replayio/app-building:latest` by default. Used by `startRemoteContainer`. |
+
+## 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).
+
+### Payload format
+
+Every POST body has this shape:
+
+```json
+{
+  "type": "container.started",
+  "containerName": "app-building-abc123",
+  "timestamp": "2026-02-28T12:00:00.000Z",
+  "data": { ... }
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `type` | `string` | Event type (see table below). |
+| `containerName` | `string` | Name of the container that emitted the event. |
+| `timestamp` | `string` | ISO-8601 timestamp. |
+| `data` | `object` | Event-specific payload. Present on all events; contents vary by type. |
+
+### Events
+
+| 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)_ |
+| `message.queued` | `POST /message` received | `messageId`, `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.done` | Task processing complete | `tasksProcessed`, `totalCost` |
+| `log` | Each log line | `line` |
+
+### Example
+
+```ts
+const config: ContainerConfig = {
+  projectRoot: "/path/to/project",
+  envVars: loadDotEnv("/path/to/project"),
+  registry: new FileContainerRegistry("/path/to/.container-registry.jsonl"),
+  webhookUrl: "https://example.com/hooks/container-events",
+};
+```

package/dist/container-registry.d.ts

@@ -3,7 +3,15 @@ export interface RegistryEntry extends AgentState {
     startedAt: string;
     stoppedAt?: string;
 }
-export declare class ContainerRegistry {
+export interface ContainerRegistry {
+    log(state: AgentState): void;
+    markStopped(containerName?: string): void;
+    clearStopped(containerName: string): void;
+    getRecent(limit?: number): RegistryEntry[];
+    find(containerName: string): RegistryEntry | null;
+    findAlive(): Promise<RegistryEntry[]>;
+}
+export declare class FileContainerRegistry implements ContainerRegistry {
     private filePath;
     constructor(filePath: string);
     private readRegistry;

package/dist/container-registry.js

@@ -1,6 +1,6 @@
 import { readFileSync, writeFileSync, appendFileSync, existsSync } from "fs";
 import { probeAlive } from "./container-utils";
-export class ContainerRegistry {
+export class FileContainerRegistry {
     filePath;
     constructor(filePath) {
         this.filePath = filePath;

package/dist/container.d.ts

@@ -8,12 +8,13 @@ export interface AgentState {
     flyMachineId?: string;
 }
 export interface ContainerConfig {
-    projectRoot: string;
+    projectRoot?: string;
     envVars: Record<string, string>;
     registry: ContainerRegistry;
     flyToken?: string;
     flyApp?: string;
     imageRef?: string;
+    webhookUrl?: string;
 }
 export interface RepoOptions {
     repoUrl: string;

package/dist/container.js

@@ -28,6 +28,8 @@ export function loadDotEnv(projectRoot) {
     return vars;
 }
 export function buildImage(config) {
+    if (!config.projectRoot)
+        throw new Error("projectRoot is required for local Docker operations");
     console.log("Building Docker image...");
     execFileSync("docker", ["build", "--network", "host", "-t", IMAGE_NAME, config.projectRoot], {
         stdio: "inherit",
@@ -92,10 +94,13 @@ export async function startContainer(config, repo) {
     const uniqueId = Math.random().toString(36).slice(2, 8);
     const containerName = `app-building-${uniqueId}`;
     const hostPort = findFreePort();
-    const containerEnv = buildContainerEnv(repo, config.envVars, {
+    const extra = {
         PORT: String(hostPort),
         CONTAINER_NAME: containerName,
-    });
+    };
+    if (config.webhookUrl)
+        extra.WEBHOOK_URL = config.webhookUrl;
+    const containerEnv = buildContainerEnv(repo, config.envVars, extra);
     // Build docker run args
     const args = ["run", "-d", "--rm", "--name", containerName];
     // --network host: container shares host network stack (no -p needed)
@@ -163,10 +168,13 @@ export async function startRemoteContainer(config, repo) {
     const uniqueId = Math.random().toString(36).slice(2, 8);
     const machineName = `app-building-${uniqueId}`;
     // Build env vars for the machine
-    const containerEnv = buildContainerEnv(repo, config.envVars, {
+    const remoteExtra = {
         PORT: "3000",
         CONTAINER_NAME: machineName,
-    });
+    };
+    if (config.webhookUrl)
+        remoteExtra.WEBHOOK_URL = config.webhookUrl;
+    const containerEnv = buildContainerEnv(repo, config.envVars, remoteExtra);
     // Remove Fly-specific vars from container env (not needed inside)
     delete containerEnv.FLY_API_TOKEN;
     delete containerEnv.FLY_APP_NAME;
@@ -260,6 +268,8 @@ export function stopContainer(config, containerName) {
     config.registry.markStopped(containerName);
 }
 export function spawnTestContainer(config) {
+    if (!config.projectRoot)
+        throw new Error("projectRoot is required for local Docker operations");
     ensureImageExists(config.projectRoot);
     const uniqueId = Math.random().toString(36).slice(2, 8);
     const containerName = `app-building-test-${uniqueId}`;

package/package.json

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