@enderfga/claw-orchestrator 5.1.0 → 6.0.0

package/dist/src/ultraapp/fix-on-failure.js

@@ -1,76 +1,60 @@
 /**
- * Purpose-built helper: run the standard verification pipeline in a worktree,
- * spawn a Claude session to fix mechanical errors on red, retry up to N rounds.
+ * Run the verification pipeline in a worktree, spawn a session to fix mechanical
+ * errors on red, retry up to N rounds.
+ *
+ * As of 6.0.0 this is an adapter over `src/verify/`, not its own runner. The
+ * logic it used to own — ordered steps, exit-code gating, byte-capped tails, the
+ * fix loop — moved out to become mode-agnostic, and came back with the two
+ * things it was missing: a per-step timeout (a wedged `npm test` used to hang
+ * the pipeline forever) and an honoured `required` flag (the field was declared
+ * here and never read, so every step was fatal).
  *
  * Not to be confused with src/autoloop/, which is a planner/coder/reviewer
  * message-bus orchestrator for a different problem shape.
  */
-import { spawn } from 'node:child_process';
-const DEFAULT_STEPS = [
+import path from 'node:path';
+import os from 'node:os';
+import { runContract } from '../verify/runner.js';
+const TEN_MIN = 10 * 60_000;
+export const DEFAULT_STEPS = [
     { cmd: 'npm', args: ['install'] },
     { cmd: 'npm', args: ['run', 'build'] },
     { cmd: 'npm', args: ['test'] },
     { cmd: 'docker', args: ['build', '-t', 'ultraapp-fix:test', '.'] },
 ];
-const TAIL_LINES = 200;
-export async function runFixOnFailure(args) {
-    const shell = args.shell ?? realShell;
-    const spawnFixer = args.spawnFixer ?? defaultSpawnFixer;
-    const steps = args.steps ?? DEFAULT_STEPS;
-    let rounds = 0;
-    while (true) {
-        const failure = await runPipelineOnce(shell, args.worktreePath, steps);
-        if (failure === null)
-            return { ok: true, rounds };
-        if (rounds >= args.maxRounds) {
-            return {
-                ok: false,
-                rounds,
-                lastError: failure.lastError,
-                failingCommand: failure.failingCommand,
-            };
-        }
-        rounds++;
-        await spawnFixer({
-            worktreePath: args.worktreePath,
-            failingCommand: failure.failingCommand,
-            tail: failure.tail,
-        });
-    }
+/** Translate the legacy step list into contract checks, `required` included this time. */
+export function stepsToContract(steps, fixOnFailureRounds) {
+    const checks = steps.map((s, i) => ({
+        id: `${s.cmd}-${i + 1}`,
+        spec: { type: 'command', cmd: s.cmd, args: s.args, timeoutMs: s.timeoutMs ?? TEN_MIN },
+        required: s.required !== false,
+    }));
+    return { id: 'fix-on-failure', checks, fixOnFailureRounds };
 }
-async function runPipelineOnce(shell, cwd, steps) {
-    for (const step of steps) {
-        const r = await shell(step.cmd, step.args, { cwd });
-        if (!r.ok) {
-            const cmdline = `${step.cmd} ${step.args.join(' ')}`;
-            const tail = lastN(r.stderr || r.stdout, TAIL_LINES);
-            return { failingCommand: cmdline, lastError: tail.slice(0, 500), tail };
-        }
-    }
-    return null;
-}
-function lastN(s, n) {
-    const lines = s.split('\n');
-    return lines.slice(-n).join('\n');
+export async function runFixOnFailure(args) {
+    const contract = args.contract ?? stepsToContract(args.steps ?? DEFAULT_STEPS, args.maxRounds);
+    const spawnFixer = args.spawnFixer
+        ? ({ cwd, failingCheck, tail }) => args.spawnFixer({ worktreePath: cwd, failingCommand: failingCheck, tail })
+        : undefined;
+    const { results, passed, rounds } = await runContract({ ...contract, fixOnFailureRounds: args.maxRounds }, {
+        cwd: args.worktreePath,
+        artifactDir: args.artifactDir ?? path.join(os.tmpdir(), 'clawo-fix-artifacts'),
+        exec: args.shell ? shellToExec(args.shell) : undefined,
+    }, spawnFixer);
+    const failing = results.find((r) => r.required && !r.passed);
+    return {
+        ok: passed,
+        rounds,
+        lastError: failing ? (failing.tail ?? failing.detail).slice(0, 500) : undefined,
+        failingCommand: failing?.detail,
+        results,
+    };
 }
-// Only the tail of build output is ever used (see lastN). Cap each stream so a
-// runaway build (e.g. a watch loop printing forever) can't OOM the process.
-const MAX_CAPTURE_BYTES = 512 * 1024;
-function appendCapped(buf, chunk) {
-    const next = buf + chunk;
-    return next.length > MAX_CAPTURE_BYTES ? next.slice(next.length - MAX_CAPTURE_BYTES) : next;
+/** Keep the injectable `ShellRunner` seam callers already depend on. */
+function shellToExec(shell) {
+    return async (cmd, cmdArgs, opts) => {
+        const r = await shell(cmd, cmdArgs, { cwd: opts.cwd ?? process.cwd() });
+        return { code: r.ok ? 0 : 1, out: r.stdout, err: r.stderr, timedOut: false, durationMs: 0 };
+    };
 }
-const realShell = (cmd, args, opts) => new Promise((resolve) => {
-    const child = spawn(cmd, args, { cwd: opts.cwd, stdio: ['ignore', 'pipe', 'pipe'] });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (d) => (stdout = appendCapped(stdout, d.toString())));
-    child.stderr.on('data', (d) => (stderr = appendCapped(stderr, d.toString())));
-    child.on('close', (code) => resolve({ ok: code === 0, stdout, stderr }));
-    child.on('error', (e) => resolve({ ok: false, stdout, stderr: stderr + e.message }));
-});
-const defaultSpawnFixer = async (args) => {
-    const { spawnFixerSession } = await import('./fix-on-failure-session.js');
-    await spawnFixerSession(args);
-};
 //# sourceMappingURL=fix-on-failure.js.map

package/dist/src/ultraapp/fix-on-failure.js.map

@@ -1 +1 @@
-{"version":3,"file":"fix-on-failure.js","sourceRoot":"","sources":["../../../src/ultraapp/fix-on-failure.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fix-on-failure.js","sourceRoot":"","sources":["../../../src/ultraapp/fix-on-failure.ts"],"names":[],"mappings":"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"}

package/dist/src/ultraapp/manager.d.ts

@@ -1,8 +1,11 @@
 import { type AppSpec } from './spec.js';
-import { type UltraappStore, type ChatEntry } from './store.js';
+import { type UltraappStore, type ChatEntry, type RunMode } from './store.js';
 import { type QuestionEnvelope } from './interview-parser.js';
 import { type PatchOp } from './json-patch.js';
 import type { BuildEvent } from './build-events.js';
+import { RunKernel } from '../kernel/engine.js';
+import type { RunRecord } from '../kernel/types.js';
+import { type AcceptanceContract, type CheckResult } from '../verify/contract.js';
 import { type DeployArgs, type DeployResult } from './deploy.js';
 import type { UltraappRouter } from './router.js';
 export type RunEvent = {
@@ -56,23 +59,69 @@ export interface UltraappManagerOptions {
         `build-complete` (v0.2 behaviour); when present, deploy runs after build
         and the run reaches `done` with a public-but-local URL. */
     router?: UltraappRouter;
+    /**
+     * The run kernel that drives the build pipeline.
+     *
+     * Supplied by SessionManager in production so UltraApp's runs share the one
+     * run store, listing and ownership model as everything else. Left out, a
+     * private kernel is wired up — which keeps the class usable on its own, and
+     * still means there is only one execution model, not two.
+     */
+    kernel?: RunKernel;
     /** Test seam: stub the deploy state machine. */
     deployFn?: (a: DeployArgs) => Promise<DeployResult>;
+    /**
+     * Override the build-stage acceptance contract.
+     *
+     * A caller-supplied contract, never an agent-supplied one — the same rule as
+     * everywhere else in the verification plane. It exists because the default
+     * really does run `npm install && npm run build && npm test` in the generated
+     * codebase, which a unit test has no business doing; tests declare a trivial
+     * contract the way they inject `deployFn`.
+     */
+    buildContract?: AcceptanceContract;
+    /**
+     * Test seam: stub the deploy-stage acceptance checks. The real one drives a
+     * headless browser against the deployed URL, which a stubbed deploy has not
+     * got, so tests inject their own the same way they inject `deployFn`.
+     */
+    runDeployChecksFn?: (contract: AcceptanceContract, cwd: string, artifactDir: string) => Promise<CheckResult[]>;
     /** Runtime mode for build + deploy. 'host' (default) runs the generated
         app as a regular Node process — works anywhere Node works, no extra
         deps. 'docker' uses `docker build` + `docker run` for isolation; only
         use this when you want shared-host hardening. */
     runtimeMode?: 'host' | 'docker';
 }
+/**
+ * The kernel run id for an app's current build.
+ *
+ * Stable rather than per-attempt, so `clawo workflow show ultraapp-<id>` always
+ * names the build that matters; a rebuild deletes the previous run and starts a
+ * new one under the same id, which the incarnation check makes safe.
+ */
+export declare function ultraappKernelRunId(appRunId: string): string;
+/**
+ * UltraApp's `RunMode`, derived from the kernel record.
+ *
+ * The build pipeline no longer has a state machine of its own: this reads the
+ * one the kernel keeps. `interview` and `queued` are not here because they are
+ * not pipeline states — nothing is running yet, and the interview genuinely is
+ * not a workflow.
+ */
+export declare function ultraappModeOf(record: RunRecord): RunMode;
 export declare class UltraappManager {
     private readonly opts;
     private readonly runs;
     private readonly skillContent;
     private readonly buildQueue;
     private readonly narrators;
+    private readonly kernel;
+    /** Per-run serialisation for the mode projection. See {@link projectMode}. */
+    private readonly projectChain;
     private readonly classifierSessions;
     private readonly inflightWork;
     constructor(opts: UltraappManagerOptions);
+    private ultraappNodeDeps;
     get store(): UltraappStore;
     createRun(): Promise<string>;
     submitAnswer(runId: string, answer: {
@@ -94,8 +143,64 @@ export declare class UltraappManager {
     startBuild(runId: string): Promise<void>;
     cancelBuild(runId: string): void;
     buildPosition(runId: string): number;
+    /**
+     * Run the build pipeline as a kernel workflow.
+     *
+     * This used to be a hand-rolled sequence: council, then fix-on-failure, then
+     * deploy, with a mode enum written at each step and nothing checkpointed
+     * between them. It worked, but it meant UltraApp was a second runtime standing
+     * beside the one this release exists to be — its runs were invisible to
+     * `workflow_list` and the Runs tab, and a crash halfway through threw away a
+     * finished council and started it again from nothing.
+     *
+     * Now the sequence is a `WorkflowSpec` and the kernel drives it. What is left
+     * here is the part that is genuinely UltraApp's: turning kernel events into
+     * `BuildEvent`s for the dashboard, and keeping `RunMode` — which the whole
+     * UI and every stored run reads — as a projection of the kernel's state
+     * rather than as a second source of truth.
+     *
+     * The interview and the done-mode conversation are deliberately NOT here.
+     * They are user-driven and open-ended; expressing them as a workflow would
+     * mean a router self-loop fighting the visit bound, or one fake node with a
+     * state machine hidden inside it. That would be unification as theatre.
+     */
     private runBuild;
-    private runDeployStage;
+    /** Best-effort narrator startup; its failure must not sink a build. */
+    private startNarrator;
+    /**
+     * Translate the run's kernel events into build events and mode transitions.
+     *
+     * The mode is recomputed from the record every time rather than stepped
+     * forward, so a handler that arrives late cannot write a stale value over a
+     * newer one — which it otherwise can, because these handlers are async and the
+     * kernel does not wait for them.
+     */
+    private subscribeKernel;
+    private onKernelEvent;
+    /**
+     * Write UltraApp's mode as it is implied by the kernel record, right now.
+     *
+     * Serialised per run, and that is the whole mechanism. These are fired from
+     * async event handlers, so two of them can read the record at different
+     * moments and still write in the opposite order — which showed up as a run
+     * that had already failed reverting to `building`. Chaining read-compute-write
+     * makes the last write the one computed last, and the kernel record only ever
+     * moves forward, so the last computed value is the current one.
+     */
+    private projectMode;
+    private projectModeNow;
+    /** Emit the terminal build event and settle the mode from the final record. */
+    private settleBuild;
+    /**
+     * Deploy the built codebase and check the deployed thing.
+     *
+     * Returns an outcome rather than writing modes: the mode is projected from the
+     * kernel now, and a stage that also wrote it would put the two back out of
+     * step. The acceptance verdict comes back with the outcome because it is the
+     * run's terminal verdict — §7g screenshots are taken against a URL that does
+     * not exist until this has run, so the contract cannot sit in the spec.
+     */
+    private deployStage;
     startContainer(runId: string): Promise<{
         ok: boolean;
         error?: string;