@llamaventures/cli 2.4.0 → 2.5.0

package/AGENT_BRIEFING.md

@@ -233,3 +233,19 @@ artifact, then decide whether its content deserves Information or a Page patch.
 - Wiki, admin audit, external pitch, authentication, and skill discovery are
   separate domains. Deal Memory is also separate. None expands the four-action
   Occam Deal space.
+
+## Report UX friction
+
+When a user, agent or both encounter a concrete obstacle (including a task that
+eventually succeeds), use `llama feedback submit --title ... --body ...
+--experienced-by user|agent|both` or MCP `feedback_submit`. Two fields suffice;
+optional expected/steps/impact/workaround/suggestion explain the obstacle.
+Use `llama help feedback` for JSON input and diagnostics. Versions are captured
+when available; do not guess unknown host/model versions. Separate observation
+from hypothesis, report once per obstacle, and never attach credentials, full
+transcripts, file contents, raw arguments or arbitrary environment variables.
+Only explicitly correlate a request from this task; concurrent agents share
+local telemetry state. Retain submission_id for identical retries, read the
+receipt with `llama feedback show` / `feedback_show`, and never let reporting
+failure block the original task or produce recursive feedback. New tools need
+Core API 5.9.0; do not loop if the server has not added them yet.

package/CHANGELOG.md

@@ -6,6 +6,12 @@ this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+### Added
+
+- Submit user/agent UX friction with `llama feedback submit` and MCP `feedback_submit`; read your receipt and resolution with `feedback show` / `feedback_show`.
+- Capture CLI/build and OS/Node versions, plus available coding-agent host identity/version with explicit provenance. Unknown versions stay absent.
+- Bounded authenticated submissions, retry IDs, credential redaction and no recursive feedback telemetry. New feedback commands require Core API 5.9.0; existing commands retain compatibility.
+
 ## [2.4.0] - 2026-09-09
 
 ### Added

package/README.md

@@ -228,3 +228,36 @@ These options require a Core version with source-content reads. Scanned PDFs
 may require OCR; no-text, missing files, unsupported formats and denied storage
 are explicit outcomes, not evidence that a memo has been read. MCP exposes the
 same text reads inside `read_deal` and `wiki_read`.
+
+## UX friction feedback
+
+Report obstacles encountered by a user, agent or both, including tasks that
+succeeded after confusion or unnecessary steps. Two fields are enough:
+
+```bash
+llama feedback submit --title "Confusing empty response" --body "Expected source text, but the successful response was empty." --experienced-by agent
+llama feedback submit --file feedback.json
+llama feedback show <feedback-id>
+llama help feedback
+```
+
+`--file -` reads JSON from stdin. Optional `details` fields: expected, steps,
+impact, workaround, suggestion. `experienced_by` defaults to both. The CLI adds
+its version/build, OS/Node and available agent identity; MCP captures its
+initialized host name/version. `--agent-name`, `--agent-version`, `--model` (or
+`LLAMA_AGENT_CLIENT`, `LLAMA_AGENT_VERSION`, `LLAMA_AGENT_MODEL`) are explicit
+reports. Missing versions stay absent; installed programs are never executed
+to guess a running host version. Automatic metadata describes the submitting
+process; retrospective reports can explicitly supply historical environment
+and `occurred_at` through JSON.
+
+Keep the returned `submission_id` for identical retries (`--submission-id`).
+One report per obstacle per task. `--request-id` is optional and must refer to
+that task and reporter; no global last-command association is inferred. Do not
+include secrets, raw command arguments, environment dumps, full transcripts or
+file contents. Known credential patterns are redacted, not a guarantee that
+arbitrary text is secret-free. Submission failures are explicit and must not
+block the original task or trigger recursive feedback. Calls use a 15-second
+fetch budget and refuse redirects. Requires Core API 5.9.0, existing login and
+write scope; receipt reads require read scope and only return your own reports.
+MCP provides `feedback_submit` and `feedback_show` with the same behavior.

package/README.zh-CN.md

@@ -215,3 +215,25 @@ npm run verify:release
 
 需要服务端支持正文读取。扫描 PDF 不自动 OCR；无文字、缺失文件、不支持的格式、
 权限不足都会明确报告。MCP 在原有 `read_deal` 和 `wiki_read` 中提供相同正文读取能力。
+
+## 用户与 Agent 的 UX friction
+
+即使任务最终成功，困惑、多余步骤、反复尝试也值得反馈：
+
+```bash
+llama feedback submit --title "成功响应没有正文" --body "用户想总结附件，但读取成功后没有返回文本，任务无法继续。" --experienced-by agent
+llama feedback submit --file feedback.json
+llama feedback show <反馈ID>
+llama help feedback
+```
+
+标题和描述必填；`experienced_by` 为 user / agent / both，默认 both。
+CLI 自动附带版本、构建、OS/Node 和可确认的 Agent 身份；MCP 读取宿主声明的名称及版本。
+Agent 版本未知时不猜测。`--agent-name`、`--agent-version`、`--model` 可明确补充信息。
+较早发生的问题可通过 JSON 提供历史环境和 `occurred_at`，自动采集的环境属于当前提交进程。
+可选 details 字段为 expected、steps、impact、workaround、suggestion。
+同一次重试复用 submission_id；同一任务的同一障碍只报一次。
+不附完整对话、文件、命令参数或凭证，不自动关联全局最后一次调用。
+提交失败明确报错，不能声称成功，也不能触发递归反馈或阻塞原任务。
+新命令需要 Core API 5.9.0，沿用现有登录；用户只能读取自己的反馈。
+MCP 对应 feedback_submit / feedback_show。

package/bin/llama-mcp.mjs

@@ -26,6 +26,7 @@ import {
   compactDealWriteResult,
   prepareDealCommand,
 } from "../lib/deal-actions.mjs";
+import { submitFeedback, readFeedback } from "../lib/feedback.mjs";
 import { buildDealMemoryPath } from "../lib/deal-memory-actions.mjs";
 import { buildPageSchemaPath, MAX_PAGE_SCHEMA_FIELDS } from "../lib/page-schema.mjs";
 
@@ -51,6 +52,28 @@ async function callApi(method, path, body, transform = (value) => value) {
   }
 }
 
+server.registerTool("feedback_submit", {
+  description: "Report concrete UX friction experienced by a user, agent or both, even if the task succeeded. Separate observations from guesses. One report per obstacle; never include secrets, transcripts, files or raw command arguments. Failures must not block the original task or trigger recursive reporting. Reuse submission_id for retries. Host identity/version is captured when available; unknown versions stay absent.",
+  inputSchema: {
+    title: z.string().min(1).max(200), body: z.string().min(1).max(8000),
+    experienced_by: z.enum(["user", "agent", "both"]).optional(), submission_id: z.string().uuid().optional(),
+    occurred_at: z.string().datetime({ offset: true }).optional(),
+    details: z.object({ expected: z.string().max(2000).optional(), steps: z.string().max(4000).optional(), impact: z.string().max(2000).optional(), workaround: z.string().max(2000).optional(), suggestion: z.string().max(2000).optional() }).strict().optional(),
+    environment: z.object({ agent_name: z.string().max(120).optional(), agent_version: z.string().max(120).optional(), model: z.string().max(120).optional(), command: z.string().max(160).optional(), error_code: z.string().max(120).optional(), request_id: z.string().max(128).optional() }).strict().optional(),
+  },
+}, async input => {
+  try { return textResult(JSON.stringify(await submitFeedback(input, server.server.getClientVersion()), null, 2)); }
+  catch (error) { return textResult(formatErrorForDisplay(error), true); }
+});
+server.registerTool("feedback_show", {
+  description: "Read your own submitted friction report and resolution using its feedback ID.",
+  inputSchema: { id: z.string().uuid() },
+  annotations: { readOnlyHint: true },
+}, async ({ id }) => {
+  try { return textResult(JSON.stringify(await readFeedback(id), null, 2)); }
+  catch (error) { return textResult(formatErrorForDisplay(error), true); }
+});
+
 const originSchema = z.object({
   kind: z.enum(["user", "agent", "system"]),
   originalUserUtterance: z.string().min(1).optional(),

package/bin/llama.mjs

@@ -44,6 +44,7 @@ import {
   buildDealMemoryPath,
   readMarkdownInput,
 } from "../lib/deal-memory-actions.mjs";
+import { submitFeedback, readFeedback, readFeedbackInput } from "../lib/feedback.mjs";
 import { buildPageSchemaPath } from "../lib/page-schema.mjs";
 
 const requireFromHere = createRequire(import.meta.url);
@@ -74,6 +75,8 @@ Separate preserved domains:
   llama deal read <dealId> --artifact <artifactId> [--version N] [--offset N --sha256 HASH] [--limit N] [--output <file>]
   llama wiki read <slug> --format text [--attachment <referenceId>] [--offset N --sha256 HASH] [--output <file>]
   llama wiki search|read|save|delete|restore
+  llama feedback submit --title "..." --body "..." [--experienced-by user|agent|both]
+  llama feedback show <id>
   llama admin auth-events|deal-events|agent-events
   llama pitch start|say|upload|status|finalize|end
 
@@ -176,6 +179,23 @@ Start with list. Before page.patch, read only the exact fields being changed;
 use a section read only when the write genuinely spans that section. This is a
 schema/field-prompt surface, not a fifth Deal action and not Page data.`;
 
+const HELP_FEEDBACK = `Report concrete user or agent UX friction, even when the task succeeds.
+
+  llama feedback submit --title "..." --body "..." [--experienced-by user|agent|both]
+  llama feedback submit --file <feedback.json|->
+  llama feedback show <id>
+
+Optional flags: --expected, --steps, --impact, --workaround, --suggestion,
+--agent-name, --agent-version, --model, --command, --error-code, --request-id,
+--occurred-at (ISO timestamp), --submission-id (reuse for retries).
+
+CLI/build, OS/Node and available agent identity are added automatically. Unknown
+agent versions stay absent. LLAMA_AGENT_CLIENT, LLAMA_AGENT_VERSION and
+LLAMA_AGENT_MODEL are explicit declarations, not inferred installed versions.
+Only attach a request ID from this task. Do not include credentials, full
+transcripts, file contents or raw command arguments. Report once per obstacle;
+feedback failure must not block the task or trigger recursive feedback.`;
+
 function parseFlags(args, allowed = null) {
   const flags = {};
   const positional = [];
@@ -206,6 +226,7 @@ function usage(area) {
     area === "deal" ? HELP_DEAL :
     area === "memory" ? HELP_MEMORY :
     area === "page-schema" ? HELP_PAGE_SCHEMA :
+    area === "feedback" ? HELP_FEEDBACK :
     HELP_ROOT,
   );
 }
@@ -529,6 +550,26 @@ async function main() {
     return;
   }
 
+  if (area === "feedback") {
+    if (action === "show" && rest.length === 1) { print(await readFeedback(rest[0])); return; }
+    if (action !== "submit") throw new Error("Usage: llama feedback submit|show; see llama help feedback");
+    const allowed = ["file", "title", "body", "experienced-by", "expected", "steps", "impact", "workaround", "suggestion", "agent-name", "agent-version", "model", "command", "error-code", "request-id", "occurred-at", "submission-id"];
+    const { flags, positional } = parseFlags(rest, allowed);
+    if (positional.length || Object.values(flags).some(v => typeof v !== "string")) throw new Error("Feedback flags require values; see llama help feedback");
+    let input;
+    if (flags.file) {
+      if (Object.keys(flags).some(k => !["file", "submission-id"].includes(k))) throw new Error("Use --file or field flags, not both");
+      input = await readFeedbackInput(flags.file);
+      if (flags["submission-id"]) input.submission_id = flags["submission-id"];
+    } else {
+      input = { title: flags.title, body: flags.body, details: {}, environment: {} };
+      for (const key of ["experienced-by", "occurred-at", "submission-id"]) if (flags[key]) input[key.replaceAll("-", "_")] = flags[key];
+      for (const key of ["expected", "steps", "impact", "workaround", "suggestion"]) if (flags[key]) input.details[key] = flags[key];
+      for (const key of ["agent-name", "agent-version", "model", "command", "error-code", "request-id"]) if (flags[key]) input.environment[key.replaceAll("-", "_")] = flags[key];
+    }
+    print(await submitFeedback(input)); return;
+  }
+
   assertDealAction(area, action);
 
   if (await handleAuth(area, action, rest)) return;

package/contracts/core-api.json

@@ -1,9 +1,9 @@
 {
   "format": "llama.core-api-contract.v1",
   "name": "llama-core-api",
-  "apiVersion": "5.8.0",
+  "apiVersion": "5.9.0",
   "openapiVersion": "3.0.3",
-  "sha256": "ec68e92362c9f60eee94b81d73fb7cff2868c80d7c17c24a9e3122cc2743e7ad",
-  "pathCount": 113,
-  "operationCount": 140
+  "sha256": "619d4cabf0fa078bab2cdbb669fc9066701fc68ce194809a37c00a431bb66d35",
+  "pathCount": 117,
+  "operationCount": 144
 }

package/contracts/required-operations.json

@@ -2,36 +2,137 @@
   "format": "llama.cli-core-api-operations.v1",
   "coreApiContract": "contracts/core-api.json",
   "requiredOperations": [
-    { "method": "DELETE", "path": "/api/wiki/{slug}" },
-    { "method": "GET", "path": "/api/admin/agent-events" },
-    { "method": "GET", "path": "/api/admin/auth-events" },
-    { "method": "GET", "path": "/api/admin/deal-events" },
-    { "method": "GET", "path": "/api/agent/briefing" },
-    { "method": "GET", "path": "/api/agent/explain" },
-    { "method": "GET", "path": "/api/agent/manifest" },
-    { "method": "GET", "path": "/api/agent/page-schema" },
-    { "method": "GET", "path": "/api/agent/preferences" },
-    { "method": "GET", "path": "/api/agent/skills" },
-    { "method": "GET", "path": "/api/agent/skills/{slug}" },
-    { "method": "GET", "path": "/api/deal-memory/{dealId}/story" },
-    { "method": "GET", "path": "/api/me" },
-    { "method": "GET", "path": "/api/oauth/authorize" },
-    { "method": "GET", "path": "/api/occam/deals" },
-    { "method": "GET", "path": "/api/occam/deals/{dealId}" },
-    { "method": "GET", "path": "/api/occam/deals/{dealId}/artifacts/{artifactId}" },
-    { "method": "GET", "path": "/api/wiki/{slug}" },
-    { "method": "GET", "path": "/api/wiki/search" },
-    { "method": "PATCH", "path": "/api/agent/preferences/{id}" },
-    { "method": "POST", "path": "/api/agent/client-events" },
-    { "method": "POST", "path": "/api/agent/preferences" },
-    { "method": "POST", "path": "/api/external/chat" },
-    { "method": "POST", "path": "/api/external/start-session" },
-    { "method": "POST", "path": "/api/external/upload" },
-    { "method": "POST", "path": "/api/oauth/revoke" },
-    { "method": "POST", "path": "/api/oauth/token" },
-    { "method": "POST", "path": "/api/occam/deals/commands" },
-    { "method": "POST", "path": "/api/wiki/{slug}/restore" },
-    { "method": "POST", "path": "/api/wiki/save" },
-    { "method": "PUT", "path": "/api/deal-memory/{dealId}/story" }
+    {
+      "method": "DELETE",
+      "path": "/api/wiki/{slug}"
+    },
+    {
+      "method": "GET",
+      "path": "/api/admin/agent-events"
+    },
+    {
+      "method": "GET",
+      "path": "/api/admin/auth-events"
+    },
+    {
+      "method": "GET",
+      "path": "/api/admin/deal-events"
+    },
+    {
+      "method": "GET",
+      "path": "/api/agent/briefing"
+    },
+    {
+      "method": "GET",
+      "path": "/api/agent/explain"
+    },
+    {
+      "method": "GET",
+      "path": "/api/agent/manifest"
+    },
+    {
+      "method": "GET",
+      "path": "/api/agent/page-schema"
+    },
+    {
+      "method": "GET",
+      "path": "/api/agent/preferences"
+    },
+    {
+      "method": "GET",
+      "path": "/api/agent/skills"
+    },
+    {
+      "method": "GET",
+      "path": "/api/agent/skills/{slug}"
+    },
+    {
+      "method": "GET",
+      "path": "/api/deal-memory/{dealId}/story"
+    },
+    {
+      "method": "GET",
+      "path": "/api/feedback/{id}"
+    },
+    {
+      "method": "GET",
+      "path": "/api/me"
+    },
+    {
+      "method": "GET",
+      "path": "/api/oauth/authorize"
+    },
+    {
+      "method": "GET",
+      "path": "/api/occam/deals"
+    },
+    {
+      "method": "GET",
+      "path": "/api/occam/deals/{dealId}"
+    },
+    {
+      "method": "GET",
+      "path": "/api/occam/deals/{dealId}/artifacts/{artifactId}"
+    },
+    {
+      "method": "GET",
+      "path": "/api/wiki/search"
+    },
+    {
+      "method": "GET",
+      "path": "/api/wiki/{slug}"
+    },
+    {
+      "method": "PATCH",
+      "path": "/api/agent/preferences/{id}"
+    },
+    {
+      "method": "POST",
+      "path": "/api/agent/client-events"
+    },
+    {
+      "method": "POST",
+      "path": "/api/agent/preferences"
+    },
+    {
+      "method": "POST",
+      "path": "/api/external/chat"
+    },
+    {
+      "method": "POST",
+      "path": "/api/external/start-session"
+    },
+    {
+      "method": "POST",
+      "path": "/api/external/upload"
+    },
+    {
+      "method": "POST",
+      "path": "/api/feedback"
+    },
+    {
+      "method": "POST",
+      "path": "/api/oauth/revoke"
+    },
+    {
+      "method": "POST",
+      "path": "/api/oauth/token"
+    },
+    {
+      "method": "POST",
+      "path": "/api/occam/deals/commands"
+    },
+    {
+      "method": "POST",
+      "path": "/api/wiki/save"
+    },
+    {
+      "method": "POST",
+      "path": "/api/wiki/{slug}/restore"
+    },
+    {
+      "method": "PUT",
+      "path": "/api/deal-memory/{dealId}/story"
+    }
   ]
 }

package/lib/build-manifest.json

@@ -1,15 +1,15 @@
 {
   "format": "llama.cli-build.v1",
   "packageName": "@llamaventures/cli",
-  "packageVersion": "2.4.0",
-  "sourceSha": "5f2e08c216a111bc568e7dee925aa198674c6255",
+  "packageVersion": "2.5.0",
+  "sourceSha": "2f1d1c40ee4a970fb8c028428aa25c2976222486",
   "sourceKind": "github",
   "sourceDirty": false,
   "coreApiContract": {
     "format": "llama.core-api-contract.v1",
     "name": "llama-core-api",
-    "apiVersion": "5.8.0",
+    "apiVersion": "5.9.0",
     "openapiVersion": "3.0.3",
-    "sha256": "ec68e92362c9f60eee94b81d73fb7cff2868c80d7c17c24a9e3122cc2743e7ad"
+    "sha256": "619d4cabf0fa078bab2cdbb669fc9066701fc68ce194809a37c00a431bb66d35"
   }
 }

package/lib/client.mjs

@@ -148,6 +148,11 @@ export function setClientRuntime(opts = {}) {
   if (opts.agentClient) runtimeAgentClient = String(opts.agentClient);
 }
 
+export function getFeedbackRuntime() {
+  const agent = detectAgentClient();
+  return { client: runtimeClient, agent, agentSource: runtimeAgentClient || process.env.LLAMA_AGENT_CLIENT ? "reported" : agent === "unknown" ? "unknown" : "detected" };
+}
+
 function detectAgentClient() {
   if (runtimeAgentClient) return runtimeAgentClient;
   if (process.env.LLAMA_AGENT_CLIENT) return process.env.LLAMA_AGENT_CLIENT;
@@ -361,7 +366,7 @@ function summarizeResult(data) {
 function shouldSkipTelemetry(endpoint) {
   if (process.env.LLAMA_TELEMETRY === "0") return true;
   const pathname = parseEndpoint(endpoint)?.pathname || endpoint;
-  return pathname === "/api/agent/client-events" || pathname === "/api/agent/eval-feedback";
+  return pathname === "/api/feedback" || pathname.startsWith("/api/feedback/") || pathname === "/api/agent/client-events" || pathname === "/api/agent/eval-feedback";
 }
 
 async function recordClientTelemetry({
@@ -602,6 +607,8 @@ async function requestWithRetry(method, endpoint, body, opts, allowRetry) {
   const command = inferCommand(method, endpoint);
   const start = Date.now();
   const res = await fetch(`${getBaseUrl()}${endpoint}`, {
+    signal: opts.signal,
+    redirect: opts.redirect,
     method,
     headers: {
       "Content-Type": "application/json",

package/lib/feedback.mjs

@@ -0,0 +1,104 @@
+import os from "node:os";
+import { createReadStream } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { getBuildInfo } from "./build-info.mjs";
+import { getFeedbackRuntime, request } from "./client.mjs";
+
+const TOP = ["submission_id", "title", "body", "experienced_by", "occurred_at", "details", "environment"];
+const DETAILS = { expected: 2000, steps: 4000, impact: 2000, workaround: 2000, suggestion: 2000 };
+const ENV = { surface: 12, cli_version: 80, cli_source_sha: 80, agent_name: 120, agent_version: 120,
+  agent_name_source: 12, agent_version_source: 12, model: 120, model_source: 12,
+  os: 80, os_version: 120, arch: 40, node_version: 80, command: 160, error_code: 120, request_id: 128 };
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export function redactFeedbackText(text) {
+  return text.replace(/\b(?:llc_|sk-|ghp_|github_pat_|ya29\.)[A-Za-z0-9_.-]+/g, "[redacted]")
+    .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, "[redacted]")
+    .replace(/\b(Bearer)\s+[^\s,;\x22\x27]+/gi, "$1 [redacted]")
+    .replace(/\b((?:access[_-]?token|refresh[_-]?token|api[_-]?key|token|secret|password|authorization|cookie)[\x22\x27]?\s*[:=]\s*)[^\r\n]+/gi, "$1[redacted]")
+    .replace(/(https?:\/\/)[^\s/@]+:[^\s/@]+@/gi, "$1[redacted]@");
+}
+function object(value, allowed, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${name} must be an object`);
+  for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new Error(`Unknown ${name} field: ${key}`);
+  return value;
+}
+function text(value, max, name) {
+  if (typeof value !== "string" || !value.trim() || value.trim().length > max) throw new Error(`${name} requires 1–${max} characters`);
+  return redactFeedbackText(value.trim());
+}
+function strings(value, fields, name) {
+  const result = {};
+  for (const [key, val] of Object.entries(object(value, Object.keys(fields), name))) result[key] = text(val, fields[key], `${name}.${key}`);
+  return result;
+}
+export function feedbackId(id) {
+  if (typeof id !== "string" || !UUID.test(id)) throw new Error("Feedback ID must be a UUID");
+  return id;
+}
+export async function readFeedbackInput(file, stdin = process.stdin) {
+  const stream = file === "-" ? stdin : createReadStream(file);
+  let size = 0; const chunks = [];
+  for await (const chunk of stream) {
+    const bytes = Buffer.from(chunk); size += bytes.length;
+    if (size > 32768) { stream.destroy(); throw new Error("Feedback exceeds 32 KiB"); }
+    chunks.push(bytes);
+  }
+  try { return JSON.parse(Buffer.concat(chunks).toString("utf8")); }
+  catch { throw new Error("Feedback file must contain valid JSON"); }
+}
+export function prepareFeedback(input, host) {
+  object(input, TOP, "feedback");
+  const runtime = getFeedbackRuntime(); const build = getBuildInfo();
+  const supplied = strings(input.environment ?? {}, ENV, "environment");
+  const environment = {
+    surface: runtime.client, cli_version: build.packageVersion, cli_source_sha: build.sourceSha,
+    os: os.platform(), os_version: os.release(), arch: os.arch(), node_version: process.version,
+    agent_name: runtime.agent, agent_name_source: runtime.agentSource,
+    ...(host?.name ? { agent_name: host.name, agent_name_source: "host" } : {}),
+    ...(host?.version ? { agent_version: host.version, agent_version_source: "host" } : {}),
+    ...(process.env.LLAMA_AGENT_VERSION ? { agent_version: process.env.LLAMA_AGENT_VERSION, agent_version_source: "reported" } : {}),
+    ...(process.env.LLAMA_AGENT_MODEL ? { model: process.env.LLAMA_AGENT_MODEL, model_source: "reported" } : {}),
+    ...supplied,
+  };
+  if (supplied.agent_name && host?.name && supplied.agent_name !== host.name && !supplied.agent_version && !process.env.LLAMA_AGENT_VERSION) {
+    delete environment.agent_version;
+    delete environment.agent_version_source;
+  }
+  // Explicit overrides are declarations, not observations of the running host.
+  for (const key of ["agent_name", "agent_version", "model"]) {
+    if (supplied[key] && !supplied[`${key}_source`]) environment[`${key}_source`] = "reported";
+  }
+  for (const key of ["agent_name_source", "agent_version_source", "model_source"]) {
+    if (environment[key] && !["detected", "host", "reported", "unknown"].includes(environment[key])) throw new Error(`Invalid ${key}`);
+  }
+  if (!["cli", "mcp", "web", "api"].includes(environment.surface)) throw new Error("Invalid environment.surface");
+  const experiencedBy = input.experienced_by ?? "both";
+  if (!["user", "agent", "both"].includes(experiencedBy)) throw new Error("experienced_by must be user, agent or both");
+  if (input.occurred_at && (typeof input.occurred_at !== "string" || !/^\d{4}-\d\d-\d\dT.*(?:Z|[+-]\d\d:\d\d)$/.test(input.occurred_at) || !Number.isFinite(Date.parse(input.occurred_at)))) throw new Error("occurred_at must be an ISO timestamp with timezone");
+  const result = {
+    submission_id: input.submission_id ? feedbackId(input.submission_id) : randomUUID(),
+    title: text(input.title, 200, "title"), body: text(input.body, 8000, "body"), experienced_by: experiencedBy,
+    ...(input.occurred_at ? { occurred_at: input.occurred_at } : {}),
+    details: strings(input.details ?? {}, DETAILS, "details"), environment: strings(environment, ENV, "environment"),
+  };
+  if (Buffer.byteLength(JSON.stringify(result)) > 32768) throw new Error("Feedback exceeds 32 KiB");
+  return result;
+}
+export async function submitFeedback(input, host) {
+  const body = prepareFeedback(input, host);
+  const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), 15000);
+  try {
+    return await request("POST", "/api/feedback", body, { signal: controller.signal, redirect: "error" });
+  } catch (error) {
+    const wrapped = new Error(`Error[FEEDBACK_NOT_CONFIRMED]: Feedback submission is not confirmed. ${redactFeedbackText(error.message)}\nRetry the same report with submission_id=${body.submission_id}. Do not recursively report this failure.`);
+    wrapped.code = "FEEDBACK_NOT_CONFIRMED";
+    throw wrapped;
+  } finally { clearTimeout(timer); }
+}
+export async function readFeedback(id) {
+  const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), 15000);
+  try {
+    // @core-api-operation GET /api/feedback/{id}
+    return await request("GET", `/api/feedback/${feedbackId(id)}`, undefined, { signal: controller.signal, redirect: "error" });
+  } finally { clearTimeout(timer); }
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@llamaventures/cli",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "CLI + MCP server for the Llama Ventures investment workbench (command.llamaventures.vc).",
   "type": "module",
   "scripts": {
     "test": "npm run test:agent-routing && npm run test:contract",
     "test:agent-routing": "node scripts/verify-agent-routing.mjs",
-    "test:contract": "node --test scripts/content-read.test.mjs scripts/build-manifest.test.mjs scripts/core-api-call-sites.test.mjs scripts/deal-actions-cli.test.mjs scripts/deal-actions.test.mjs scripts/deal-memory-actions-cli.test.mjs scripts/deal-memory-actions.test.mjs scripts/mcp-four-action-surface.test.mjs scripts/page-schema-cli.test.mjs scripts/page-schema.test.mjs scripts/server-compatibility.test.mjs scripts/verify-core-api-contract.test.mjs && node scripts/verify-core-api-contract.mjs",
+    "test:contract": "node --test scripts/feedback.test.mjs scripts/content-read.test.mjs scripts/build-manifest.test.mjs scripts/core-api-call-sites.test.mjs scripts/deal-actions-cli.test.mjs scripts/deal-actions.test.mjs scripts/deal-memory-actions-cli.test.mjs scripts/deal-memory-actions.test.mjs scripts/mcp-four-action-surface.test.mjs scripts/page-schema-cli.test.mjs scripts/page-schema.test.mjs scripts/server-compatibility.test.mjs scripts/verify-core-api-contract.test.mjs && node scripts/verify-core-api-contract.mjs",
     "verify:artifact": "node scripts/verify-release-artifact.mjs",
     "verify:release": "npm test && npm run verify:artifact && node scripts/verify-tarball-clean.mjs",
     "prepack": "node scripts/prepare-build-manifest.mjs",