@replayio/app-building 1.24.1 → 1.25.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`, `taskWebhookUrl` (GET endpoint for external task queue), `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), `addTaskWebhookUrl` (POST endpoint for tasks added by `add-task` script), `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`. |
@@ -144,6 +144,13 @@ The agent can also run `list-secrets` to see which secrets are available, and `s
 |---|---|
 | `getImageRef()` | Returns `CONTAINER_IMAGE_REF` env var, or `ghcr.io/replayio/app-building:latest` by default. |
 
+### Task dependencies
+
+| Export | Description |
+|---|---|
+| `findReadyTask(pendingTasks, completedTasks)` | Find the first task in `pendingTasks` whose `requiredTaskIds` are all satisfied. A required task is satisfied when it appears in `completedTasks` and has no children still pending or with incomplete children of their own (recursive). Returns the task, or `null` if all are blocked. |
+| `TaskInfo` | Interface with `id?`, `requiredTaskIds?`, `parentTaskId?` — the minimum fields needed for dependency resolution. |
+
 ## Container HTTP API
 
 Each container runs an HTTP server that accepts the following requests:
@@ -196,6 +203,32 @@ Each task in the queue (local or webhook) has the following fields:
 | `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. |
+| `setup` | `string` | No | Shell command to run once when the task starts (before the first agent attempt). Task fails if it exits non-zero. |
+| `requiredTaskIds` | `string[]` | No | Task IDs that must complete before this task can start. A task is "complete" when it and all its child tasks have finished. |
+| `parentTaskId` | `string` | No | ID of the task that spawned this task (set automatically by `add-task`). Used for dependency resolution — a required task isn't considered complete until all its children are done. |
+
+### Task dependencies
+
+Tasks can declare dependencies on other tasks via `requiredTaskIds`. The worker skips blocked
+tasks and picks the first task whose dependencies are all satisfied. A dependency is satisfied
+when the required task has completed **and** all of its child tasks (tasks with matching
+`parentTaskId`) have also completed. This means a task that depends on a parent will
+automatically wait for all work the parent spawned.
+
+By default, `add-task` chains tasks serially — each task depends on the previous one. Use
+`--parallel` to add tasks that can run in any order:
+
+```bash
+# Serial (default): B waits for A, C waits for B
+npx tsx /repo/scripts/add-task.ts <<'EOF'
+[{ "skill": "...", "subtasks": ["A"] }, { "skill": "...", "subtasks": ["B"] }, { "skill": "...", "subtasks": ["C"] }]
+EOF
+
+# Parallel: A, B, C can run in any order
+npx tsx /repo/scripts/add-task.ts --parallel <<'EOF'
+[{ "skill": "...", "subtasks": ["A"] }, { "skill": "...", "subtasks": ["B"] }, { "skill": "...", "subtasks": ["C"] }]
+EOF
+```
 
 ### External task queue
 
@@ -209,6 +242,13 @@ local task queue is empty, the container GETs this URL (with the same `Bearer` t
 The first task is processed immediately; any remaining tasks are added to the local queue.
 Tasks use the same structure documented above.
 
+### Add-task webhook
+
+Set `config.addTaskWebhookUrl` to a POST endpoint that receives tasks added by the `add-task`
+script. When set, the agent's `add-task` calls POST tasks to this URL instead of writing to
+the local task file. The request body is `{ "tasks": [...] }` with the same task structure
+documented above. Auth uses the same `Bearer` token from `webhookSecret`.
+
 ## 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.

package/dist/container.d.ts

@@ -21,6 +21,8 @@ export interface ContainerConfig {
     webhookSecret?: string;
     /** GET endpoint to fetch the next task when the local queue is empty. Uses webhookSecret for auth. */
     taskWebhookUrl?: string;
+    /** POST endpoint to receive tasks added by the add-task script. When set, add-task POSTs tasks here instead of writing to the local task file. Uses webhookSecret for auth. */
+    addTaskWebhookUrl?: 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). */
@@ -31,6 +33,8 @@ export interface ContainerConfig {
     absorbTasks?: boolean;
     /** Container name prefix. Default: "app-building". */
     namePrefix?: string;
+    /** Agent command override (e.g. "codex", "gemini"). Default: "claude". */
+    agentCommand?: string;
 }
 export interface RepoOptions {
     repoUrl: string;

package/dist/container.js

@@ -104,6 +104,8 @@ function buildExtraEnv(config, containerName) {
         extra.WEBHOOK_URL = config.webhookUrl;
     if (config.taskWebhookUrl)
         extra.TASK_WEBHOOK_URL = config.taskWebhookUrl;
+    if (config.addTaskWebhookUrl)
+        extra.ADD_TASK_WEBHOOK_URL = config.addTaskWebhookUrl;
     if (config.webhookSecret)
         extra.WEBHOOK_SECRET = config.webhookSecret;
     if (config.detached)
@@ -112,6 +114,8 @@ function buildExtraEnv(config, containerName) {
         extra.INITIAL_PROMPT = config.initialPrompt;
     if (config.absorbTasks)
         extra.ABSORB_TASKS = "1";
+    if (config.agentCommand)
+        extra.AGENT_COMMAND = config.agentCommand;
     return extra;
 }
 function isRemote(config) {

package/dist/index.d.ts

@@ -4,3 +4,4 @@ export * from "./container-utils";
 export * from "./http-client";
 export * from "./image-ref";
 export * from "./secrets";
+export * from "./tasks";

package/dist/index.js

@@ -4,3 +4,4 @@ export * from "./container-utils";
 export * from "./http-client";
 export * from "./image-ref";
 export * from "./secrets";
+export * from "./tasks";

package/dist/tasks.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Task dependency resolution helpers.
+ *
+ * Pure functions that take task arrays and return ready tasks — no file I/O.
+ */
+export interface TaskInfo {
+    id?: string;
+    requiredTaskIds?: string[];
+    parentTaskId?: string;
+}
+/**
+ * Find the first task in `pendingTasks` whose dependencies are all satisfied.
+ * Returns the task, or null if all tasks are blocked.
+ *
+ * A required task is "fully complete" when:
+ * 1. It appears in `completedTasks`, AND
+ * 2. Every task in `completedTasks` that has it as `parentTaskId` is also
+ *    fully complete (recursive — children's children must also be done), AND
+ * 3. No task in `pendingTasks` has it as `parentTaskId`.
+ *
+ * @param pendingTasks - Tasks waiting to run (ordered by priority).
+ * @param completedTasks - Tasks that have finished (need id and parentTaskId).
+ */
+export declare function findReadyTask<T extends TaskInfo>(pendingTasks: T[], completedTasks: TaskInfo[]): T | null;

package/dist/tasks.js

@@ -0,0 +1,53 @@
+/**
+ * Task dependency resolution helpers.
+ *
+ * Pure functions that take task arrays and return ready tasks — no file I/O.
+ */
+/**
+ * Find the first task in `pendingTasks` whose dependencies are all satisfied.
+ * Returns the task, or null if all tasks are blocked.
+ *
+ * A required task is "fully complete" when:
+ * 1. It appears in `completedTasks`, AND
+ * 2. Every task in `completedTasks` that has it as `parentTaskId` is also
+ *    fully complete (recursive — children's children must also be done), AND
+ * 3. No task in `pendingTasks` has it as `parentTaskId`.
+ *
+ * @param pendingTasks - Tasks waiting to run (ordered by priority).
+ * @param completedTasks - Tasks that have finished (need id and parentTaskId).
+ */
+export function findReadyTask(pendingTasks, completedTasks) {
+    const completedIds = new Set(completedTasks.map((t) => t.id).filter(Boolean));
+    // Parents that still have pending children.
+    const pendingChildParents = new Set();
+    for (const t of pendingTasks) {
+        if (t.parentTaskId)
+            pendingChildParents.add(t.parentTaskId);
+    }
+    // Cache for recursive full-completion check.
+    const cache = new Map();
+    function isFullyComplete(taskId) {
+        if (cache.has(taskId))
+            return cache.get(taskId);
+        // Prevent infinite recursion on cycles.
+        cache.set(taskId, false);
+        if (!completedIds.has(taskId))
+            return false;
+        if (pendingChildParents.has(taskId))
+            return false;
+        // Check completed children are also fully complete.
+        for (const child of completedTasks) {
+            if (child.parentTaskId === taskId && child.id && !isFullyComplete(child.id)) {
+                return false;
+            }
+        }
+        cache.set(taskId, true);
+        return true;
+    }
+    const idx = pendingTasks.findIndex((task) => {
+        if (!task.requiredTaskIds || task.requiredTaskIds.length === 0)
+            return true;
+        return task.requiredTaskIds.every((id) => isFullyComplete(id));
+    });
+    return idx === -1 ? null : pendingTasks[idx];
+}

package/package.json

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