@stackstackstack/dsh-command-feedback 0.1.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.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/feedback/command-feedback/README.md
+README.md: 3882d2a28c6f6f5165e6e1b432027aea3f982c21
+README.zh.md: 2c745938c587d685138a60d970b47884a5943d0a

package/README.md

@@ -0,0 +1,73 @@
+# @stackstackstack/dsh-command-feedback
+
+English | [中文](README.zh.md)
+
+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 [`dsh-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`. [`dsh-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 `$DSH_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: '@stackstackstack/dsh-commands'
+- id: command-feedback
+  name: '@stackstackstack/dsh-command-feedback'
+```
+
+The shipped `dsh` 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/README.zh.md

@@ -0,0 +1,73 @@
+# @stackstackstack/dsh-command-feedback
+
+[English](README.md) | 中文
+
+与触发方式无关的会话反馈，以及面向用户的 `/feedback` 采集。本包导出 `recordFeedback(session, text)`；该函数会追加一个仅写入日志的 `feedback/record` 事件。该插件通过 [`ctx.commands`](../../interaction/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现它；随附的 Web 客户端无需模型轮次即可执行。
+
+## 命令约定
+
+| 输入 | 结果 |
+|---|---|
+| `/feedback <text>` | 追加 `feedback/record`，并以 `Feedback recorded for session {sessionId}`、`Anonymous user: {userId}` 加会话共享披露确认。 |
+| `/feedback` | 返回一个直接用法错误。仅含空白的输入视为空输入。 |
+
+前后空白会被丢弃，但除此之外，反馈内容不会被解析：不进行截断或大小写折叠，也不识别控制词。看起来像另一个命令的文本（例如 `/feedback /plan felt slow`）就是反馈内容。重复执行命令时，每次都会产生一个事件；不会发生替换或合并。
+
+## 会话共享披露
+
+确认文本会点名接收会话的 id，并报告该会话如何被共享；该信息通过插件上下文（`ctx.get('telemetry')`，绝不是声明的注入）从已挂载的 [`telemetry`](../../session/session-telemetry/README.md) 服务读取。披露是依据后端 [`SessionTelemetrySharingStatus`](../../session/session-telemetry/README.md) 选择的一句话：
+
+| 披露的状态 | 确认文本中的句子 |
+|---|---|
+| `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.` |
+| 无服务 | `Session sharing is not configured.` |
+
+披露只陈述部署当前的共享策略，绝不承诺投递或留存：在 `full` 或 `feedback-only` 下，记录被交给后端的非阻塞入队，批处理、重试与丢失策略归 SDK 负责，因此句子不声称任何内容已到达采集端；`disabled` 也不声称未来不会重新配置。披露不新增任何事件，也绝不会进入模型 surface。
+
+## 本插件做什么、不做什么
+
+`recordFeedback(session, text)` 是不依赖命令的写入路径。它拒绝规范化后为空的文本，并追加 `feedback/record { text }`；其他 UI、钩子或 host 集成无需构造斜杠命令即可调用它。`/feedback` 处理器通过该函数写入，且不启动任何模型工作。可选的 [`dsh-session-telemetry-otel`](../../session/session-telemetry-otel) 消费方会观察该事件，但不改变它的采集约定。
+
+反馈文本只出现在一个持久载荷中：`feedback/record`。[`dsh-commands`](../../interaction/commands/README.md) 仍会追加通用的 `command/run` / `command/done` 配对，但此定义设置了 `recordInput: false`，因此 `command/run` 会省略 `args`；配对的 `command/done` 只携带结果。三个事件都仅写入日志，不出现在有序 surface、`deriveMessages()` 以及模型请求中。这些追加会启动持久化的常规即时排空，但两个生产方都不会强制 `session/flush`，因此确认文本表示反馈已进入日志，而不表示它已经落盘。确认文本同时标明接收反馈的会话和[共享匿名用户](../../identity/anonymous-user-id/)；对于某个 harness home，首次接受反馈时可能创建 `$DSH_HOME/.anonymous-user-id`。被拒绝的空输入只会留下以 `kind: 'error'` 结算的命令配对，不会产生 `feedback/record`，也不会查找用户 id。
+
+权威记录是该事件，而不是命令记录，因为反馈可能来自 `/feedback` 之外的触发方式。让载荷不进入 `command/run`，可避免两条记录携带相同文本。
+
+## 组合
+
+生产方只注入 `commands`。自定义应用挂载注册表以及本插件：
+
+```yaml
+- id: commands
+  name: '@stackstackstack/dsh-commands'
+- id: command-feedback
+  name: '@stackstackstack/dsh-command-feedback'
+```
+
+随附的 `dsh` 基础组合无条件挂载此命令；它没有配置，也不依赖持久化 goal 栈。Web 客户端通过命令适配器暴露该命令。无头模式、ACP（Agent Client Protocol）自动化和 JSON-RPC 不提供命令适配器，因此不会暴露它。
+
+## 模型体验
+
+### 用户 `/feedback` 采集
+
+#### 模型看到的内容
+
+无。斜杠输入、`feedback/record` 以及确认文本都不出现在模型请求中。反馈事件和注册表生命周期记录仅写入日志且不携带 `surfaceOp`，因此它们绝不会进入有序 surface、`deriveMessages()` 或系统提示词。在某个轮次中记录反馈不会改变该轮次剩余的请求。
+
+#### Token 影响
+
+无直接 token 影响。无论是已接受的条目还是用法错误，都不会在记录所在轮次或此后任何轮次增加模型 token。
+
+#### KV Cache 影响
+
+与模型请求路径无关。记录只追加到会话日志，不触碰已经可复用的请求前缀。本包贡献的任何内容都不会使缓存复用失效。
+
+## 已知限制与暂缓工作
+
+- **没有反馈检索或管理 surface**：可选的 OTel 插件仅将该事件用作共享触发器。本包不为 `feedback/record` 提供检索、聚合、分类或面向模型的工具。
+- **没有结构化字段**：一条条目就是一个自由文本字符串，没有类别、严重程度或关联事件链接，因此无法在不重读文本的情况下按主题过滤反馈。
+- **不支持修改或撤回**：会话日志是仅追加的，本包也不新增 tombstone，因此错误的条目会一直保留在记录中，只能由后续条目取代。
+- **没有显式持久化屏障**：确认文本紧随追加而非 flush，因此紧临崩溃前记录的条目可能与其他未 flush 的尾部一同丢失。为反馈强制同步写盘并不值得；需要该保证的消费方可自行等待 `ctx.sessions.flush(session)`。
+- **新会话上没有可见的确认**：Web 转录只在会话激活后渲染命令行，因此在仍为空白的新会话上执行 `/feedback` 会记录事件但不会显示确认行。发送首条消息后再记录反馈即可正常渲染。
+- **随附的产品入口中只有 Web 使用此命令**：无头模式、ACP（Agent Client Protocol）自动化和 JSON-RPC 不提供命令适配器，因此 `/feedback` 在那里不可用。

package/lib/index.js

@@ -0,0 +1,83 @@
+import { getOrCreateAnonymousUserId } from "@stackstackstack/dsh-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 @stackstackstack/dsh-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 `@stackstackstack/dsh-command-feedback`.
+* @module @stackstackstack/dsh-command-feedback/invariant
+*/
+const PACKAGE_NAME = "@stackstackstack/dsh-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 @stackstackstack/dsh-command-feedback
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@stackstackstack/dsh-session';
+export declare const name = "command-feedback";
+export declare const inject: string[];
+declare module '@stackstackstack/dsh-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 `@stackstackstack/dsh-command-feedback`.
+ * @module @stackstackstack/dsh-command-feedback/invariant
+ */
+import type { Context } from '@deepseek-ai/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

@@ -0,0 +1,54 @@
+{
+  "name": "@stackstackstack/dsh-command-feedback",
+  "description": "Log-only session feedback producer and human-facing slash command",
+  "version": "0.1.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-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": {
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@stackstackstack/dsh-commands": "^0.1.5",
+    "@stackstackstack/dsh-session-telemetry": "^0.1.5",
+    "@stackstackstack/dsh-session": "^0.1.5",
+    "@stackstackstack/dsh-anonymous-user-id": "^0.1.5",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-include": "^1.0.6",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
+    "@stackstackstack/dsh-agent": "^0.1.5",
+    "@stackstackstack/dsh-commands": "^0.1.5",
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@stackstackstack/dsh-llm": "^0.1.5",
+    "@stackstackstack/dsh-session": "^0.1.5",
+    "@stackstackstack/dsh-session-telemetry": "^0.1.5",
+    "@stackstackstack/dsh-anonymous-user-id": "^0.1.5",
+    "@deepseek-ai/cordis": "^4.0.1"
+  }
+}