@llamaventures/cli 1.18.1 → 1.20.0

package/AGENT_BRIEFING.md

@@ -63,10 +63,11 @@ A teammate says "I just met them and heard…" or pastes a chunk of notes. Your
 
 1. **Find the deal** — `llama deal search "<name>"` (Pipeline First). New name → offer to create it.
 2. **Split what they gave you into two kinds** — this is the whole data model:
+   - **A source packet with 2+ facts, or facts + a note → ingest once.** Build a JSON object with `source`, `facts`, and optional `note`, then run `llama deal ingest <dealId> --file <packet.json>`. This is the preferred agent path: one atomic, deduplicated, retry-safe commit. Reuse an explicit `idempotencyKey` when retrying the same material. The matching MCP tool is `deal_ingest` and uses the same packet shape.
    - **Verifiable claims → facts.** `llama deal fact add <dealId> --category <cat> --claim "…" --source "<where it came from>" --source-url <url>`. A claim someone *relayed* ("their ARR is $3M", "raised from a16z") is a fact at **unverified** trust — it's hearsay until checked. Pass `--attested` ONLY if you actually verified it against a source yourself. In raw API terms, the fact text field is `claim` (`value` is only a compatibility alias), `source` is the human-readable provenance label, and `sourceUrl` is the canonical URL.
    - **Their judgment / impression → a note.** `llama post <dealId> "…"`. "Founder seemed evasive", "I'd lean pass", "worth a second meeting" — opinion, not fact. Attributed, never "verified".
    - A pasted blob → pull the verifiable claims out as facts, capture their take as a note.
-3. **Read it back before you claim it's saved.** A tool call returning `{ok:true}` is NOT proof the content is where the user will look for it. After filing, run `llama deal feed <dealId>` and confirm your fact/note actually appears, THEN tell the user in plain language what you recorded and where. Never say "记好了 / saved" from the return value alone — the #1 failure is an agent writing to the wrong surface (e.g. the brief, which is the Memo and does NOT appear in the feed) and reporting success anyway. If it's not in the feed, you routed it wrong — fix it.
+3. **Read it back before you claim it's saved.** A generic tool call returning `{ok:true}` is NOT proof the content is where the user will look for it. `deal ingest` is the exception because its response is built from the rows and note block read back after commit: confirm `createdFacts`, `skippedFacts`, `note`, and `summary` in that receipt. For every other write, run `llama deal feed <dealId>` and confirm your fact/note actually appears. Never say "记好了 / saved" from a request acknowledgment alone — the #1 failure is an agent writing to the wrong surface (e.g. the brief, which is the Memo and does NOT appear in the feed) and reporting success anyway. If the authoritative ingest receipt or the feed read-back does not contain the material, fix it before reporting success.
    - **Authorship is automatic, don't fake it.** Everything you write via CLI/MCP is recorded as "via assistant" (you're the accountable human's assistant). You can't and shouldn't make it read as human-typed — that honesty is the feature. Facts you add stay **unverified** until a human confirms them; if you pass `--attested` (only when you actually checked the source) your ceiling is **agent-verified**, never human-vouched. Only a person, signed in at the browser, can vouch. The confirmation IS the trust step — never silently mark something verified.
 
 Why split it: facts and opinions live in different layers so the deal keeps one clean **source of truth** (facts, sourced + trust-rated) separate from people's **takes** (notes). The four layers — facts / notes / brief (AI's synthesis) / timeline — are documented in Llama Command's `docs/SCHEMA.md`.
@@ -130,6 +131,7 @@ These three look similar but land in different surfaces. Don't infer from the co
 
 | You want to… | Command | Lands in |
 |---|---|---|
+| File a **source packet** with multiple facts and/or one note | `llama deal ingest <dealId> --file packet.json` | Facts + optional note → deal **Feed**, atomically and retry-safe |
 | Record a **sourced, verifiable fact** | `llama deal fact add <dealId> --category <cat> --claim "…" --source "deck p3" --source-url <url>` | Facts → deal **Feed** (FACT card) + citable in the **Memo** |
 | Leave a **comment / opinion / question / reaction** for the team | `llama post <dealId> "…"` (`@name` to notify) | Posts → deal **Feed** (POST card); `@mention` fires email + UI badge |
 | Write **narrative that belongs in the IC memo** | `llama brief add-text <dealId> --heading "…" --body "…"` | Brief blocks → **Memo tab only — NOT in the Feed** |
@@ -298,7 +300,7 @@ Run `llama --help` for the full surface (~40 commands).
 
 ## MCP-native agents
 
-If you support [MCP](https://modelcontextprotocol.io), **prefer the MCP server over parsing CLI output.** The same package ships `llama-mcp` (59 typed tools, identical auth chain).
+If you support [MCP](https://modelcontextprotocol.io), **prefer the MCP server over parsing CLI output.** The same package ships `llama-mcp` (55 typed tools, identical auth chain).
 
 Add to your MCP client config (Claude Desktop / Claude Code / Cursor / OpenClaw / Codex / etc.):
 

package/CHANGELOG.md

@@ -6,6 +6,42 @@ this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+## [1.20.0] - 2026-07-22
+
+### Added
+- Add `llama deal ingest <dealId> --file <packet.json>` and the matching
+  `deal_ingest` MCP tool for atomic, retry-safe source packets containing up to
+  50 facts and an optional Feed note.
+- Add `llama pref list|add|retire|approve` and the `pref_list` / `pref_add` /
+  `pref_set_status` MCP tools for standing agent preferences (Core API 3.1.0).
+  Own user scope activates immediately; team scope requires system-admin
+  approval. Content is hard-capped at 280 chars.
+
+### Changed
+- Prefer packet ingest for multi-fact agent writes; Core now canonicalizes fact
+  categories and skips exact source-aware duplicates before committing.
+- Pin the Core API consumer contract to 3.1.0.
+
+### Removed
+- Remove the retired generated-persona refresh and skill-correction commands
+  from the CLI, MCP tool registry, and required Core operation inventory.
+  Llama Command keeps authenticated historical reads and 410 compatibility
+  tombstones, but new clients can no longer invoke the retired workflow.
+- Remove `llama eval` and the `record_eval_feedback` MCP tool; the server-side
+  Golden Query Eval candidate pipeline was retired with Core API 3.0.0.
+
+## [1.19.0] - 2026-07-16
+
+### Added
+- Pin each CLI artifact to the exact versioned Llama Core OpenAPI contract,
+  source commit, and complete source-derived operation inventory.
+- Verify the contract identity and required Core operations during tests,
+  packaging, clean tarball installation, and release-gate validation.
+
+### Changed
+- Treat Core HTTP as the CLI's only backend boundary and expose contract/build
+  provenance through `llama version --json` for independent rollback audits.
+
 ## [1.18.1] - 2026-07-09
 
 ### Changed

package/README.md

@@ -7,7 +7,7 @@
 <p align="center">
   <strong>The Llama Ventures CLI &amp; MCP server.</strong><br/>
   One package, two binaries: <code>llama</code> — the CLI for humans and scripts —
-  and <code>llama-mcp</code> — a stdio MCP server with 59 typed tools for any
+  and <code>llama-mcp</code> — a stdio MCP server with 55 typed tools for any
   MCP-native agent. Both share the same auth chain, HTTP client, and error
   format, and talk to <a href="https://command.llamaventures.vc">command.llamaventures.vc</a>.
 </p>
@@ -42,6 +42,7 @@
 ```bash
 npm i -g @llamaventures/cli    # Node 18+; also puts `llama-mcp` on your PATH
 llama --version
+llama version --json           # package, source commit, and pinned Core API contract
 llama auth status              # round-trips against /api/me
 ```
 
@@ -97,6 +98,7 @@ llama deal feed <dealId>               # every contribution, newest first
 llama activity new-deals --since 24h   # recent deal creations
 llama activity updated-deals --since 7d # meaningful updates grouped by deal
 llama deal create "Acme AI" --source alex --deal-owner owner@llamaventures.vc --source-direction Outbound --status Interested
+llama deal ingest <dealId> --file packet.json  # atomic multi-fact + optional Feed note; retry-safe
 llama deal fact add <dealId> --category funding --claim "Raised a seed round" --source "deck p3" --source-url https://...
 llama deal update <dealId> status Diligence
 llama post <dealId> "note body"
@@ -112,6 +114,13 @@ Status vocabulary — `Interested`: tracked before any contact ·
 signal exists. `sourceDirection` is separate: `Inbound` came to the firm,
 `Outbound` we reached out first.
 
+For a deck, meeting note, email, or research packet, prefer `deal ingest` over a
+loop of `deal fact add` calls. The JSON object accepts `source`, up to 50
+`facts`, an optional `note`, and an optional `idempotencyKey`. The server commits
+the packet atomically, maps common category aliases into the canonical taxonomy,
+and skips exact source-aware duplicates. `deal fact add` remains the simple path
+for one fact.
+
 Facts use `claim` for the fact text. `source` is a readable provenance label
 and `sourceUrl` is the canonical evidence URL; both round-trip from the API.
 For deal owners, use an exact `/api/field-options` `dealOwner` value, a user
@@ -128,12 +137,11 @@ reference (100+ commands). Deletes are soft and audit-logged everywhere.
 | `Error[UNAUTHORIZED]` | Server rejected the credentials | Token revoked / expired / wrong account |
 
 The MCP server returns the same prefixes inside `isError: true` content.
-Authenticated calls send bounded, content-redacted telemetry to Command;
-`llama eval good|bad --last` turns real searches into eval feedback.
+Authenticated calls send bounded, content-redacted telemetry to Command.
 
 ## MCP server
 
-`llama-mcp` is a stdio Model Context Protocol server exposing 59 typed tools
+`llama-mcp` is a stdio Model Context Protocol server exposing 55 typed tools
 that mirror the most-used CLI surface. Every tool is named and scoped — there
 is deliberately no generic API passthrough. Auth is identical to the CLI's
 chain. For the exact live list, pipe `tools/list` through it:

package/README.zh-CN.md

@@ -7,7 +7,7 @@
 <p align="center">
   <strong>Llama Ventures 的 CLI 与 MCP server。</strong><br/>
   一个包、两个可执行文件：<code>llama</code>——给人和脚本用的 CLI；
-  <code>llama-mcp</code>——带 59 个类型化工具的 stdio MCP server，任何
+  <code>llama-mcp</code>——带 55 个类型化工具的 stdio MCP server，任何
   MCP 原生 agent 都能接。两者共享同一认证链、同一 HTTP 客户端、同一错误格式，
   连接 <a href="https://command.llamaventures.vc">command.llamaventures.vc</a>。
 </p>
@@ -67,6 +67,7 @@ Pitch 完成后档案自动进我们团队的 inbox，我们会主动联系你
 ```bash
 npm i -g @llamaventures/cli    # Node 18+；llama-mcp 也会一起装上 PATH
 llama --version
+llama version --json           # 包版本、源码 commit 与固定的 Core API 契约
 llama auth status              # 会跑一次 /api/me 验证
 ```
 
@@ -119,6 +120,7 @@ llama deal feed <dealId>               # 该 deal 的全部贡献，最新在前
 llama activity new-deals --since 24h   # 最近新建的 deal
 llama activity updated-deals --since 7d # 按 deal 聚合的实质更新
 llama deal create "Acme AI" --source alex --deal-owner owner@llamaventures.vc --source-direction Outbound --status Interested
+llama deal ingest <dealId> --file packet.json  # 多条 facts + 可选 Feed note，一次提交且可安全重试
 llama deal fact add <dealId> --category funding --claim "Raised a seed round" --source "deck p3" --source-url https://...
 llama deal update <dealId> status Diligence
 llama post <dealId> "备注内容"
@@ -133,6 +135,11 @@ Status 语义——`Interested`：接触前先记录关注 · `Outreached`：已
 尚无回应 · `Sourced`：已有真实关系信号。`sourceDirection` 是独立维度：
 `Inbound` 流入，`Outbound` 我们主动。
 
+处理 deck、会议笔记、邮件或研究材料时，优先使用 `deal ingest`，不要循环调用
+`deal fact add`。JSON 对象支持 `source`、最多 50 条 `facts`、可选 `note` 和可选
+`idempotencyKey`。服务端会原子提交整个材料包、把常见 category 别名归一到固定分类，
+并跳过来源一致的精确重复。只有真正的单条事实才用 `deal fact add`。
+
 Facts 的正文用 `claim`。`source` 是人可读来源标签，`sourceUrl` 是 canonical
 证据 URL；两者都会从 API 回显。`dealOwner` 请用 `/api/field-options`
 里的精确 `dealOwner` 值、用户邮箱，或数字 user id。
@@ -152,7 +159,7 @@ MCP server 在 `isError: true` 内容里返回相同前缀。认证请求会向
 
 ## MCP server
 
-`llama-mcp` 是 stdio MCP server，59 个类型化工具镜像 CLI 最常用的命令面。
+`llama-mcp` 是 stdio MCP server，55 个类型化工具镜像 CLI 最常用的命令面。
 每个工具具名、有边界——**故意不提供**通用 API passthrough。认证链与 CLI
 完全一致。精确工具清单以 `tools/list` 为准：
 

package/bin/llama-mcp.mjs

@@ -15,7 +15,6 @@ import { z } from "zod";
 import {
   getAuthHeaders,
   getBaseUrl,
-  getLastAgentEvent,
   readBriefing,
   request,
   requestSse,
@@ -84,20 +83,6 @@ function splitSources(value) {
     .filter(Boolean);
 }
 
-function expectedIds(value) {
-  const expected = { dealIds: [], wikiSlugs: [], raw: [] };
-  if (!value) return expected;
-  const items = Array.isArray(value) ? value : String(value).split(",");
-  for (const item of items.map((s) => String(s).trim()).filter(Boolean)) {
-    const [kind, ...rest] = item.split(":");
-    const id = rest.join(":").trim();
-    if (kind === "deal" && id) expected.dealIds.push(id);
-    else if ((kind === "wiki" || kind === "slug") && id) expected.wikiSlugs.push(id);
-    else expected.raw.push(item);
-  }
-  return expected;
-}
-
 function buildEnrichmentAgentMessage(args = {}) {
   if (args.message) return String(args.message);
   const sources = splitSources(args.sources) ?? [
@@ -257,41 +242,6 @@ server.registerTool(
   }
 );
 
-server.registerTool(
-  "record_eval_feedback",
-  {
-    description:
-      "Mark the latest llama CLI/MCP result as good/bad or add a real query " +
-      "to the Golden Query Eval candidate pool. Use when the user says a " +
-      "Llama Command search/result was right, wrong, missing a source, or should be regression-tested.",
-    inputSchema: {
-      action: z.enum(["good", "bad", "add"]).describe("feedback action"),
-      eventId: z.number().optional().describe("agent_client_events id; defaults to latest local event"),
-      query: z.string().optional().describe("required for manual add when no source event is available"),
-      surface: z.string().optional().describe("deal, wiki, activity, people, or manual"),
-      expect: z
-        .union([z.string(), z.array(z.string())])
-        .optional()
-        .describe("expected ids like wiki:llamaos-weekly-2026-06-17 or deal:<uuid>"),
-      reason: z.string().optional().describe("why this was good/bad or should be tracked"),
-      privacyLevel: z.string().optional().describe("default internal"),
-    },
-  },
-  async ({ action, eventId, query, surface, expect, reason, privacyLevel }) => {
-    const last = getLastAgentEvent();
-    const body = {
-      action,
-      eventId: eventId ?? last?.lastEventId,
-      query,
-      surface: surface ?? last?.lastSurface,
-      expected: expectedIds(expect),
-      reason,
-      privacyLevel: privacyLevel ?? "internal",
-    };
-    return callApi("POST", "/api/agent/eval-feedback", body);
-  }
-);
-
 server.registerTool(
   "skills_search",
   {
@@ -311,6 +261,60 @@ server.registerTool(
   }
 );
 
+server.registerTool(
+  "pref_list",
+  {
+    description:
+      "List standing agent preferences (team scope + the caller's user scope). " +
+      "These are injected into every server-side agent turn. Use status=proposed " +
+      "to review pending proposals awaiting approval.",
+    inputSchema: {
+      status: z.enum(["active", "proposed", "retired", "all"]).optional()
+        .describe("filter; defaults to active"),
+    },
+  },
+  async ({ status }) => {
+    const params = new URLSearchParams();
+    if (status) params.set("status", status);
+    return callApi("GET", `/api/agent/preferences${params.toString() ? `?${params}` : ""}`);
+  }
+);
+
+server.registerTool(
+  "pref_add",
+  {
+    description:
+      "Save a standing preference so every Llama agent follows it from the next " +
+      "turn on. Use when the user states a durable way they want agents to work " +
+      "(style, workflow, defaults). Content is hard-capped at 280 chars — if it " +
+      "does not fit, it is a procedure and belongs in a skill. Team scope needs " +
+      "system-admin approval; own user scope activates immediately.",
+    inputSchema: {
+      key: z.string().describe("short slug, e.g. reply-style.conclusion-first"),
+      content: z.string().describe("the preference, max 280 chars"),
+      scope: z.enum(["user", "team"]).optional().describe("default user (the caller)"),
+      evidence: z.string().optional().describe("what prompted this (run, correction)"),
+    },
+  },
+  async ({ key, content, scope, evidence }) =>
+    callApi("POST", "/api/agent/preferences", { key, content, scope, evidence })
+);
+
+server.registerTool(
+  "pref_set_status",
+  {
+    description:
+      "Approve (activate) or retire a standing preference by id. Own user scope " +
+      "is self-service; team scope requires a system admin.",
+    inputSchema: {
+      id: z.number().describe("preference id from pref_list"),
+      status: z.enum(["active", "retired"]).describe("new status"),
+    },
+  },
+  async ({ id, status }) =>
+    callApi("PATCH", `/api/agent/preferences/${encodeURIComponent(String(id))}`, { status })
+);
+
 server.registerTool(
   "skills_read",
   {
@@ -509,6 +513,50 @@ server.registerTool(
 // Deal facts (research substrate + trust ladder)
 // ============================================================
 
+server.registerTool(
+  "deal_ingest",
+  {
+    description:
+      "Preferred write tool when one source yields multiple facts, or facts plus a Feed note. " +
+      "Commits the packet atomically, canonicalizes fact categories, skips exact source-aware " +
+      "duplicates, and is safe to retry with the same idempotencyKey. Use deal_fact_add only " +
+      "for a genuinely single fact. Canonical categories: company_basics, team, product, market, " +
+      "financials, fundraise, risk, milestone, meta.",
+    inputSchema: {
+      dealId: z.string(),
+      idempotencyKey: z
+        .string()
+        .optional()
+        .describe("Stable key for retries. If omitted, the server derives one from packet content."),
+      source: z
+        .object({
+          kind: z.enum(["deck", "web", "meeting_note", "email", "human", "agent_inference"]).optional(),
+          title: z.string().optional(),
+          url: z.string().optional(),
+          contentHash: z.string().optional(),
+        })
+        .optional(),
+      facts: z
+        .array(z.object({
+          category: z.string(),
+          claim: z.string(),
+          source: z.string().optional(),
+          sourceUrl: z.string().optional(),
+          sourceKind: z.enum(["deck", "web", "meeting_note", "email", "human", "agent_inference"]).optional(),
+          confidence: z.enum(["high", "medium", "low"]).optional(),
+          attested: z.boolean().optional(),
+        }))
+        .max(50)
+        .optional(),
+      note: z.string().optional().describe("Opinion, impression, or context to add to the deal Feed."),
+    },
+  },
+  async ({ dealId, ...packet }) => {
+    // @core-api-operation POST /api/deals/{dealId}/ingest
+    return callApi("POST", `/api/deals/${encodeURIComponent(dealId)}/ingest`, packet);
+  }
+);
+
 server.registerTool(
   "deal_fact_list",
   {
@@ -613,7 +661,7 @@ server.registerTool(
       "accountable person, null only for principal-less system writes) and `agent` " +
       "(the assistant/system label when an AI did the writing, null when a human " +
       "typed it) so you can tell human-typed from assistant-drafted. The AI's " +
-      "regenerable brief/persona synthesis is NOT here (that's the Memo) — only " +
+      "regenerable brief synthesis is NOT here (that's the Memo) — only " +
       "facts + discussion notes. Each item: kind (fact|note), ts, who, agent, " +
       "origin, text, and for facts: source + trust rung + category.",
     inputSchema: {
@@ -993,63 +1041,7 @@ server.registerTool(
 );
 
 // ============================================================
-// Skill corrections (persona-owner pushback workflow)
-// ============================================================
-
-server.registerTool(
-  "skill_correction_list",
-  {
-    description:
-      "List the recorded corrections (long-term rules) for a persona/skill. These shape how " +
-      "that persona's analysis is generated.",
-    inputSchema: {
-      skillSlug: z.string(),
-      includeDeleted: z.boolean().optional(),
-    },
-  },
-  async ({ skillSlug, includeDeleted }) => {
-    const params = new URLSearchParams({ skill: skillSlug });
-    if (includeDeleted) params.set("include_deleted", "1");
-    return callApi("GET", `/api/skill-corrections?${params}`);
-  }
-);
-
-server.registerTool(
-  "skill_correction_add",
-  {
-    description:
-      "Record a long-term correction rule for a persona/skill (e.g. 'always check burn multiple " +
-      "before commenting on efficiency'). ALWAYS reconfirm the distilled rule with the user before " +
-      "calling — this changes how the persona behaves going forward. Optionally tie it to the deal/" +
-      "block where it came up.",
-    inputSchema: {
-      skillSlug: z.string(),
-      correctionText: z.string(),
-      dealUuid: z.string().optional(),
-      blockId: z.string().optional(),
-    },
-  },
-  async ({ skillSlug, correctionText, dealUuid, blockId }) =>
-    callApi("POST", "/api/skill-corrections", {
-      skill_slug: skillSlug,
-      correction_text: correctionText,
-      triggered_in_deal_uuid: dealUuid ?? null,
-      triggered_in_block_id: blockId ?? null,
-    })
-);
-
-server.registerTool(
-  "skill_correction_delete",
-  {
-    description: "Soft-delete a recorded skill correction by id.",
-    inputSchema: { id: z.union([z.string(), z.number()]) },
-  },
-  async ({ id }) =>
-    callApi("DELETE", `/api/skill-corrections/${encodeURIComponent(String(id))}`)
-);
-
-// ============================================================
-// Brief / persona refresh (signal-driven re-evaluation)
+// Brief refresh (signal-driven re-evaluation)
 // ============================================================
 
 server.registerTool(
@@ -1070,22 +1062,6 @@ server.registerTool(
     )
 );
 
-server.registerTool(
-  "deal_refresh_persona",
-  {
-    description:
-      "Regenerate one persona's analysis section for a deal. persona = a server-configured " +
-      "persona key (unknown keys are rejected; discover the roster via agent_bootstrap). " +
-      "Returns a runId (or null if debounced).",
-    inputSchema: {
-      dealId: z.string(),
-      persona: z.string(),
-    },
-  },
-  async ({ dealId, persona }) =>
-    callApi("POST", `/api/deals/${encodeURIComponent(dealId)}/refresh-persona`, { persona })
-);
-
 server.registerTool(
   "deal_agent_run",
   {