Merge pull request #1 from egavrin/codex/mar10-cleanup

fix(runner): validate execution artifacts and standardize tooling

Author: egavrin

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DevAgent Hub Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bun.lock

@@ -0,0 +1,28 @@
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    languageOptions: {
+      globals: {
+        Buffer: "readonly",
+        clearTimeout: "readonly",
+        console: "readonly",
+        process: "readonly",
+        setTimeout: "readonly",
+      },
+    },
+  },
+  {
+    rules: {
+      "@typescript-eslint/no-unused-vars": ["warn", { argsIgnorePattern: "^_" }],
+      "@typescript-eslint/no-explicit-any": "warn",
+      "no-console": ["warn", { allow: ["error", "warn"] }],
+    },
+  },
+  {
+    ignores: ["**/dist/**", "**/node_modules/**", "*.config.js"],
+  },
+);

eslint.config.js

@@ -9,11 +9,19 @@
   "scripts": {
     "build": "bunx tsc -b packages/core packages/local-runner packages/adapters packages/cli",
     "typecheck": "bunx tsc -b --pretty false packages/core packages/local-runner packages/adapters packages/cli",
-    "test": "bun run build && bun test ./packages/*/dist/*.test.js"
+    "test": "bun run build && node ./node_modules/vitest/vitest.mjs run --config vitest.config.ts",
+    "lint": "bunx eslint packages/"
   },
   "devDependencies": {
+    "@devagent-sdk/schema": "file:../devagent-sdk/packages/schema",
+    "@devagent-sdk/types": "file:../devagent-sdk/packages/types",
+    "@devagent-sdk/validation": "file:../devagent-sdk/packages/validation",
+    "@eslint/js": "^10.0.1",
     "@types/bun": "^1.3.10",
     "@types/node": "^24.3.0",
-    "typescript": "^5.9.3"
+    "eslint": "^10.0.3",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.1",
+    "vitest": "^3.2.4"
   }
 }

package.json

@@ -12,6 +12,7 @@
   },
   "dependencies": {
     "@devagent-runner/core": "file:../core",
+    "@devagent-sdk/validation": "file:../../../devagent-sdk/packages/validation",
     "@devagent-sdk/types": "file:../../../devagent-sdk/packages/types"
   },
   "scripts": {

packages/adapters/package.json

@@ -1,8 +1,8 @@
-import test from "node:test";
 import assert from "node:assert/strict";
 import { join } from "node:path";
 import { chmod, mkdtemp, mkdir, readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
+import { test } from "vitest";
 import {
   ClaudeAdapter,
   CodexAdapter,
@@ -155,6 +155,28 @@ setTimeout(() => process.exit(0), 10000);
   assert.equal(events.length, 0);
 });
 
+test("DevAgentAdapter emits failure events when result.json is missing", async () => {
+  const { root, artifactDir, workspacePath } = await createWorkspace();
+  const stubPath = join(root, "devagent-missing-result-stub.js");
+  await createStub(stubPath, `#!/usr/bin/env node
+process.stderr.write("result file was never written\\n");
+process.exit(1);
+`);
+
+  const { events, result } = await collectEvents(
+    new DevAgentAdapter(`${process.execPath} ${stubPath}`),
+    createRequest("devagent"),
+    workspacePath,
+    artifactDir,
+  );
+
+  assert.equal(result.status, "failed");
+  assert.equal(result.error?.code, "EXECUTION_FAILED");
+  assert.deepEqual(events.map((event) => event.type), ["log", "log", "artifact", "completed"]);
+  assert.equal(events[0]?.type, "log");
+  assert.match(events[0]?.type === "log" ? events[0].message : "", /result file was never written/);
+});
+
 test("CodexAdapter smoke test with stub executable", async () => {
   const { root, artifactDir, workspacePath } = await createWorkspace();
   const stubPath = join(root, "codex-stub.js");

packages/adapters/src/index.test.ts

@@ -1,11 +1,11 @@
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import type { ChildProcess } from "node:child_process";
-import type { ExecutorAdapter, RunHandle } from "@devagent-runner/core";
-import { RunnerError } from "@devagent-runner/core";
+import type { ExecutorAdapter, RunHandle, RunStatus } from "@devagent-runner/core";
+import { RunnerError, TrackedRunHandle } from "@devagent-runner/core";
+import { validateTaskExecutionEvent, validateTaskExecutionResult } from "@devagent-sdk/validation";
 import type {
   ArtifactKind,
   ArtifactRef,
@@ -19,12 +19,21 @@ import { PROTOCOL_VERSION } from "@devagent-sdk/types";
 async function waitForFile(path: string, timeoutMs = 500): Promise<boolean> {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() <= deadline) {
-    if (existsSync(path)) {
+    if (await fileExists(path)) {
       return true;
     }
     await new Promise((resolve) => setTimeout(resolve, 25));
   }
-  return existsSync(path);
+  return fileExists(path);
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 function artifactFileName(kind: ArtifactKind): string {
@@ -67,33 +76,17 @@ function artifactTitle(taskType: TaskExecutionRequest["taskType"]): string {
   return taskType[0]!.toUpperCase() + taskType.slice(1);
 }
 
-class ProcessRunHandle implements RunHandle {
-  private currentStatus: "running" | "success" | "failed" | "cancelled" = "running";
-  readonly pid: number | undefined;
-
+class ProcessRunHandle extends TrackedRunHandle {
   constructor(
     readonly id: string,
     private readonly child: ChildProcess,
-    private readonly resultPromise: Promise<TaskExecutionResult>,
+    resultPromise: Promise<TaskExecutionResult>,
   ) {
-    this.pid = child.pid ?? undefined;
-    void this.resultPromise.then((result) => {
-      this.currentStatus = result.status;
-    }).catch(() => {
-      this.currentStatus = "failed";
-    });
-  }
-
-  status(): "running" | "success" | "failed" | "cancelled" {
-    return this.currentStatus;
-  }
-
-  wait(): Promise<TaskExecutionResult> {
-    return this.resultPromise;
+    super(id, child.pid ?? undefined, resultPromise);
   }
 
   async cancel(): Promise<void> {
-    this.currentStatus = "cancelled";
+    this.markCancelled();
     this.child.kill("SIGTERM");
   }
 }
@@ -155,7 +148,7 @@ async function createFallbackResult(
 }
 
 function errorForStatus(
-  status: TaskExecutionResult["status"],
+  status: RunStatus,
   message: string,
 ): TaskExecutionResult["error"] | undefined {
   if (status === "success") {
@@ -335,7 +328,7 @@ export class DevAgentAdapter implements ExecutorAdapter {
       const lines = chunk.toString().split("\n").filter((line: string) => line.trim());
       for (const line of lines) {
         try {
-          onEvent(JSON.parse(line) as TaskExecutionEvent);
+          onEvent(validateTaskExecutionEvent(JSON.parse(line)));
         } catch {
           onEvent({
             protocolVersion: PROTOCOL_VERSION,
@@ -364,19 +357,17 @@ export class DevAgentAdapter implements ExecutorAdapter {
 
     const resultPromise = new Promise<TaskExecutionResult>((resolve, reject) => {
       child.once("error", (error: Error) => reject(new RunnerError("PROCESS_LAUNCH_FAILED", error.message)));
-      let exitCode: number | null = null;
       let exitSignal: NodeJS.Signals | null = null;
 
-      child.once("exit", (code: number | null, signal: NodeJS.Signals | null) => {
-        exitCode = code;
+      child.once("exit", (_code: number | null, signal: NodeJS.Signals | null) => {
         exitSignal = signal;
       });
 
       child.once("close", async () => {
         try {
           const resultPath = join(artifactDir, "result.json");
           if (!await waitForFile(resultPath)) {
-            const status = exitSignal === "SIGTERM" ? "cancelled" : "failed";
+            const status: RunStatus = exitSignal === "SIGTERM" ? "cancelled" : "failed";
             const fallback = await createFallbackResult(
               request,
               artifactDir,
@@ -388,10 +379,34 @@ export class DevAgentAdapter implements ExecutorAdapter {
                 exitSignal === "SIGTERM" ? "Cancelled by operator" : (stderr || "Missing result.json"),
               ),
             );
+            if (status === "failed") {
+              onEvent({
+                protocolVersion: PROTOCOL_VERSION,
+                type: "log",
+                at: new Date().toISOString(),
+                taskId: request.taskId,
+                stream: "stderr",
+                message: stderr || "DevAgent did not emit result.json",
+              } as TaskExecutionEvent);
+              onEvent({
+                protocolVersion: PROTOCOL_VERSION,
+                type: "artifact",
+                at: new Date().toISOString(),
+                taskId: request.taskId,
+                artifact: fallback.artifacts[0]!,
+              } as TaskExecutionEvent);
+              onEvent({
+                protocolVersion: PROTOCOL_VERSION,
+                type: "completed",
+                at: new Date().toISOString(),
+                taskId: request.taskId,
+                status,
+              } as TaskExecutionEvent);
+            }
             resolve(fallback);
             return;
           }
-          const parsed = JSON.parse(await readFile(resultPath, "utf-8")) as TaskExecutionResult;
+          const parsed = validateTaskExecutionResult(JSON.parse(await readFile(resultPath, "utf-8")));
           resolve(parsed);
         } catch (error) {
           reject(error);
@@ -421,7 +436,7 @@ export class CodexAdapter extends CliPromptAdapter {
       ],
       parseOutput: async (stdout, artifactDir) => {
         const lastMessagePath = join(artifactDir, "last-message.txt");
-        if (existsSync(lastMessagePath)) {
+        if (await fileExists(lastMessagePath)) {
           return readFile(lastMessagePath, "utf-8");
         }
         return stdout;

packages/adapters/src/index.ts

@@ -15,11 +15,42 @@ export interface WorkspaceManager {
 
 export interface RunHandle {
   readonly id: string;
+  readonly pid?: number;
   status(): RunStatus;
   wait(): Promise<TaskExecutionResult>;
   cancel(): Promise<void>;
 }
 
+export abstract class TrackedRunHandle implements RunHandle {
+  private currentStatus: RunStatus = "running";
+
+  constructor(
+    readonly id: string,
+    readonly pid: number | undefined,
+    private readonly resultPromise: Promise<TaskExecutionResult>,
+  ) {
+    void this.resultPromise.then((result) => {
+      this.currentStatus = result.status;
+    }).catch(() => {
+      this.currentStatus = "failed";
+    });
+  }
+
+  status(): RunStatus {
+    return this.currentStatus;
+  }
+
+  wait(): Promise<TaskExecutionResult> {
+    return this.resultPromise;
+  }
+
+  protected markCancelled(): void {
+    this.currentStatus = "cancelled";
+  }
+
+  abstract cancel(): Promise<void>;
+}
+
 export interface ExecutorAdapter {
   executorId(): string;
   canHandle(spec: ExecutorSpec): boolean;

packages/core/src/index.ts

@@ -12,6 +12,7 @@
   },
   "dependencies": {
     "@devagent-runner/core": "file:../core",
+    "@devagent-sdk/validation": "file:../../../devagent-sdk/packages/validation",
     "@devagent-sdk/types": "file:../../../devagent-sdk/packages/types"
   },
   "scripts": {