@replayio/app-building 1.24.1 → 1.26.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. |
+| `Task` | Interface for task queue entries — includes `skill`, `subtasks`, `timestamp`, and optional fields like `id`, `requiredTaskIds`, `parentTaskId`, `command`, etc. |
+
 ## 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.
@@ -245,8 +285,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 | `id`, `iteration`, `skill`, `subtasks`, `prompt` |
-| `task.done` | Task processing complete | `id`, `skill`, `subtasks`, `prompt`, `cost`, `totalCost`, `failed`, `pendingTasks`, `duration_ms` |
+| `task.started` | Task processing begins | All `Task` fields (`id`, `skill`, `subtasks`, `timestamp`, `app`, `prompt`, `command`, `maxAttempts`, `timeoutMinutes`, `setup`, `requiredTaskIds`, `parentTaskId`) + `iteration` |
+| `task.done` | Task processing complete | All `Task` fields + `cost`, `totalCost`, `failed`, `pendingTasks`, `duration_ms` |
 | `log` | Each log line | `line` |
 
 ### Example

package/dist/index.d.ts

@@ -1,6 +1,188 @@
-export * from "./container";
-export * from "./container-registry";
-export * from "./container-utils";
-export * from "./http-client";
-export * from "./image-ref";
-export * from "./secrets";
+interface RegistryEntry extends AgentState {
+    startedAt: string;
+    stoppedAt?: string;
+}
+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[]>;
+}
+declare class FileContainerRegistry implements ContainerRegistry {
+    private filePath;
+    constructor(filePath: string);
+    private readRegistry;
+    private updateEntry;
+    log(state: AgentState): void;
+    markStopped(containerName?: string): void;
+    clearStopped(containerName: string): void;
+    getRecent(limit?: number): RegistryEntry[];
+    find(containerName: string): RegistryEntry | null;
+    findAlive(): Promise<RegistryEntry[]>;
+}
+
+/**
+ * Infisical secrets API.
+ *
+ * API versions used (per https://infisical.com/docs/api-reference):
+ *   - Auth:    POST /api/v1/auth/universal-auth/login
+ *   - Secrets: GET/POST/PATCH /api/v4/secrets[/{secretName}]
+ *   - Folders: POST /api/v2/folders
+ */
+interface InfisicalConfig {
+    token: string;
+    projectId: string;
+    environment: string;
+}
+/**
+ * Log in to Infisical using Universal Auth (Client ID + Client Secret).
+ * POST /api/v1/auth/universal-auth/login
+ * Returns a short-lived access token.
+ */
+declare function infisicalLogin(clientId: string, clientSecret: string): Promise<string>;
+/**
+ * Fetch secrets from an Infisical folder path.
+ * GET /api/v4/secrets?projectId=…&environment=…&secretPath=…
+ * Returns a key→value record.
+ */
+declare function fetchInfisicalSecrets(config: InfisicalConfig, secretPath: string): Promise<Record<string, string>>;
+/**
+ * Fetch global build secrets from `/global/`.
+ */
+declare function fetchGlobalSecrets(config: InfisicalConfig): Promise<Record<string, string>>;
+/**
+ * Fetch per-branch deployment secrets from `/branches/<branch>/`.
+ */
+declare function fetchBranchSecrets(config: InfisicalConfig, branch: string): Promise<Record<string, string>>;
+/**
+ * Create or update a branch secret in Infisical.
+ * Creates the folder path if it doesn't exist yet.
+ *
+ *   POST  /api/v4/secrets/{name}   — create
+ *   PATCH /api/v4/secrets/{name}   — update (if secret already exists)
+ *
+ * Body: { projectId, environment, secretPath, secretValue, type }
+ */
+declare function createBranchSecret(config: InfisicalConfig, branch: string, name: string, value: string): Promise<void>;
+/**
+ * Extract Infisical config from environment variables and log in.
+ * Reads INFISICAL_CLIENT_ID, INFISICAL_CLIENT_SECRET, INFISICAL_PROJECT_ID,
+ * and INFISICAL_ENVIRONMENT from the env vars.
+ * Throws if any required var is missing.
+ */
+declare function getInfisicalConfig(envVars: Record<string, string>): Promise<InfisicalConfig>;
+
+interface AgentState {
+    type: "local" | "remote";
+    containerName: string;
+    port: number;
+    baseUrl: string;
+    flyApp?: string;
+    flyMachineId?: string;
+    flyVolumeId?: string;
+}
+interface ContainerConfig {
+    projectRoot?: string;
+    /** Infisical credentials — required for all containers. */
+    infisical: InfisicalConfig;
+    registry: ContainerRegistry;
+    flyToken?: string;
+    flyApp?: string;
+    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;
+    /** 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). */
+    initialPrompt?: string;
+    /** Override the host port for local containers (default: auto-selected). */
+    localPort?: number;
+    /** Absorb task files from other containers at startup. Default: false. */
+    absorbTasks?: boolean;
+    /** Container name prefix. Default: "app-building". */
+    namePrefix?: string;
+    /** Agent command override (e.g. "codex", "gemini"). Default: "claude". */
+    agentCommand?: string;
+}
+interface RepoOptions {
+    repoUrl: string;
+    cloneBranch: string;
+    pushBranch: string;
+}
+declare function loadDotEnv(projectRoot: string): Record<string, string>;
+declare function buildImage(config: ContainerConfig): void;
+/**
+ * Start a container (local Docker or remote Fly.io based on config).
+ * If flyToken and flyApp are set, starts remotely; otherwise locally.
+ */
+declare function startContainer(config: ContainerConfig, repo: RepoOptions): Promise<AgentState>;
+/**
+ * Stop a container by its state or registry entry.
+ */
+declare function stopContainer(config: ContainerConfig, state: AgentState | RegistryEntry): Promise<void>;
+/**
+ * Spawn an interactive test container (local only).
+ */
+declare function spawnTestContainer(config: ContainerConfig): Promise<void>;
+
+interface HttpOptions {
+    timeout?: number;
+    headers?: Record<string, string>;
+}
+declare function httpGet(url: string, opts?: HttpOptions): Promise<any>;
+declare function httpPost(url: string, body?: unknown, opts?: HttpOptions): Promise<any>;
+
+declare function httpOptsFor(state: AgentState): HttpOptions;
+declare function probeAlive(entry: RegistryEntry): Promise<boolean>;
+
+declare function getImageRef(): string;
+
+/**
+ * Task dependency resolution helpers.
+ *
+ * Pure functions that take task arrays and return ready tasks — no file I/O.
+ */
+interface Task {
+    skill: string;
+    subtasks: string[];
+    timestamp: string;
+    app?: string;
+    /** Optional ID for coordination (e.g. from task webhook). Included in task.started/task.done events. */
+    id?: string;
+    /** Raw prompt for message-derived tasks (no skill file). */
+    prompt?: string;
+    /** Custom command (agent + args) to run instead of the default "claude" with extraArgs. */
+    command?: string;
+    /** Maximum number of attempts before giving up. Default: 5. */
+    maxAttempts?: number;
+    /** Maximum time in minutes for each attempt. Agent is killed if exceeded. */
+    timeoutMinutes?: number;
+    /** Shell command to run once when the task starts (before the first agent attempt). */
+    setup?: string;
+    /** Task IDs that must complete before this task can start. */
+    requiredTaskIds?: string[];
+    /** The ID of the task that spawned this task via add-task. */
+    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).
+ */
+declare function findReadyTask(pendingTasks: Task[], completedTasks: Pick<Task, "id" | "parentTaskId">[]): Task | null;
+
+export { type AgentState, type ContainerConfig, type ContainerRegistry, FileContainerRegistry, type HttpOptions, type InfisicalConfig, type RegistryEntry, type RepoOptions, type Task, buildImage, createBranchSecret, fetchBranchSecrets, fetchGlobalSecrets, fetchInfisicalSecrets, findReadyTask, getImageRef, getInfisicalConfig, httpGet, httpOptsFor, httpPost, infisicalLogin, loadDotEnv, probeAlive, spawnTestContainer, startContainer, stopContainer };