@hydraharness/harness-sdk-jsonrpc-demo 0.1.1-rc.10

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,31 @@
+# @hydraharness/harness-sdk-jsonrpc-demo
+
+Bin-only app that boots an external `cordis.yml`; its [`jsonrpc`](../../sdk/server/README.md) entry serves SDK clients over newline-delimited stdio. The config composes the spine, backends, and serving plugin. The published `hydra-jsonrpc-agent` bin resolves bare plugins from the configuration project. The Python SDK's `hydra-jsonrpc-agent-pkg` [single-executable runtime](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) uses `lib/packaged-bin.js` instead: packaged bare plugins resolve from its closed runtime tree, while relative plugins remain configuration-relative.
+
+## Config discovery
+
+The first non-empty channel wins: `$HYDRA_CORDIS_CONFIG`, then positional `argv[2]`. If neither names an existing file, the bin prints one-line usage to stderr and exits 1; there is no working-directory or built-in fallback. [`@hydraharness/harness-app-boot`](../../boot/app-boot/README.md) makes plugin load failures fatal. This protocol does not use `HYDRA_SNAPSHOT`.
+
+A config without `@hydraharness/harness-sdk-jsonrpc-server` is valid and serves nothing; the bin does not designate a server plugin.
+
+## Exit lifecycle
+
+stdin EOF and `SIGTERM` dispose the root to quiescence and exit 0; `SIGINT` exits 130 after the same disposal. EOF may cut off an in-flight turn as documented in the [distribution Agent Note](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md). The `jsonrpc` plugin owns response-before-exit protocol shutdown; both paths are idempotent and safe to race.
+
+## stdout is the protocol
+
+stdout carries only JSON-RPC frames. The bin and boot guards diagnose on stderr, and the config must omit stdout loggers.
+
+## Model Experience
+
+Indirectly, through the plugins loaded from the external `cordis.yml`, which own every model-bound prompt, schema, message, and result; this bin adds none of its own.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **The bin cannot prove that the config serves JSON-RPC** — a valid config with no `@hydraharness/harness-sdk-jsonrpc-server` entry boots successfully and serves nothing.
+- **No built-in or default config exists** — every launch must provide `HYDRA_CORDIS_CONFIG` or a positional path, and deployment owns the complete plugin tree and stdout discipline.
+- **stdin EOF cuts off in-flight work** — client disappearance disposes the root immediately; callers that need orderly completion use the protocol-level `shutdown` request.

package/lib/bin.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { boot, installFailLoud, loadEnv, resolveConfigPath } from "@hydraharness/harness-app-boot";
+//#region lib/types/runner.js
+/**
+* Shared process lifecycle for the generic and closed-runtime JSON-RPC bins.
+*
+* @module @hydraharness/harness-sdk-jsonrpc-demo/runner
+*/
+/* v8 ignore start -- composition over tested app-boot/jsonrpc and executable acceptance paths */
+const NAME = "hydra-jsonrpc-agent";
+/**
+* Boot the explicitly selected external configuration and own process exit.
+* @param bareModuleBaseUrl - optional installed-runtime base for bare plugins;
+* omit it when the configuration project owns its plugin packages.
+* @returns after process handlers are installed; process lifetime then belongs
+* to stdin and signal events.
+*/
+async function runJsonrpcAgent(bareModuleBaseUrl) {
+	installFailLoud(NAME);
+	loadEnv(NAME);
+	const fromEnv = process.env["HYDRA_CORDIS_CONFIG"];
+	const fromArgv = process.argv[2];
+	const requested = fromEnv !== void 0 && fromEnv !== "" ? fromEnv : fromArgv !== void 0 && fromArgv !== "" ? fromArgv : void 0;
+	const configPath = requested === void 0 ? void 0 : resolveConfigPath(requested, void 0);
+	if (configPath === void 0 || !existsSync(configPath)) {
+		process.stderr.write(`usage: ${NAME} <path/to/cordis.yml> (or set HYDRA_CORDIS_CONFIG=<path>, which wins); the config is required — there is no built-in fallback\n`);
+		process.exit(1);
+	}
+	const ctx = await boot(NAME, configPath, void 0, void 0, bareModuleBaseUrl);
+	let exiting = false;
+	async function disposeAndExit(code) {
+		if (exiting) return;
+		exiting = true;
+		try {
+			await ctx.fiber.dispose();
+		} finally {
+			process.exit(code);
+		}
+	}
+	process.stdin.on("end", () => {
+		disposeAndExit(0);
+	});
+	process.on("SIGTERM", () => {
+		disposeAndExit(0);
+	});
+	process.on("SIGINT", () => {
+		disposeAndExit(130);
+	});
+}
+/* v8 ignore stop */
+//#endregion
+//#region lib/types/bin.js
+/**
+* Generic JSON-RPC agent bin. External configurations own their bare plugin
+* packages; the packaged runtime uses `packaged-bin.ts` instead.
+*
+* @module @hydraharness/harness-sdk-jsonrpc-demo/bin
+*/
+await runJsonrpcAgent();
+//#endregion
+export {};

package/lib/index.js

@@ -0,0 +1 @@
+export {};

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-sdk-jsonrpc-demo`.
+* @module @hydraharness/harness-sdk-jsonrpc-demo/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-sdk-jsonrpc-demo";
+/** Cordis companion plugin name. */
+const name = "sdk-jsonrpc-demo-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this composition package owns no independent event stream or mutable data;
+* Loader and built-entry tests cover its wiring.
+*/
+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/packaged-bin.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { boot, installFailLoud, loadEnv, resolveConfigPath } from "@hydraharness/harness-app-boot";
+//#region lib/types/runner.js
+/**
+* Shared process lifecycle for the generic and closed-runtime JSON-RPC bins.
+*
+* @module @hydraharness/harness-sdk-jsonrpc-demo/runner
+*/
+/* v8 ignore start -- composition over tested app-boot/jsonrpc and executable acceptance paths */
+const NAME = "hydra-jsonrpc-agent";
+/**
+* Boot the explicitly selected external configuration and own process exit.
+* @param bareModuleBaseUrl - optional installed-runtime base for bare plugins;
+* omit it when the configuration project owns its plugin packages.
+* @returns after process handlers are installed; process lifetime then belongs
+* to stdin and signal events.
+*/
+async function runJsonrpcAgent(bareModuleBaseUrl) {
+	installFailLoud(NAME);
+	loadEnv(NAME);
+	const fromEnv = process.env["HYDRA_CORDIS_CONFIG"];
+	const fromArgv = process.argv[2];
+	const requested = fromEnv !== void 0 && fromEnv !== "" ? fromEnv : fromArgv !== void 0 && fromArgv !== "" ? fromArgv : void 0;
+	const configPath = requested === void 0 ? void 0 : resolveConfigPath(requested, void 0);
+	if (configPath === void 0 || !existsSync(configPath)) {
+		process.stderr.write(`usage: ${NAME} <path/to/cordis.yml> (or set HYDRA_CORDIS_CONFIG=<path>, which wins); the config is required — there is no built-in fallback\n`);
+		process.exit(1);
+	}
+	const ctx = await boot(NAME, configPath, void 0, void 0, bareModuleBaseUrl);
+	let exiting = false;
+	async function disposeAndExit(code) {
+		if (exiting) return;
+		exiting = true;
+		try {
+			await ctx.fiber.dispose();
+		} finally {
+			process.exit(code);
+		}
+	}
+	process.stdin.on("end", () => {
+		disposeAndExit(0);
+	});
+	process.on("SIGTERM", () => {
+		disposeAndExit(0);
+	});
+	process.on("SIGINT", () => {
+		disposeAndExit(130);
+	});
+}
+/* v8 ignore stop */
+//#endregion
+//#region lib/types/packaged-bin.js
+/**
+* Closed-runtime JSON-RPC agent bin. Bare plugins resolve from the installed
+* runtime closure while relative plugins remain configuration-relative.
+*
+* @module @hydraharness/harness-sdk-jsonrpc-demo/packaged-bin
+*/
+/* v8 ignore next -- exercised through the built Python runtime carriers */
+await runJsonrpcAgent(import.meta.url);
+//#endregion
+export {};

package/lib/types/bin.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Generic JSON-RPC agent bin. External configurations own their bare plugin
+ * packages; the packaged runtime uses `packaged-bin.ts` instead.
+ *
+ * @module @hydraharness/harness-sdk-jsonrpc-demo/bin
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Bin-only app package: its generic and packaged entries discover an external
+ * `cordis.yml` and own process exit. This module exports no composition plugin;
+ * the config chooses whether to load the
+ * {@link @hydraharness/harness-sdk-jsonrpc-server} serving plugin.
+ *
+ * @module @hydraharness/harness-sdk-jsonrpc-demo
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-sdk-jsonrpc-demo`.
+ * @module @hydraharness/harness-sdk-jsonrpc-demo/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "sdk-jsonrpc-demo-invariant";
+/** Service required before the companion can reserve package ownership. */
+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/packaged-bin.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Closed-runtime JSON-RPC agent bin. Bare plugins resolve from the installed
+ * runtime closure while relative plugins remain configuration-relative.
+ *
+ * @module @hydraharness/harness-sdk-jsonrpc-demo/packaged-bin
+ */
+export {};
+//# sourceMappingURL=packaged-bin.d.ts.map

package/lib/types/runner.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared process lifecycle for the generic and closed-runtime JSON-RPC bins.
+ *
+ * @module @hydraharness/harness-sdk-jsonrpc-demo/runner
+ */
+/**
+ * Boot the explicitly selected external configuration and own process exit.
+ * @param bareModuleBaseUrl - optional installed-runtime base for bare plugins;
+ * omit it when the configuration project owns its plugin packages.
+ * @returns after process handlers are installed; process lifetime then belongs
+ * to stdin and signal events.
+ */
+export declare function runJsonrpcAgent(bareModuleBaseUrl?: string): Promise<void>;
+//# sourceMappingURL=runner.d.ts.map

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@hydraharness/harness-sdk-jsonrpc-demo",
+  "description": "Bin that boots an external Cordis config for the stdio JSON-RPC SDK runtime",
+  "version": "0.1.1-rc.10",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong2010/Hydra-Harness.git",
+    "directory": "packages/examples/jsonrpc-demo"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "bin": {
+    "hydra-jsonrpc-agent": "lib/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./bin": {
+      "types": "./lib/types/bin.d.ts",
+      "default": "./lib/bin.js"
+    },
+    "./packaged-bin": {
+      "types": "./lib/types/packaged-bin.d.ts",
+      "default": "./lib/packaged-bin.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/bin.js",
+    "lib/packaged-bin.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@hydraharness/harness-app-boot": "^0.1.1-rc.10"
+  },
+  "peerDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.10",
+    "@hydraharness/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.10",
+    "@hydraharness/cordis": "^4.0.2"
+  }
+}