xcoder-dna 0.0.0-stage → 1.3.1

package/dist/worker-agent/to-subtask-node.d.ts

@@ -0,0 +1,35 @@
+import type { SubtaskNode } from "../types.js";
+import type { WorkerSubtask } from "./worker-orchestrator.js";
+/**
+ * Context handed to the adapter for one attempt. Everything here is
+ * traceability-only except `maxAttempts`, which is carried into the node's
+ * `healing` block purely so downstream logs read correctly.
+ */
+export interface ToSubtaskNodeContext {
+    taskId: string;
+    /** 1-based attempt number of the wave being dispatched. */
+    attempt: number;
+    maxAttempts: number;
+    /** Errors from previous attempts, folded into `healing.log` for traceability only. */
+    priorErrors: string[];
+}
+/**
+ * Adapts a generic `WorkerSubtask` onto the `SubtaskNode` shape every Sub
+ * Agent already understands.
+ *
+ * Every constant below is justified by reading `agents/sub-agent.ts`, not
+ * guessed:
+ *
+ * - `engine: "react-v1"` — hard requirement. `SubAgent.run()` synthesises a
+ *   not-implemented result for any other engine name, so this is not
+ *   caller-controllable and is deliberately absent from `WorkerSubtask`.
+ * - `stage: "code"` — cosmetic on this path. `SubAgent` reads `stage` only
+ *   when tagging a lesson/text for a stuck loop; it gates nothing. If that
+ *   ever changes, this constant becomes a real bug (design tradeoff T4).
+ * - `role` — genuinely matters: it indexes the role directives and per-role
+ *   protocol overrides. Caller-controllable, defaulting to `programmer`.
+ * - `dependsOn: []` — worker subtasks are independent (design tradeoff T3).
+ * - `acceptanceCriteria: []` — there is no SDLC validation gate on this path,
+ *   and `SubAgent` does not read the field.
+ */
+export declare function toSubtaskNode(sub: WorkerSubtask, ctx: ToSubtaskNodeContext): SubtaskNode;

package/dist/worker-agent/to-subtask-node.js

@@ -0,0 +1,41 @@
+/**
+ * Adapts a generic `WorkerSubtask` onto the `SubtaskNode` shape every Sub
+ * Agent already understands.
+ *
+ * Every constant below is justified by reading `agents/sub-agent.ts`, not
+ * guessed:
+ *
+ * - `engine: "react-v1"` — hard requirement. `SubAgent.run()` synthesises a
+ *   not-implemented result for any other engine name, so this is not
+ *   caller-controllable and is deliberately absent from `WorkerSubtask`.
+ * - `stage: "code"` — cosmetic on this path. `SubAgent` reads `stage` only
+ *   when tagging a lesson/text for a stuck loop; it gates nothing. If that
+ *   ever changes, this constant becomes a real bug (design tradeoff T4).
+ * - `role` — genuinely matters: it indexes the role directives and per-role
+ *   protocol overrides. Caller-controllable, defaulting to `programmer`.
+ * - `dependsOn: []` — worker subtasks are independent (design tradeoff T3).
+ * - `acceptanceCriteria: []` — there is no SDLC validation gate on this path,
+ *   and `SubAgent` does not read the field.
+ */
+export function toSubtaskNode(sub, ctx) {
+    const goal = (sub.goal ?? "").trim();
+    const deliverableSpec = (sub.deliverableSpec ?? "").trim() || goal;
+    const role = sub.role ?? "programmer";
+    return {
+        id: sub.id,
+        stage: "code",
+        role,
+        engine: "react-v1",
+        dependsOn: [],
+        goal,
+        upstreamContext: sub.upstreamContext ?? {},
+        deliverableSpec,
+        acceptanceCriteria: [],
+        status: "ready",
+        healing: {
+            attempts: Math.max(0, ctx.attempt - 1),
+            maxAttempts: ctx.maxAttempts,
+            log: [...ctx.priorErrors],
+        },
+    };
+}

package/dist/worker-agent/worker-orchestrator.d.ts

@@ -0,0 +1,104 @@
+import { dispatchSwarm } from "../orchestrator/swarm.js";
+import type { LlmClient } from "../llm/client.js";
+import type { Role, SubtaskResult, TokenUsage } from "../types.js";
+/**
+ * One unit of work. There is intentionally no `stage`, `engine`,
+ * `dependsOn`, `acceptanceCriteria` or `healing` field — an `SdlcStage`
+ * cannot be supplied to this path by construction.
+ */
+export interface WorkerSubtask {
+    /** Stable id, echoed in the report. Unique within a request. */
+    id: string;
+    /** Self-contained work order. */
+    goal: string;
+    /** Owning role. Optional: defaults to "programmer". Prompt routing only. */
+    role?: Role;
+    /** Inlined upstream context, as in `SubtaskNode`. */
+    upstreamContext?: Record<string, unknown>;
+    /** Optional; defaults to `goal`. */
+    deliverableSpec?: string;
+}
+export interface WorkerRunRequest {
+    taskDescription: string;
+    /** Ordered; request order is preserved in the report, execution is concurrent. */
+    subtasks: WorkerSubtask[];
+    /** Default 3. Clamped to >= 1. */
+    concurrency?: number;
+    /** Total attempts per subtask (not retries). Default 2. Clamped to >= 1. */
+    maxAttempts?: number;
+    /** Optional run id; otherwise `worker-<timestamp>`. */
+    taskId?: string;
+    /** Stops *new* waves. In-flight agents finish (no real-time cancellation). */
+    signal?: AbortSignal;
+}
+export type WorkerSubtaskStatus = "done" | "failed";
+export interface WorkerAttemptRecord {
+    /** 1-based. */
+    attempt: number;
+    ok: boolean;
+    error: string | null;
+}
+export interface WorkerSubtaskReport {
+    id: string;
+    status: WorkerSubtaskStatus;
+    /** Always >= 1; equals `history.length`. */
+    attempts: number;
+    summary: string;
+    /** Last failure message; `null` when the subtask is done. */
+    error: string | null;
+    filesTouched: string[];
+    tokenUsage: TokenUsage;
+    iterations: number;
+    crashed: boolean;
+    /** One entry per attempt, in order — this is what makes retries assertable. */
+    history: WorkerAttemptRecord[];
+}
+export type WorkerRunStatus = "completed" | "partial" | "failed";
+export interface WorkerRunReport {
+    taskId: string;
+    taskDescription: string;
+    status: WorkerRunStatus;
+    /** Request order, always one entry per requested subtask. */
+    subtasks: WorkerSubtaskReport[];
+    totals: {
+        subtasks: number;
+        done: number;
+        failed: number;
+        totalAttempts: number;
+        inputTokens: number;
+        outputTokens: number;
+        durationMs: number;
+    };
+    /** Run-level problems (adapter/validation), never raw agent stacks. */
+    errors: string[];
+}
+export interface WorkerOrchestratorOptions {
+    workspaceRoot: string;
+    llm: LlmClient;
+    /** Swarm worker client; defaults to `llm`. */
+    subAgentLlm?: LlmClient;
+    quiet?: boolean;
+    /** Injection seam for tests — defaults to the real `dispatchSwarm`. */
+    dispatch?: typeof dispatchSwarm;
+}
+/**
+ * The single place "what counts as a failed attempt" is decided. Centralising
+ * it keeps the retry loop unchanged if the policy is ever revisited, and lets
+ * tests assert the predicate directly.
+ */
+export declare function isFailure(result: SubtaskResult): boolean;
+export declare class WorkerOrchestrator {
+    private readonly workspaceRoot;
+    private readonly llm;
+    private readonly subAgentLlm?;
+    private readonly quiet;
+    private readonly dispatch;
+    constructor(opts: WorkerOrchestratorOptions);
+    /**
+     * Runs every subtask, retrying failures in bounded waves.
+     *
+     * NEVER rejects — for any input, and for any failure of any worker agent.
+     * Unusable input surfaces as a `failed` report with run-level `errors`.
+     */
+    run(request: WorkerRunRequest): Promise<WorkerRunReport>;
+}

package/dist/worker-agent/worker-orchestrator.js

@@ -0,0 +1,201 @@
+// xcoder:version 1 | xcoder:task task-c4a64f | xcoder:updated 2026-10-17T02:20:47.001Z | xcoder:subtask code-st-348a21
+// Generic worker orchestrator — non-SDLC task delegation.
+//
+// Deliberately NOT a copy of `sdlc-orchestrator.ts`: there is no TaskSpec,
+// no WBS DAG, no escalations, no orchestrator trace, and no `SdlcStage` in
+// the public input. Concurrency and crash isolation are delegated to the
+// existing `dispatchSwarm`; the only logic here is the retry policy and
+// report assembly.
+import { dispatchSwarm } from "../orchestrator/swarm.js";
+import { toSubtaskNode } from "./to-subtask-node.js";
+/**
+ * The single place "what counts as a failed attempt" is decided. Centralising
+ * it keeps the retry loop unchanged if the policy is ever revisited, and lets
+ * tests assert the predicate directly.
+ */
+export function isFailure(result) {
+    return result.crashed === true || result.iterationsExhausted === true;
+}
+function emptyResult(error) {
+    return {
+        summary: error,
+        deliverable: null,
+        filesTouched: [],
+        raoTrace: [],
+        tokenUsage: { inputTokens: 0, outputTokens: 0 },
+        iterations: 0,
+        crashed: true,
+    };
+}
+function errOf(result) {
+    const summary = (result.summary ?? "").trim();
+    if (summary)
+        return summary;
+    if (result.crashed)
+        return "subtask crashed";
+    if (result.iterationsExhausted)
+        return "subtask exhausted its iteration budget";
+    return "subtask failed";
+}
+export class WorkerOrchestrator {
+    workspaceRoot;
+    llm;
+    subAgentLlm;
+    quiet;
+    dispatch;
+    constructor(opts) {
+        this.workspaceRoot = opts.workspaceRoot;
+        this.llm = opts.llm;
+        this.subAgentLlm = opts.subAgentLlm;
+        this.quiet = opts.quiet ?? false;
+        this.dispatch = opts.dispatch ?? dispatchSwarm;
+    }
+    /**
+     * Runs every subtask, retrying failures in bounded waves.
+     *
+     * NEVER rejects — for any input, and for any failure of any worker agent.
+     * Unusable input surfaces as a `failed` report with run-level `errors`.
+     */
+    async run(request) {
+        const startedAt = Date.now();
+        const taskId = (request?.taskId ?? "").trim() || `worker-${startedAt}`;
+        const taskDescription = request?.taskDescription ?? "";
+        const errors = [];
+        const requested = Array.isArray(request?.subtasks) ? request.subtasks : [];
+        if (!Array.isArray(request?.subtasks)) {
+            errors.push("request.subtasks must be an array; nothing was dispatched");
+        }
+        const concurrency = Math.max(1, Math.floor(request?.concurrency ?? 3) || 1);
+        const maxAttempts = Math.max(1, Math.floor(request?.maxAttempts ?? 2) || 1);
+        const signal = request?.signal;
+        // De-duplicate by id defensively: dispatchSwarm keys results by subtask id,
+        // so a duplicate would silently mis-map results.
+        const seen = new Set();
+        const subtasks = [];
+        for (const sub of requested) {
+            const id = (sub?.id ?? "").trim();
+            if (!id) {
+                errors.push(`skipped a subtask with no id (goal: ${(sub?.goal ?? "").slice(0, 80)})`);
+                continue;
+            }
+            if (seen.has(id)) {
+                errors.push(`skipped duplicate subtask id '${id}'`);
+                continue;
+            }
+            seen.add(id);
+            subtasks.push(sub);
+        }
+        const history = new Map();
+        const finals = new Map();
+        for (const sub of subtasks)
+            history.set(sub.id, []);
+        let pending = [...subtasks];
+        let attempt = 1;
+        while (pending.length > 0 && attempt <= maxAttempts && !signal?.aborted) {
+            const priorErrorsOf = (id) => (history.get(id) ?? [])
+                .map((h) => h.error)
+                .filter((e) => typeof e === "string" && e.length > 0);
+            const nodes = pending.map((sub) => toSubtaskNode(sub, {
+                taskId,
+                attempt,
+                maxAttempts,
+                priorErrors: priorErrorsOf(sub.id),
+            }));
+            let dispatched = [];
+            try {
+                dispatched = await this.dispatch(nodes, {
+                    taskId,
+                    workspaceRoot: this.workspaceRoot,
+                    llm: this.llm,
+                    subAgentLlm: this.subAgentLlm,
+                    concurrency,
+                    signal,
+                    quiet: this.quiet,
+                });
+            }
+            catch (e) {
+                // `dispatchSwarm` is contractually non-throwing; reaching here means
+                // something structural broke. Attribute it to every subtask in the
+                // wave rather than losing the run.
+                const message = e?.message ?? String(e);
+                errors.push(`dispatch failed on attempt ${attempt}: ${message}`);
+                dispatched = [];
+            }
+            const byId = new Map();
+            for (const out of dispatched ?? []) {
+                if (out && typeof out.subtaskId === "string" && out.result) {
+                    byId.set(out.subtaskId, out.result);
+                }
+            }
+            const retry = [];
+            for (const sub of pending) {
+                const result = byId.get(sub.id) ?? emptyResult("no result returned for this subtask");
+                const failed = isFailure(result);
+                const rec = {
+                    attempt,
+                    ok: !failed,
+                    error: failed ? errOf(result) : null,
+                };
+                history.get(sub.id)?.push(rec);
+                if (failed && attempt < maxAttempts) {
+                    retry.push(sub);
+                }
+                else {
+                    finals.set(sub.id, { result, error: failed ? rec.error : null });
+                }
+            }
+            pending = retry;
+            attempt += 1;
+        }
+        // Anything still pending after the loop ended (abort, or an attempt wave
+        // that produced no result) is finalised as failed — never left absent.
+        for (const sub of pending) {
+            const reason = signal?.aborted ? "aborted before dispatch" : "attempts exhausted without a result";
+            const recs = history.get(sub.id) ?? [];
+            recs.push({ attempt: recs.length + 1, ok: false, error: reason });
+            history.set(sub.id, recs);
+            finals.set(sub.id, { result: emptyResult(reason), error: reason });
+        }
+        const reports = subtasks.map((sub) => {
+            const recs = history.get(sub.id) ?? [];
+            const final = finals.get(sub.id);
+            const result = final?.result ?? emptyResult("subtask was never dispatched");
+            const failed = final ? final.error !== null : true;
+            const hist = recs.length > 0 ? recs.map((r) => ({ ...r })) : [{ attempt: 1, ok: false, error: "not dispatched" }];
+            return {
+                id: sub.id,
+                status: failed ? "failed" : "done",
+                attempts: hist.length,
+                summary: result.summary ?? "",
+                error: failed ? (final?.error ?? "subtask was never dispatched") : null,
+                filesTouched: Array.isArray(result.filesTouched) ? [...result.filesTouched] : [],
+                tokenUsage: {
+                    inputTokens: result.tokenUsage?.inputTokens ?? 0,
+                    outputTokens: result.tokenUsage?.outputTokens ?? 0,
+                },
+                iterations: result.iterations ?? 0,
+                crashed: result.crashed === true,
+                history: hist,
+            };
+        });
+        const done = reports.filter((r) => r.status === "done").length;
+        const failedCount = reports.length - done;
+        const status = reports.length === 0 || failedCount === 0 ? "completed" : done === 0 ? "failed" : "partial";
+        return {
+            taskId,
+            taskDescription,
+            status,
+            subtasks: reports,
+            totals: {
+                subtasks: reports.length,
+                done,
+                failed: failedCount,
+                totalAttempts: reports.reduce((sum, r) => sum + r.attempts, 0),
+                inputTokens: reports.reduce((sum, r) => sum + r.tokenUsage.inputTokens, 0),
+                outputTokens: reports.reduce((sum, r) => sum + r.tokenUsage.outputTokens, 0),
+                durationMs: Date.now() - startedAt,
+            },
+            errors,
+        };
+    }
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "xcoder-dna",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.3.1",
+  "description": "Reusable Xcoder components: tools, skills, swarm, sub-agent runtime and shared orchestration primitives.",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node -e \"fs.cpSync('skills', 'dist/skills', { recursive: true })\"",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.32.0",
+    "@clack/prompts": "^0.7.0",
+    "cheerio": "^1.2.0",
+    "cli-spinners": "^2.9.2",
+    "commander": "^12.1.0",
+    "dotenv": "^16.4.5",
+    "js-yaml": "^5.5.0",
+    "openai": "^7.4.0",
+    "ora": "^8.1.0",
+    "zod": "^4.4.3"
+  },
+  "optionalDependencies": {
+    "playwright": "^1.62.1"
+  }
 }