@hydraharness/harness-optional-plugins 0.0.0-stage → 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

@@ -1,3 +1,16 @@
-# Temporary Holding Version
+# Optional plugin policy
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `optional-plugins.enabled` preference defaults to On and preserves individual enablement records. Consumers acquire a completion lease before starting optional work. Off rejects new work immediately. Lifetime owners await `drain()` before removing contributions; enabling plugins again cancels pending removal. Required plugins remain available independently of the restart classification `pluginType`.
+
+
+## Model Experience
+
+Indirectly, through the owning optional plugins whose contributions and new invocations this policy controls.
+
+#### KV Cache effect
+
+Disabling optional tools can change the next request's tool context; each owning plugin controls its rendered contribution.
+
+## Known Limitations and Deferred Work
+
+- Work admitted before disablement finishes under its existing lease. Turning the common policy back on preserves individual choices.

package/lib/index.js

@@ -0,0 +1,67 @@
+import { Service } from "@hydraharness/cordis";
+import z from "@hydraharness/schemastery";
+import { settingsNamespace } from "@hydraharness/harness-settings";
+//#region lib/types/index.js
+/** Global optional-plugin invocation gate; lifetime owners drain before removing contributions. */
+/** Immediate disablement and leases for operations that may already be running. */
+var OptionalPluginPolicy = class extends Service {
+	static inject = ["settings"];
+	settings;
+	active = 0;
+	waiters = /* @__PURE__ */ new Set();
+	listeners = /* @__PURE__ */ new Set();
+	/**
+	* @param ctx - global settings and owning plugin lifetime.
+	*/
+	constructor(ctx) {
+		super(ctx, "optionalPlugins");
+		this.settings = ctx.settings.register(settingsNamespace("optional-plugins"), z.object({ enabled: z.boolean().default(true) }));
+		ctx.effect(() => this.settings.watch((value) => {
+			if (value.enabled) this.releaseWaiters();
+			for (const listener of this.listeners) listener(value.enabled);
+		}), "optional-plugins: accepted policy");
+	}
+	/** Committed policy, read synchronously before every invocation. */
+	get enabled() {
+		return this.settings.get().enabled;
+	}
+	/** Rejects new optional work while disabled and tracks work already admitted.
+	* @returns an idempotent completion lease; rejects a new operation immediately while disabled.
+	*/
+	acquire() {
+		if (!this.enabled) throw new Error("Optional plugins are disabled");
+		this.active += 1;
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			this.active -= 1;
+			if (this.active === 0) this.releaseWaiters();
+		};
+	}
+	/** Waits for owned work before a contribution can be removed.
+	* @returns settlement when existing optional operations finish, or the user enables plugins again.
+	*/
+	drain() {
+		if (this.active === 0 || this.enabled) return Promise.resolve();
+		return new Promise((resolve) => {
+			this.waiters.add(resolve);
+		});
+	}
+	/** Observes accepted common-policy changes.
+	* @param listener - callback after an accepted policy change.
+	* @returns subscription disposer.
+	*/
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	releaseWaiters() {
+		for (const waiter of this.waiters) waiter();
+		this.waiters.clear();
+	}
+};
+//#endregion
+export { OptionalPluginPolicy, OptionalPluginPolicy as default };

package/lib/invariant.js

@@ -0,0 +1,17 @@
+//#region lib/types/invariant.js
+/** Cordis companion plugin name. */
+const name = "optional-plugins-invariant";
+/** Service required before reserving package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: admitted operations return private idempotent leases; consumers own their operation streams, so
+* the lease counter has no independent membership stream to compare.
+*/
+const install = () => {};
+/** Registers this package's invariant ownership.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns registration disposer.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register("@hydraharness/harness-optional-plugins", install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,37 @@
+/** Global optional-plugin invocation gate; lifetime owners drain before removing contributions. */
+import { Service, type Context } from '@hydraharness/cordis';
+declare module '@hydraharness/cordis' {
+    interface Context {
+        optionalPlugins: OptionalPluginPolicy;
+    }
+}
+/** Immediate disablement and leases for operations that may already be running. */
+export declare class OptionalPluginPolicy extends Service {
+    static inject: string[];
+    private readonly settings;
+    private active;
+    private readonly waiters;
+    private readonly listeners;
+    /**
+   * @param ctx - global settings and owning plugin lifetime.
+   */
+    constructor(ctx: Context);
+    /** Committed policy, read synchronously before every invocation. */
+    get enabled(): boolean;
+    /** Rejects new optional work while disabled and tracks work already admitted.
+   * @returns an idempotent completion lease; rejects a new operation immediately while disabled.
+   */
+    acquire(): () => void;
+    /** Waits for owned work before a contribution can be removed.
+   * @returns settlement when existing optional operations finish, or the user enables plugins again.
+   */
+    drain(): Promise<void>;
+    /** Observes accepted common-policy changes.
+   * @param listener - callback after an accepted policy change.
+   * @returns subscription disposer.
+   */
+    subscribe(listener: (enabled: boolean) => void): () => void;
+    private releaseWaiters;
+}
+export default OptionalPluginPolicy;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

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

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@hydraharness/harness-optional-plugins",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1-rc.10",
+  "description": "Immediate optional-plugin invocation policy and draining lifecycle",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong2010/Hydra-Harness.git",
+    "directory": "packages/host/optional-plugins"
+  },
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "hydra": {
+    "plugin": {
+      "application": "Suspend optional plugins without changing their individual choices."
+    }
+  },
+  "peerDependencies": {
+    "@hydraharness/harness-settings": "^0.1.1-rc.10",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.10"
+  },
+  "dependencies": {
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-settings": "^0.1.1-rc.10",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.10",
+    "@hydraharness/cordis": "^4.0.2"
+  }
 }