@replayio/app-building 1.25.0 → 1.27.0

package/README.md

@@ -149,7 +149,7 @@ The agent can also run `list-secrets` to see which secrets are available, and `s
 | 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. |
+| `Task` | Interface for task queue entries — includes `skill`, `subtasks`, `timestamp`, and optional fields like `id`, `requiredTaskIds`, `parentTaskId`, `command`, etc. |
 
 ## Container HTTP API
 
@@ -215,8 +215,9 @@ when the required task has completed **and** all of its child tasks (tasks with
 `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:
+By default, `add-task` chains tasks serially — each task depends on the previous one. Set
+`"parallel": true` on individual tasks to run them concurrently. Non-parallel tasks act as
+barriers:
 
 ```bash
 # Serial (default): B waits for A, C waits for B
@@ -224,9 +225,14 @@ 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"] }]
+# Mixed: A runs first, B and C run in parallel, D waits for both B and C
+npx tsx /repo/scripts/add-task.ts <<'EOF'
+[
+  { "skill": "...", "subtasks": ["A"] },
+  { "skill": "...", "parallel": true, "subtasks": ["B"] },
+  { "skill": "...", "parallel": true, "subtasks": ["C"] },
+  { "skill": "...", "subtasks": ["D"] }
+]
 EOF
 ```
 
@@ -285,8 +291,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,7 +1,188 @@
-export * from "./container";
-export * from "./container-registry";
-export * from "./container-utils";
-export * from "./http-client";
-export * from "./image-ref";
-export * from "./secrets";
-export * from "./tasks";
+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 };