pi-harness-runtime 1.1.428 → 1.1.430

package/packages/runtime/src/runtime-api.ts

@@ -25,9 +25,86 @@ import { createServer, type Server, type IncomingMessage } from "node:http";
 import { WebSocketServer, WebSocket } from "ws";
 import { URL } from "node:url";
 import { EventEmitter } from "node:events";
-import type { JobStateMachine } from "../../harness/job-state-machine.js";
-import type { TaskGraphManager } from "../../../harness/task-graph.js";
-import type { CheckpointManager } from "../../harness/job-state-machine.js";
+import type {
+	JobStatus,
+	RuntimeCheckpoint,
+	RuntimeEvent,
+	RuntimeTask,
+} from "../../types/dist/runtime-types.js";
+
+/**
+ * The outcome of a job transition, as reported by the registered machine.
+ */
+export interface JobTransitionResult {
+	success: boolean;
+	checkpoint?: RuntimeCheckpoint;
+	error?: string;
+}
+
+/**
+ * The job actions the API exposes.
+ *
+ * The states are the ones the job state machine actually has:
+ * `paused_quota` is its only paused state and a paused job returns to
+ * `running`. There is no plain `paused` status, so the API must not
+ * pretend there is one.
+ */
+const JOB_ACTIONS: Record<
+	string,
+	{ status: JobStatus; message: string; event: string }
+> = {
+	start: { status: "running", message: "Job started", event: "job.started" },
+	pause: {
+		status: "paused_quota",
+		message: "Job paused",
+		event: "job.paused",
+	},
+	resume: { status: "running", message: "Job resumed", event: "job.resumed" },
+	cancel: {
+		status: "cancelled",
+		message: "Job cancelled",
+		event: "job.cancelled",
+	},
+};
+
+/**
+ * The job state machine the harness registers.
+ *
+ * The runtime API does not implement a job: it stores the machine the
+ * harness already runs and reports on it. The package therefore describes
+ * the shape it uses instead of importing the harness - the harness is the
+ * app root, a package may not reach into it, and the import also dragged
+ * the whole harness program into this package's compilation.
+ */
+export interface JobStateMachineLike {
+	getStatusSummary(): {
+		status: JobStatus;
+		isTerminal: boolean;
+		canResume: boolean;
+	} | null;
+	getCheckpoint(): RuntimeCheckpoint | null | Promise<RuntimeCheckpoint | null>;
+	resumeJob(jobId: string): Promise<JobTransitionResult>;
+	transition(
+		to: JobStatus,
+		data?: Partial<RuntimeCheckpoint>,
+	): Promise<JobTransitionResult>;
+}
+
+/**
+ * The task graph the harness registers.
+ */
+export interface TaskGraphLike {
+	getAllTasks(): RuntimeTask[];
+}
+
+/**
+ * The checkpoint manager the harness registers.
+ */
+export interface CheckpointManagerLike {
+	save(checkpoint: RuntimeCheckpoint): Promise<void>;
+	load(jobId: string): Promise<RuntimeCheckpoint | null>;
+	appendEvent(jobId: string, event: RuntimeEvent): Promise<void>;
+}
 
 export interface RuntimeApiConfig {
 	/** Port to listen on (default: 3849) */
@@ -107,9 +184,9 @@ export class RuntimeApi extends EventEmitter {
 	private wsClients: Set<WebSocket> = new Set();
 	private isRunning = false;
 	private startTime: number = 0;
-	private jobMachines: Map<string, JobStateMachine> = new Map();
-	private taskGraphs: Map<string, TaskGraphManager> = new Map();
-	private checkpoints: Map<string, CheckpointManager> = new Map();
+	private jobMachines: Map<string, JobStateMachineLike> = new Map();
+	private taskGraphs: Map<string, TaskGraphLike> = new Map();
+	private checkpoints: Map<string, CheckpointManagerLike> = new Map();
 	private requestCounter = 0;
 
 	constructor(config: RuntimeApiConfig = {}) {
@@ -118,6 +195,18 @@ export class RuntimeApi extends EventEmitter {
 		this.startTime = Date.now();
 	}
 
+	/**
+	 * The port the API listens on.
+	 *
+	 * The operating system picks the port when the API was started on port
+	 * 0, so the running port is not always the configured one.
+	 */
+	getPort(): number | null {
+		const address = this.server?.address();
+		if (!address || typeof address === "string") return null;
+		return address.port;
+	}
+
 	/**
 	 * Start the Runtime API server
 	 */
@@ -212,21 +301,24 @@ export class RuntimeApi extends EventEmitter {
 	/**
 	 * Register a job machine
 	 */
-	registerJob(jobId: string, machine: JobStateMachine): void {
+	registerJob(jobId: string, machine: JobStateMachineLike): void {
 		this.jobMachines.set(jobId, machine);
 	}
 
 	/**
 	 * Register a task graph
 	 */
-	registerTaskGraph(jobId: string, graph: TaskGraphManager): void {
+	registerTaskGraph(jobId: string, graph: TaskGraphLike): void {
 		this.taskGraphs.set(jobId, graph);
 	}
 
 	/**
 	 * Register a checkpoint manager
 	 */
-	registerCheckpointManager(jobId: string, manager: CheckpointManager): void {
+	registerCheckpointManager(
+		jobId: string,
+		manager: CheckpointManagerLike,
+	): void {
 		this.checkpoints.set(jobId, manager);
 	}
 
@@ -315,22 +407,32 @@ export class RuntimeApi extends EventEmitter {
 		res: import("node:http").ServerResponse,
 	): void {
 		const origin = req.headers.origin;
-		const allowedOrigins = this.config.corsOrigins ?? ["*"];
+		if (!origin) {
+			// Only a browser request carries an Origin header, and only a
+			// browser request is affected by the CORS headers.
+			return;
+		}
 
+		const allowedOrigins = this.config.corsOrigins ?? ["*"];
 		if (
-			allowedOrigins.includes("*") ||
-			(origin && allowedOrigins.includes(origin))
+			!allowedOrigins.includes("*") &&
+			!allowedOrigins.includes(origin)
 		) {
-			res.setHeader("Access-Control-Allow-Origin", origin ?? "*");
-			res.setHeader(
-				"Access-Control-Allow-Methods",
-				"GET, POST, PUT, DELETE, OPTIONS",
-			);
-			res.setHeader(
-				"Access-Control-Allow-Headers",
-				"Content-Type, Authorization, X-Api-Key",
-			);
+			return;
 		}
+
+		// The request origin is reflected instead of the wildcard: the API
+		// never enables credentialed requests, and a reflected origin keeps
+		// the response usable for a browser client.
+		res.setHeader("Access-Control-Allow-Origin", origin);
+		res.setHeader(
+			"Access-Control-Allow-Methods",
+			"GET, POST, PUT, DELETE, OPTIONS",
+		);
+		res.setHeader(
+			"Access-Control-Allow-Headers",
+			"Content-Type, Authorization, X-Api-Key",
+		);
 	}
 
 	private async handleRequest(
@@ -400,11 +502,7 @@ export class RuntimeApi extends EventEmitter {
 			const summary = machine.getStatusSummary();
 			if (summary) {
 				if (summary.status === "running") status.jobs.active++;
-				else if (
-					summary.status === "paused" ||
-					summary.status === "paused_quota"
-				)
-					status.jobs.paused++;
+				else if (summary.status === "paused_quota") status.jobs.paused++;
 				else if (summary.isTerminal) status.jobs.completed++;
 			}
 		}
@@ -498,7 +596,7 @@ export class RuntimeApi extends EventEmitter {
 		jobId: string,
 		method: string,
 		url: URL,
-		req: IncomingMessage,
+		_req: IncomingMessage,
 		res: import("node:http").ServerResponse,
 		requestId: string,
 	): Promise<void> {
@@ -550,43 +648,61 @@ export class RuntimeApi extends EventEmitter {
 		const action = url.searchParams.get("action");
 
 		switch (method) {
-			case "POST":
-				if (action === "start") {
-					await machine.resumeJob(jobId);
-					this.broadcast("job.started", { jobId });
-					this.sendJson(res, 200, { message: "Job started", jobId }, requestId);
-				} else if (action === "pause") {
-					const result = await machine.transition("paused");
-					this.broadcast("job.paused", { jobId });
-					this.sendJson(
-						res,
-						200,
-						{ message: "Job paused", jobId, result },
-						requestId,
-					);
-				} else if (action === "resume") {
-					await machine.resumeJob(jobId);
-					this.broadcast("job.resumed", { jobId });
-					this.sendJson(res, 200, { message: "Job resumed", jobId }, requestId);
-				} else if (action === "cancel") {
-					const result = await machine.transition("cancelled");
-					this.broadcast("job.cancelled", { jobId });
+			case "POST": {
+				const target = JOB_ACTIONS[action ?? ""];
+				if (!target) {
+					this.sendJson(res, 400, { error: "Unknown action" }, requestId);
+					break;
+				}
+
+				const result = await this.moveJob(machine, jobId, target.status);
+				if (!result.success) {
 					this.sendJson(
 						res,
-						200,
-						{ message: "Job cancelled", jobId, result },
+						409,
+						{
+							error: result.error ?? `Cannot ${target.message.toLowerCase()}`,
+							jobId,
+						},
 						requestId,
 					);
-				} else {
-					this.sendJson(res, 400, { error: "Unknown action" }, requestId);
+					break;
 				}
+
+				this.broadcast(target.event, { jobId });
+				this.sendJson(res, 200, { message: target.message, jobId }, requestId);
 				break;
+			}
 
 			default:
 				this.sendJson(res, 405, { error: "Method not allowed" }, requestId);
 		}
 	}
 
+	/**
+	 * Move a job to a new state.
+	 *
+	 * The machine keeps the active checkpoint in memory, so it has to be
+	 * activated for the job before it can transition. The transition itself
+	 * validates the move against the state machine's rules and reports the
+	 * outcome, so a refused move never becomes a false success.
+	 */
+	private async moveJob(
+		machine: JobStateMachineLike,
+		jobId: string,
+		to: JobStatus,
+	): Promise<JobTransitionResult> {
+		const activated = await machine.resumeJob(jobId);
+		if (!activated.success) {
+			return {
+				success: false,
+				error: activated.error ?? `Job ${jobId} is not available`,
+			};
+		}
+
+		return machine.transition(to);
+	}
+
 	private async handleGetQuota(
 		res: import("node:http").ServerResponse,
 		requestId: string,

package/packages/runtime/test/runtime-api.test.ts

@@ -0,0 +1,169 @@
+/**
+ * Runtime API tests — the job actions and the states they use.
+ *
+ * The API stores the job machine the harness registers and moves the job
+ * through the state machine. The states are the ones the state machine
+ * actually has: `paused_quota` is its only paused state, and there is no
+ * plain `paused` status.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import {
+	RuntimeApi,
+	type JobStateMachineLike,
+	type JobTransitionResult,
+} from "../src/runtime-api.js";
+import type {
+	JobStatus,
+	RuntimeCheckpoint,
+} from "../../types/dist/runtime-types.js";
+
+/** The states the fake machine accepts. */
+const ACCEPTED: JobStatus[] = ["running", "paused_quota", "cancelled"];
+
+/** The envelope every API response uses. */
+interface ApiResponseBody<T> {
+	success: boolean;
+	data?: T;
+	error?: string;
+}
+
+/** Read the JSON body of a response. */
+async function readJson<T>(res: Response): Promise<ApiResponseBody<T>> {
+	return (await res.json()) as ApiResponseBody<T>;
+}
+
+/** A job machine that records the moves the API asks for. */
+class FakeMachine implements JobStateMachineLike {
+	status: JobStatus = "running";
+	readonly moves: JobStatus[] = [];
+
+	getStatusSummary() {
+		return {
+			status: this.status,
+			isTerminal: this.status === "cancelled",
+			canResume: this.status === "paused_quota",
+		};
+	}
+
+	getCheckpoint(): RuntimeCheckpoint {
+		return {
+			version: 1,
+			jobId: "job-1",
+			status: this.status,
+			requirement: "do the thing",
+			createdAt: "2026-01-01T00:00:00.000Z",
+			updatedAt: "2026-01-01T00:00:00.000Z",
+		};
+	}
+
+	async resumeJob(): Promise<JobTransitionResult> {
+		return { success: true };
+	}
+
+	async transition(to: JobStatus): Promise<JobTransitionResult> {
+		this.moves.push(to);
+		if (!ACCEPTED.includes(to)) {
+			return { success: false, error: `Invalid transition to ${to}` };
+		}
+		this.status = to;
+		return { success: true };
+	}
+}
+
+describe("RuntimeApi job actions", () => {
+	let api: RuntimeApi;
+	let machine: FakeMachine;
+	let base: string;
+
+	beforeEach(async () => {
+		api = new RuntimeApi({ port: 0, host: "127.0.0.1" });
+		machine = new FakeMachine();
+		api.registerJob("job-1", machine);
+		await api.start();
+		base = `http://127.0.0.1:${api.getPort()}`;
+	});
+
+	afterEach(async () => {
+		await api.stop();
+	});
+
+	it("pauses a job into the state the machine has", async () => {
+		const res = await fetch(`${base}/jobs/job-1?action=pause`, {
+			method: "POST",
+		});
+
+		expect(res.status).toBe(200);
+		expect(machine.moves).toEqual(["paused_quota"]);
+		expect(machine.status).toBe("paused_quota");
+	});
+
+	it("resumes a paused job", async () => {
+		await fetch(`${base}/jobs/job-1?action=pause`, { method: "POST" });
+		machine.moves.length = 0;
+
+		const res = await fetch(`${base}/jobs/job-1?action=resume`, {
+			method: "POST",
+		});
+
+		expect(res.status).toBe(200);
+		expect(machine.moves).toEqual(["running"]);
+		expect(machine.status).toBe("running");
+	});
+
+	it("cancels a job", async () => {
+		const res = await fetch(`${base}/jobs/job-1?action=cancel`, {
+			method: "POST",
+		});
+
+		expect(res.status).toBe(200);
+		expect(machine.status).toBe("cancelled");
+	});
+
+	it("reports a refused move instead of a false success", async () => {
+		const refusing = new FakeMachine();
+		refusing.transition = async (to: JobStatus) => {
+			refusing.moves.push(to);
+			return { success: false, error: "the state machine refused the move" };
+		};
+		api.registerJob("job-2", refusing);
+
+		const res = await fetch(`${base}/jobs/job-2?action=pause`, {
+			method: "POST",
+		});
+
+		expect(res.status).toBe(409);
+		const body = await readJson<never>(res);
+		expect(body.error).toBe("the state machine refused the move");
+	});
+
+	it("rejects an unknown action", async () => {
+		const res = await fetch(`${base}/jobs/job-1?action=explode`, {
+			method: "POST",
+		});
+
+		expect(res.status).toBe(400);
+		expect(machine.moves).toEqual([]);
+	});
+
+	it("counts a paused job as paused", async () => {
+		await fetch(`${base}/jobs/job-1?action=pause`, { method: "POST" });
+
+		const res = await fetch(`${base}/status`);
+		const body = await readJson<{
+			jobs: { total: number; active: number; paused: number; completed: number };
+		}>(res);
+
+		expect(body.data?.jobs.total).toBe(1);
+		expect(body.data?.jobs.paused).toBe(1);
+		expect(body.data?.jobs.active).toBe(0);
+	});
+
+	it("reports an unknown job", async () => {
+		const res = await fetch(`${base}/jobs/nope?action=pause`, {
+			method: "POST",
+		});
+
+		expect(res.status).toBe(404);
+	});
+});

package/packages/scheduler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/scheduler",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "description": "pi-harness-runtime — scheduler",
   "type": "module",
   "main": "./dist/index.js",

package/packages/scheduler-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/scheduler-adapter",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "description": "Scheduler Adapter — cron, systemd, launchd, internal adapters for autonomous runtime (RFC-0101 §6)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/session/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/session",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "description": "Session management system for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/session-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/session-api",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/session-export/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/session-export",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/shared-context/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/shared-context",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "description": "pi-harness-runtime — shared-context",
   "type": "module",
   "main": "./dist/index.js",

package/packages/skill-mcp-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/skill-mcp-client",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "description": "MCP client for Skills SaaS backend",
   "type": "module",
   "main": "./dist/index.js",

package/packages/skill-registry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/skill-registry",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "description": "Skill Registry for pi-harness-runtime — dynamic skill discovery and invocation",
   "type": "module",
   "main": "./dist/index.js",

package/packages/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/skills",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "description": "File-based skill system with pi.dev compatibility and Hermes self-improvement",
   "type": "module",
   "main": "src/index.ts",

package/packages/sprint-planner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/sprint-planner",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "type": "module",
   "description": "Sprint planning engine for pi-harness",
   "main": "dist/index.js",

package/packages/subscription-engine/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/subscription-engine",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/task-compiler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/task-compiler",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "description": "Task Compiler for pi-harness-runtime — produces deterministic task DAG from CompiledRequirement",
   "type": "module",
   "main": "./dist/index.js",

package/packages/tencentdb-memory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moocoding/tencentdb-memory",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "description": "TencentDB Agent Memory client - sync skills to centralized knowledge base",
   "type": "module",
   "main": "src/index.ts",

package/packages/tencentdb-sync/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/tencentdb-sync",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "description": "Sync SKILL.md skills to TencentDB-Agent-Memory server (RFC-0105/0106)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/test-data-generator/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/test-data-generator",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "description": "Test data generation for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/test-generator/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/test-generator",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "description": "Auto-Test Generator — generate unit and E2E tests from source code (RFC-0013)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/todo-bd-sync/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moocoding/todo-bd-sync",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "description": "Two-way sync between rpiv-todo overlay and bd issue tracker",
   "type": "module",
   "main": "src/index.ts",

package/packages/token-estimation/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/token-estimation",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "description": "pi-harness-runtime — token-estimation",
   "type": "module",
   "main": "./dist/index.js",

package/packages/token-optimizer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/token-optimizer",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "description": "Token Budget Optimizer — maximize prompt value within token limits (RFC-0011)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/tooling-preference/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/tooling-preference",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "description": "pi-harness-runtime — JS/TS tooling preference (Biome vs ESLint/Prettier) proposal",
   "type": "module",
   "main": "./dist/index.js",

package/packages/trajectory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/trajectory",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "description": "Trajectory capture for the write-review loop — persists cycle records for learning",
   "type": "module",
   "main": "./dist/src/index.js",

package/packages/tui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/tui",
-  "version": "1.1.428",
+  "version": "1.1.430",
   "description": "pi-harness-runtime — tui",
   "type": "module",
   "main": "./dist/index.js",