@hydraharness/harness-headless 0.1.1-rc.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+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.

package/README.md

@@ -0,0 +1,18 @@
+# `@hydraharness/harness-headless`
+
+The hydra one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides directly over [`@hydraharness/harness-base`](../base/README.md): it supplies the coding persona and tool mode, disables HMR, mounts Code Mode's worker as a core execution capability, and inserts this package's `headless-runner` plugin (config `{task}`, resolved from the injected `headlessStartup` provider). It mounts no Host, HTTP server, Web runtime, or browser plugin.
+
+After the Loader settles, the runner reads the shared [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md), creates one fresh persisted Agent through `ctx.agents`, submits the task as an ordinary user message, and waits for quiescence. It flushes the Session before folding the owned durable event interval, writes the last non-empty assistant text to stdout, and requests exit through the launcher-provided `ctx.appExit` host hook ([`@hydraharness/harness-cmdline`](../../boot/cmdline/README.md)) (final `turn/end` completed → 0, otherwise 1). A terminal `error` reason also writes its code and message to stderr; successful runs keep stderr empty. The process opens no listening port. The task text is this app's command line: the ordinary `headless-startup` provider ([`src/startup.ts`](src/startup.ts)) injects `ctx.cmdlineArgs` ([`@hydraharness/harness-cmdline`](../../boot/cmdline/README.md)), reads the positional argument of `hydra --profile headless "task"`, prints the app's `--help`, and provides `headlessStartup`; the runner injects that service and reads its task from lazy config. A missing or whitespace-only task is rejected before the runner activates.
+
+## Model Experience
+
+None, as the runner submits the task as an ordinary user message; prompts and tools belong to the base and headless bundle rows.
+
+#### KV Cache effect
+
+None; the runner adds nothing to the request prefix.
+
+## Known Limitations and Deferred Work
+
+- **One submitted task only** — the runner has no interactive follow-up surface; it waits through any work the Agent completes before returning to idle and prints the last non-empty assistant message in that interval.
+- **`ctx.appExit` is launcher-owned** — booting the headless profile outside the `hydra` launcher fails loud at activation until the host provides the exit request.

package/cordis.patch.yml

@@ -0,0 +1,35 @@
+# The hydra-headless bundle patch: one-shot task mode directly over hydra-base.
+# It mounts no Host, HTTP server, Web runtime, or browser plugin. An ordinary
+# provider plugin injects `cmdlineArgs`, parses the task positional
+# (`hydra --profile headless "<task>"`) and this app's --help, then the direct
+# driver creates an Agent through the core registry and prints its durable result.
+
+- id: system-prompt
+  config:
+    persona: >-
+      You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.
+
+# The shared module-reload HMR row stays off; the launcher's watch-only
+# fallback still keeps the user patch layers live until the run exits.
+- id: hmr
+  disabled: true
+
+- id: tools
+  config:
+    # Keep the same temporary process-wide Code Mode opt-in as the Web surface.
+    mode: !!js process.env.HYDRA_TOOLS_MODE
+
+- insert:
+    # Code Mode is a core execution capability, not a Web component.
+    - id: code-runtime
+      name: '@hydraharness/harness-code-runtime-worker-thread'
+
+    - id: headless-startup
+      name: '@hydraharness/harness-headless/startup'
+
+    # Reads its task from the ordinary headlessStartup provider.
+    - id: headless-runner
+      name: '@hydraharness/harness-headless'
+      inject: [headlessStartup]
+      config:
+        task: !!js ctx.headlessStartup.task

package/lib/index.js

@@ -0,0 +1,118 @@
+import { randomUUID } from "node:crypto";
+import z from "@hydraharness/schemastery";
+import { installModelSelection } from "@hydraharness/harness-agent";
+import { createUserMessage } from "@hydraharness/harness-llm";
+import { SessionId } from "@hydraharness/harness-session";
+//#region lib/types/index.js
+/**
+* @hydraharness/harness-headless — one-shot direct Agent driver. The bundle patch
+* rides over @hydraharness/harness-base without Host, HTTP, or browser plugins; this runner
+* creates one Agent through the core registry, drives the task to quiescence,
+* flushes its Session, prints the final assistant text, and exits.
+*
+* @module @hydraharness/harness-headless
+*/
+/** Stable Cordis plugin name. */
+const name = "headless-runner";
+/** Core services required before the one-shot turn can start. */
+const inject = [
+	"agentDefaultModel",
+	"agents",
+	"sessions"
+];
+const Config = z.object({ task: z.string().required() });
+/** The process streams the runner writes to; tests substitute captures. */
+const internals = {
+	stdout: process.stdout,
+	stderr: process.stderr
+};
+/** Aggregate the last assistant text and turn outcome in one owned interval. */
+function summarize(events, firstSeq) {
+	let started = false;
+	let text = "";
+	let reason;
+	for (const event of events) {
+		if (event.seq < firstSeq) continue;
+		if (event.type === "turn/start") {
+			started = true;
+			continue;
+		}
+		if (!started) continue;
+		if (event.type === "assistant/message") {
+			const joined = event.data.message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+			if (joined !== "") text = joined;
+		}
+		if (event.type === "turn/end") reason = event.data.reason;
+	}
+	return {
+		text,
+		reason
+	};
+}
+/** Report an unexpected direct-driver failure and request a failing exit. */
+function fail(io, error) {
+	io.stderr.write(`hydra: ${error instanceof Error ? error.message : String(error)}\n`);
+	io.exit(1);
+}
+/**
+* Run one task through a freshly created Agent and request process exit.
+* @param ctx - plugin context carrying the Agent, default model, Session, and launcher IO services.
+* @param task - one-shot task text.
+* @param io - process-facing effects.
+*/
+async function run(ctx, task, io) {
+	await ctx.get("loader")?.await();
+	const agents = ctx.get("agents");
+	const defaultModel = ctx.get("agentDefaultModel");
+	const sessions = ctx.get("sessions");
+	if (agents === void 0 || defaultModel === void 0 || sessions === void 0) return;
+	const selection = defaultModel.currentSelection();
+	const { agent } = await agents.create({
+		sessionId: SessionId(`session-${randomUUID()}`),
+		meta: { cwd: process.cwd() },
+		agentOptions: {
+			provider: selection.provider,
+			model: selection.model
+		},
+		setup: (agentCtx) => {
+			installModelSelection(agentCtx, {
+				current: selection,
+				assembled: void 0
+			});
+		}
+	});
+	await agent.whenIdle();
+	const firstSeq = agent.session.seq;
+	agent.followup(createUserMessage({
+		content: [{
+			type: "text",
+			text: task
+		}],
+		source: { kind: "user" }
+	}));
+	await agent.whenIdle();
+	await sessions.flush(agent.session);
+	const outcome = summarize(agent.session.events, firstSeq);
+	io.stdout.write(outcome.text + "\n");
+	if (outcome.reason?.kind === "error") io.stderr.write(`hydra: ${outcome.reason.error.code}: ${outcome.reason.error.message}\n`);
+	io.exit(outcome.reason?.kind === "completed" ? 0 : 1);
+}
+/**
+* Mount the one-shot direct driver.
+* @param ctx - plugin context carrying core services and the launcher-provided exit request.
+* @param config - validated task config.
+*/
+function apply(ctx, config) {
+	const exit = ctx.get("appExit");
+	if (exit === void 0) throw new Error("headless-runner: the launcher must provide ctx.appExit before the tree mounts");
+	const io = {
+		stdout: internals.stdout,
+		stderr: internals.stderr,
+		exit
+	};
+	run(ctx, config.task, io).catch((error) => {
+		fail(io, error);
+	});
+}
+//#endregion
+export { Config, apply, inject, internals, name };

package/lib/invariant.js

@@ -0,0 +1,25 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-headless`.
+* @module @hydraharness/harness-headless/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-headless";
+/** Cordis companion plugin name. */
+const name = "headless-invariant";
+/** Service required before the companion can register. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the runner is a one-shot driver over the API carrier
+* whose observable contract (final text on stdout, exit code by turn-end
+* reason) is process-level and owned by the launcher e2e; it registers
+* nothing and holds no mutable relation to audit inside the tree.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/startup.js

@@ -0,0 +1,42 @@
+import { Command } from "commander";
+import { parseCmdline } from "@hydraharness/harness-cmdline";
+//#region lib/types/startup.js
+/**
+* The one-shot app's command-line provider: it parses the task positional and
+* `--help`, then publishes {@link HEADLESS_STARTUP_SERVICE}. The runner is an
+* ordinary consumer whose lazy config waits for that service.
+* @module @hydraharness/harness-headless/startup
+*/
+/** Stable Cordis plugin name. */
+const name = "headless-startup";
+/** Services required before the task can be resolved. */
+const inject = ["cmdlineArgs"];
+/** Service provided by this plugin and injected by the one-shot runner. */
+const HEADLESS_STARTUP_SERVICE = "headlessStartup";
+/**
+* This app's command: the task positional, its description, and its help text.
+* @returns a fresh program, so one process can parse more than once (tests).
+*/
+function headlessCommand() {
+	return new Command().name("hydra --profile headless").description("Answer one task, print the final assistant message, and exit.").helpOption("-h, --help", "show this help").argument("[task...]", "the task text; multiple words are joined by spaces").addHelpText("after", `
+Examples:
+  hydra --profile headless "run the tests"     answer one task and exit
+`);
+}
+/**
+* Parse and provide the one-shot task as an ordinary Cordis service. The
+* command's action publishes the task; a missing or whitespace-only task is a
+* usage error, so on rejection (and on `--help`) nothing is provided.
+* @param ctx - plugin context carrying the command line.
+*/
+function apply(ctx) {
+	const program = headlessCommand();
+	program.action(() => {
+		const task = program.args.join(" ");
+		if (task.trim() === "") program.error("error: a task is required, for example: hydra --profile headless \"run the tests\"");
+		ctx.provide(HEADLESS_STARTUP_SERVICE, { task });
+	});
+	parseCmdline(ctx, program);
+}
+//#endregion
+export { HEADLESS_STARTUP_SERVICE, apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @hydraharness/harness-headless — one-shot direct Agent driver. The bundle patch
+ * rides over @hydraharness/harness-base without Host, HTTP, or browser plugins; this runner
+ * creates one Agent through the core registry, drives the task to quiescence,
+ * flushes its Session, prints the final assistant text, and exits.
+ *
+ * @module @hydraharness/harness-headless
+ */
+import type { Context } from '@hydraharness/cordis';
+import z from '@hydraharness/schemastery';
+/** Stable Cordis plugin name. */
+export declare const name = "headless-runner";
+/** Core services required before the one-shot turn can start. */
+export declare const inject: string[];
+/** Plugin config: the task resolved from this app's injected provider service. */
+export interface Config {
+    /** The prompt text for the single run. */
+    task: string;
+}
+export declare const Config: z<Config>;
+/** Process-facing effects of one run: output streams plus the launcher's bounded exit request. */
+interface HeadlessIo {
+    stdout: {
+        write(chunk: string): unknown;
+    };
+    stderr: {
+        write(chunk: string): unknown;
+    };
+    /** Request process exit with `code` after the tree disposes. */
+    exit(code: number): void;
+}
+/** The process streams the runner writes to; tests substitute captures. */
+export declare const internals: {
+    stdout: HeadlessIo['stdout'];
+    stderr: HeadlessIo['stderr'];
+};
+/**
+ * Mount the one-shot direct driver.
+ * @param ctx - plugin context carrying core services and the launcher-provided exit request.
+ * @param config - validated task config.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-headless`.
+ * @module @hydraharness/harness-headless/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "headless-invariant";
+/** Service required before the companion can register. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/startup.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The one-shot app's command-line provider: it parses the task positional and
+ * `--help`, then publishes {@link HEADLESS_STARTUP_SERVICE}. The runner is an
+ * ordinary consumer whose lazy config waits for that service.
+ * @module @hydraharness/harness-headless/startup
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Stable Cordis plugin name. */
+export declare const name = "headless-startup";
+/** Services required before the task can be resolved. */
+export declare const inject: string[];
+/** Service provided by this plugin and injected by the one-shot runner. */
+export declare const HEADLESS_STARTUP_SERVICE = "headlessStartup";
+/** What the runner row reads from {@link HEADLESS_STARTUP_SERVICE}. */
+export interface HeadlessStartupValues {
+    /** The task text this invocation asked for. */
+    task: string;
+}
+/**
+ * Parse and provide the one-shot task as an ordinary Cordis service. The
+ * command's action publishes the task; a missing or whitespace-only task is a
+ * usage error, so on rejection (and on `--help`) nothing is provided.
+ * @param ctx - plugin context carrying the command line.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=startup.d.ts.map

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@hydraharness/harness-headless",
+  "description": "The hydra one-shot bundle: a direct core Agent/Session runner over hydra-base with no Host, HTTP, or browser layer",
+  "version": "0.1.1-rc.6",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/bundle/headless"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./startup": {
+      "types": "./lib/types/startup.d.ts",
+      "default": "./lib/startup.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/startup.js",
+    "cordis.patch.yml",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "hydra": {
+    "plugin": {
+      "application": "Run a single task from the command line and exit after the final answer."
+    },
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "@hydraharness/harness-cmdline": "^0.1.1-rc.6",
+    "@hydraharness/schemastery": "^3.18.2",
+    "@hydraharness/harness-code-runtime-worker-thread": "^0.1.1-rc.6"
+  },
+  "peerDependencies": {
+    "@hydraharness/cordis-plugin-loader": "^1.0.3",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-agent": "^0.1.1-rc.6",
+    "@hydraharness/harness-agent-default-model": "^0.1.1-rc.6",
+    "@hydraharness/harness-session": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-llm": "^0.1.1-rc.6"
+  },
+  "devDependencies": {
+    "@hydraharness/cordis-plugin-loader": "^1.0.3",
+    "@hydraharness/harness-agent-default-model": "^0.1.1-rc.6",
+    "@hydraharness/harness-agent": "^0.1.1-rc.6",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-llm": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-session": "^0.1.1-rc.6"
+  }
+}