@replayio/app-building 1.21.0 → 1.23.0

package/README.md

@@ -80,7 +80,7 @@ The agent can also run `list-secrets` to see which secrets are available, and `s
 
 | Export | Description |
 |---|---|
-| `ContainerConfig` | `infisical` (required `InfisicalConfig`), optional `projectRoot` (local Docker only), `registry`, `flyToken`/`flyApp` (set both for remote Fly.io), `imageRef`, `webhookUrl`/`webhookSecret`, `detached`, `initialPrompt`, `localPort`, `absorbTasks`, `namePrefix` (default: `"app-building"`). |
+| `ContainerConfig` | `infisical` (required `InfisicalConfig`), optional `projectRoot` (local Docker only), `registry`, `flyToken`/`flyApp` (set both for remote Fly.io), `imageRef`, `webhookUrl`/`webhookSecret`, `taskWebhookUrl` (GET endpoint for external task queue), `detached`, `initialPrompt`, `localPort`, `absorbTasks`, `namePrefix` (default: `"app-building"`). |
 | `RepoOptions` | Per-invocation git settings: `repoUrl`, `cloneBranch`, `pushBranch`. |
 | `AgentState` | Returned by `startContainer`. Contains `type`, `containerName`, `port`, `baseUrl`, and Fly-specific fields for remote containers. |
 | `ContainerRegistry` | Interface for container registry storage. Methods: `log`, `markStopped`, `clearStopped`, `getRecent`, `find`, `findAlive`. |
@@ -182,6 +182,33 @@ Set `config.absorbTasks = true` to have the container absorb task files from oth
 at startup. This is off by default. When enabled, the container scans `tasks/` for task files
 belonging to other containers, merges their tasks into its own queue, and deletes the foreign files.
 
+### Task structure
+
+Each task in the queue (local or webhook) has the following fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | Auto-assigned | UUID for coordination. Auto-assigned by `add-task` if not provided. Included in `task.started`/`task.done` webhook events. |
+| `skill` | `string` | Yes | Path to the skill file (e.g. `skills/tasks/build/writeApp.md`). |
+| `subtasks` | `string[]` | Yes | List of subtask descriptions. |
+| `app` | `string` | No | App name (directory under `apps/`). |
+| `prompt` | `string` | No | Raw prompt for message-derived tasks (no skill file). |
+| `command` | `string` | No | Custom command to run instead of the default `claude` CLI. |
+| `maxAttempts` | `number` | No | Maximum attempts before giving up. Default: 5. |
+| `timeoutMinutes` | `number` | No | Per-attempt time limit in minutes. Agent is killed if exceeded. |
+
+### External task queue
+
+Set `config.taskWebhookUrl` to a GET endpoint that returns tasks to process. When the
+local task queue is empty, the container GETs this URL (with the same `Bearer` token from
+`webhookSecret`) and expects a JSON response:
+
+- `{ "tasks": [{ "skill": "...", "subtasks": [...], ... }, ...] }` — process these tasks
+- `{}` or `{ "tasks": [] }` — no tasks available, go idle
+
+The first task is processed immediately; any remaining tasks are added to the local queue.
+Tasks use the same structure documented above.
+
 ## Webhooks
 
 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). Set `webhookSecret` to include a `Bearer` token in the `Authorization` header for authenticating webhook requests.
@@ -218,8 +245,8 @@ Every POST body has this shape:
 | `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 | `iteration`, `skill`, `subtasks`, `prompt` |
-| `task.done` | Task processing complete | `skill`, `subtasks`, `prompt`, `cost`, `totalCost`, `failed`, `pendingTasks`, `duration_ms` |
+| `task.started` | Task processing begins | `id`, `iteration`, `skill`, `subtasks`, `prompt` |
+| `task.done` | Task processing complete | `id`, `skill`, `subtasks`, `prompt`, `cost`, `totalCost`, `failed`, `pendingTasks`, `duration_ms` |
 | `log` | Each log line | `line` |
 
 ### Example

package/dist/container.d.ts

@@ -19,6 +19,8 @@ export interface ContainerConfig {
     imageRef?: string;
     webhookUrl?: string;
     webhookSecret?: string;
+    /** GET endpoint to fetch the next task when the local queue is empty. Uses webhookSecret for auth. */
+    taskWebhookUrl?: 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). */

package/dist/container.js

@@ -102,6 +102,8 @@ function buildExtraEnv(config, containerName) {
     };
     if (config.webhookUrl)
         extra.WEBHOOK_URL = config.webhookUrl;
+    if (config.taskWebhookUrl)
+        extra.TASK_WEBHOOK_URL = config.taskWebhookUrl;
     if (config.webhookSecret)
         extra.WEBHOOK_SECRET = config.webhookSecret;
     if (config.detached)

package/package.json

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