@hydraharness/harness-command-feedback 0.0.0-stage → 0.1.1-rc.5

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,71 @@
-# Temporary Holding Version
+# @hydraharness/harness-command-feedback
 
-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.
+Trigger-independent session feedback plus human-facing `/feedback` capture. The package exports `recordFeedback(session, text)`, which appends one log-only `feedback/record` event. Its plugin registers one global command through [`ctx.commands`](../../interaction/commands/README.md), so every composed command adapter discovers it; the shipped Web client executes it without a model turn.
+
+## Command contract
+
+| Input | Result |
+|---|---|
+| `/feedback <text>` | Append `feedback/record` and acknowledge with `Feedback recorded for session {sessionId}`, `Anonymous user: {userId}`, plus the session-sharing disclosure. |
+| `/feedback` | Return a direct usage error. Whitespace-only input is treated as empty. |
+
+Surrounding whitespace is discarded, but feedback is otherwise unparsed: no truncation, case folding, or control words. Text that looks like another command, such as `/feedback /plan felt slow`, is feedback content. Repeated commands each produce their own event; nothing is replaced or merged.
+
+## Session-sharing disclosure
+
+The acknowledgement names the receiving session id and reports how that session is shared, read from the mounted [`telemetry`](../../session/session-telemetry/README.md) service through the plugin context (`ctx.get('telemetry')`, never a declared injection). The disclosure is one sentence chosen from the backend's [`SessionTelemetrySharingStatus`](../../session/session-telemetry/README.md):
+
+| Disclosed status | Acknowledgement sentence |
+|---|---|
+| `full` | `Session sharing is enabled.` |
+| `feedback-only` | `Session sharing is feedback-gated; recording feedback releases the session prefix for sharing.` |
+| `disabled` | `Session sharing is disabled.` |
+| no service | `Session sharing is not configured.` |
+
+The disclosure states the deployment's current sharing policy only; it never promises delivery or retention. With `full` or `feedback-only`, records are handed to the backend's non-blocking enqueue and the SDK owns batching, retry, and loss policy, so the sentence claims nothing about what reached a collector; `disabled` claims nothing about future reconfiguration. The disclosure adds no event and never enters the model surface.
+
+## What this plugin does and does not do
+
+`recordFeedback(session, text)` is the command-independent write path. It rejects empty normalized text and appends `feedback/record { text }`; a different UI, hook, or host integration can call it without constructing a slash command. The `/feedback` handler uses that producer and starts no model work. The optional [`@hydraharness/harness-session-telemetry-otel`](../../session/session-telemetry-otel) consumer observes the event without changing its capture contract.
+
+The feedback text appears in exactly one durable payload: `feedback/record`. [`@hydraharness/harness-commands`](../../interaction/commands/README.md) still appends its generic `command/run` / `command/done` pairing, but this definition sets `recordInput: false`, so `command/run` omits `args`; the paired `command/done` carries only the outcome. All three events are log-only and absent from the ordered surface, `deriveMessages()`, and model requests. These appends start persistence's ordinary eager drain, but neither producer forces `session/flush`, so acknowledgement means the feedback is in the log, not that it has reached disk. The acknowledgement identifies both the receiving session and the [shared anonymous user](../../identity/anonymous-user-id/); the first accepted feedback for a harness home can create `$HYDRA_HOME/.anonymous-user-id`. Rejected empty input leaves only the command pairing settled as `kind: 'error'`, with no `feedback/record` and no user-id lookup.
+
+The event is authoritative rather than the command record because feedback may arrive through a trigger other than `/feedback`. Keeping the payload out of `command/run` avoids two records carrying the same text.
+
+## Composition
+
+The producer injects only `commands`. A custom app mounts the registry plus this plugin:
+
+```yaml
+- id: commands
+  name: '@hydraharness/harness-commands'
+- id: command-feedback
+  name: '@hydraharness/harness-command-feedback'
+```
+
+The shipped `hydra` base mounts this command unconditionally; it has no configuration and no dependency on the persisted-goal stack. The Web client exposes it through the command adapter. Headless mode, ACP automation, and JSON-RPC do not provide a command adapter, so they do not expose it.
+
+## Model Experience
+
+### Human `/feedback` capture
+
+#### What the model sees
+
+Nothing. The slash input, `feedback/record`, and the acknowledgement are absent from model requests. The feedback event and registry lifecycle records are log-only and carry no `surfaceOp`, so they never reach the ordered surface, `deriveMessages()`, or a system prompt. Recording feedback during a turn does not change that turn's remaining requests.
+
+#### Token effect
+
+Zero direct token effect. Neither an accepted entry nor a usage error adds model tokens, in the recording turn or any later one.
+
+#### KV Cache effect
+
+Independent of the model request path. Recording appends to the session log only, leaving an already-reusable request prefix untouched. Nothing this package contributes can invalidate cache reuse.
+
+## Known Limitations and Deferred Work
+
+- **No feedback retrieval or management surface** — the optional OTel plugin uses the event only as a sharing trigger. There is no retrieval, aggregation, categorization, or model-facing tool for `feedback/record`.
+- **No structured fields** — an entry is one free-text string with no category, severity, or referenced-event link, so feedback cannot be filtered by subject without re-reading its text.
+- **No amend or withdraw** — the session log is append-only and this package adds no tombstone, so a mistaken entry stays recorded and can only be superseded by a later one.
+- **No explicit durability barrier** — the acknowledgement follows the append, not a flush, so an entry recorded immediately before a crash can be lost with any other unflushed tail. Feedback is not worth forcing a synchronous disk write for; a consumer that needs one awaits `ctx.sessions.flush(session)`.
+- **No visible acknowledgement on a fresh session** — the web transcript renders command rows only once a session is active, so `/feedback` on a still-blank session records the event but shows no acknowledgement row. Recording feedback after the first message renders normally.
+- **Web only among the shipped entry points** — headless mode, ACP automation, and JSON-RPC do not provide a command adapter, so `/feedback` is unavailable there.

package/lib/index.js

@@ -0,0 +1,83 @@
+import { getOrCreateAnonymousUserId } from "@hydraharness/harness-anonymous-user-id";
+//#region lib/types/index.js
+/**
+* Session feedback event plus the human-facing `/feedback` producer. Recording
+* appends one authoritative log-only event and does not start model work. The
+* append is eager but unflushed, so acknowledgement reports that the entry is
+* logged, not that it reached disk.
+* @module @hydraharness/harness-command-feedback
+*/
+const name = "command-feedback";
+const inject = ["commands"];
+const USAGE = "Usage: /feedback <text>";
+/** Fail closed when a future sharing status reaches the sentence switch. */
+/* v8 ignore next 3 -- only the ignored default arm calls this; the closed union cannot reach it via the public API. */
+function assertNever(value) {
+	throw new Error(`command-feedback: unsupported sharing status ${JSON.stringify(value)}`);
+}
+/** The acknowledgement's sharing sentence for a disclosed policy. */
+function sharingSentence(sharing) {
+	switch (sharing) {
+		case "full": return "Session sharing is enabled.";
+		case "feedback-only": return "Session sharing is feedback-gated; recording feedback releases the session prefix for sharing.";
+		case "disabled": return "Session sharing is disabled.";
+		/* v8 ignore next 2 -- the seam's closed union cannot reach the default; a future status must be given a sentence here. */
+		default: return assertNever(sharing);
+	}
+}
+/**
+* The sharing disclosure appended to the acknowledgement: the mounted
+* backend's disclosed policy, or a "not configured" notice when no backend
+* is mounted. Read through the plugin context so the command still works
+* when the telemetry service is absent.
+* @param telemetry - the mounted telemetry service, or undefined.
+* @returns one sentence describing this session's sharing policy.
+*/
+function sharingDisclosure(telemetry) {
+	if (telemetry === void 0) return "Session sharing is not configured.";
+	return sharingSentence(telemetry.sharing);
+}
+/**
+* Record feedback independently of any UI trigger.
+* @param session - session the feedback describes.
+* @param text - human-authored feedback; surrounding whitespace is discarded.
+* @throws {TypeError} when the normalized text is empty.
+*/
+function recordFeedback(session, text) {
+	const normalized = text.trim();
+	if (normalized.length === 0) throw new TypeError("feedback text must not be empty");
+	session.append("feedback/record", { text: normalized });
+}
+/**
+* Validate, record, and acknowledge one feedback entry. Returning an error
+* leaves no `feedback/record` event.
+* @param invocation - receiving agent, raw command input, and UI cancellation.
+* @param ctx - plugin context used to read the optional telemetry service.
+* @returns an acknowledgement containing the receiving session and anonymous
+* user ids plus the session-sharing disclosure, or a usage error when no
+* feedback text was supplied.
+*/
+function executeFeedbackCommand(invocation, ctx) {
+	if (invocation.rawInput.trim().length === 0) return {
+		kind: "error",
+		text: `Feedback text is required. ${USAGE}`
+	};
+	recordFeedback(invocation.agent.session, invocation.rawInput);
+	const telemetry = ctx.get("sessionTelemetry");
+	return {
+		kind: "success",
+		text: `Feedback recorded for session ${invocation.agent.session.id}\nAnonymous user: ${getOrCreateAnonymousUserId()}. ${sharingDisclosure(telemetry)}`
+	};
+}
+/** Register the global `/feedback` command for every composed command adapter. */
+function apply(ctx) {
+	ctx.commands.register({
+		name: "feedback",
+		description: "record feedback about this session",
+		input: { hint: "<text>" },
+		recordInput: false,
+		handler: (invocation) => executeFeedbackCommand(invocation, ctx)
+	});
+}
+//#endregion
+export { apply, inject, name, recordFeedback };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-command-feedback`.
+* @module @hydraharness/harness-command-feedback/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-command-feedback";
+/** Cordis companion plugin name. */
+const name = "command-feedback-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: each `feedback/record` is an independent append-only
+* fact with no cross-event or mutable-data relationship.
+*/
+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/types/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Session feedback event plus the human-facing `/feedback` producer. Recording
+ * appends one authoritative log-only event and does not start model work. The
+ * append is eager but unflushed, so acknowledgement reports that the entry is
+ * logged, not that it reached disk.
+ * @module @hydraharness/harness-command-feedback
+ */
+import type { Context } from '@hydraharness/cordis';
+import type { Session } from '@hydraharness/harness-session';
+export declare const name = "command-feedback";
+export declare const inject: string[];
+declare module '@hydraharness/harness-session/types' {
+    interface SessionEventMap {
+        /**
+         * One recorded human remark about this session. Log-only and independent
+         * of its trigger; it never enters model context or derived history.
+         */
+        'feedback/record': {
+            text: string;
+        };
+    }
+}
+/**
+ * Record feedback independently of any UI trigger.
+ * @param session - session the feedback describes.
+ * @param text - human-authored feedback; surrounding whitespace is discarded.
+ * @throws {TypeError} when the normalized text is empty.
+ */
+export declare function recordFeedback(session: Session, text: string): void;
+/** Register the global `/feedback` command for every composed command adapter. */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-command-feedback`.
+ * @module @hydraharness/harness-command-feedback/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "command-feedback-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/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@hydraharness/harness-command-feedback",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Log-only session feedback producer and human-facing slash command",
+  "hydra": {
+    "plugin": {
+      "application": "Record session feedback through a slash command."
+    }
+  },
+  "version": "0.1.1-rc.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/feedback/command-feedback"
+  },
+  "type": "module",
+  "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"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-commands": "^0.1.1-rc.5",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5",
+    "@hydraharness/harness-session": "^0.1.1-rc.5",
+    "@hydraharness/harness-session-telemetry": "^0.1.1-rc.5",
+    "@hydraharness/harness-anonymous-user-id": "^0.1.1-rc.5",
+    "@hydraharness/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@hydraharness/cordis-plugin-loader": "^1.0.3",
+    "@hydraharness/harness-commands": "^0.1.1-rc.5",
+    "@hydraharness/harness-agent": "^0.1.1-rc.5",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5",
+    "@hydraharness/cordis-plugin-include": "^1.0.7",
+    "@hydraharness/harness-llm": "^0.1.1-rc.5",
+    "@hydraharness/harness-session-telemetry": "^0.1.1-rc.5",
+    "@hydraharness/harness-session": "^0.1.1-rc.5",
+    "@hydraharness/harness-anonymous-user-id": "^0.1.1-rc.5",
+    "@hydraharness/cordis": "^4.0.2"
+  }
 }