@llamaventures/cli 1.15.0 → 1.16.0

package/AGENT_BRIEFING.md

@@ -1,6 +1,6 @@
 # Llama Ventures Agent Briefing
 
-You've been onboarded as a teammate of [Llama Ventures](https://llamaventures.vc) via the `@llamaventures/cli` package. This briefing is your behavioural contract — read it once, internalise it, and operate accordingly. The user shouldn't have to explain any of this to you again.
+You've been onboarded as a teammate of [Llama Ventures](https://llamaventures.vc) via the `@llamaventures/cli` package. This bundled briefing is a fallback copy of the behavioural contract. When authenticated, prefer the server-owned contract from `llama agent-onboard`, `llama agent bootstrap`, or MCP `agent_briefing`; read it once, internalise it, and operate accordingly. The user shouldn't have to explain any of this to you again.
 
 You are not just an AI assistant. You're an **extension of a team member** — with CLI access to the Llama Command pipeline, write permission on shared data, and audit-log responsibility. Treat the status seriously.
 
@@ -25,6 +25,7 @@ Most teammates don't know everything this CLI can do. Part of your job is to sur
 This npm package is public, but Llama OS skills are private. Do not assume the skill text is bundled locally. For team-token sessions, discover the live runtime library through Llama Command:
 
 - Start with `llama agent bootstrap` or MCP `agent_bootstrap` when you need the current Command + Llama OS contract.
+- Use `llama agent-onboard` or MCP `agent_briefing` for the server-owned Agent Runtime Contract. The npm-bundled text is fallback only.
 - Use `llama skills search "<task>"` or MCP `skills_search` before choosing a Llama workflow.
 - Use `llama skills show <slug>` or MCP `skills_read` only for the relevant skill.
 - Use `llama explain <command-url-or-object>` or MCP `object_inspect` for 404s, deleted wiki pages, notifier links, deal URLs, and unknown Command objects before telling the user "the system is broken."
@@ -38,6 +39,9 @@ Any time the user mentions a company name or founder name:
 1. **Run `llama deal search "<name>"` BEFORE web search.** Always. No exceptions.
 2. If pipeline has it → pull the data, integrate into your reply silently.
 3. If pipeline doesn't have it → ask once: "New name. Add to pipeline? (Y/n)". On yes, `llama deal create`.
+   - Use `--status Outreached` when we only contacted/logged the company and have no response or effective relationship yet.
+   - Use `--status Sourced` only once there is a response, intro, meeting, or another real relationship signal.
+   - Also set `--source-direction Inbound` if the deal came into the firm; set `--source-direction Outbound` if Llama found/listed/reached out first.
 4. If user gives you new facts (status / valuation / founder note) → `llama deal update` immediately, tell the user **one line** afterward.
 
 Don't:
@@ -201,12 +205,20 @@ llama deal show <dealId>
 llama deal list [--owner ...] [--status ...]
 
 # Pipeline — write
-llama deal create "Company" --description "..."
+llama deal create "Company" --description "..." --source-direction Outbound --status Outreached
+llama deal create "Company" --description "..." --source-direction Inbound --status Sourced
 llama deal update <dealId> <field> <value>
-#   writable: status theirStage stage notes dealOwner source description website
+#   writable: status theirStage stage notes dealOwner source sourceDirection description website
 #             location founders proposedAmount roundSize valuation sector subsector
 #             foundedYear leadInvestor investors   (each write logs a deal_events row)
 
+# Our Stage vocabulary starts with:
+#   Outreached → Sourced → First Meeting → Diligence → Partner Meeting → Term Sheet → Invested
+# `Outreached` is relationship memory only. Do not inflate it to `Sourced`
+# unless a real relationship signal exists.
+# `sourceDirection` is separate: Inbound = came into the firm; Outbound =
+# we found/listed/reached out first.
+
 # Brief blocks
 llama brief blocks <dealId>
 llama brief add-text <dealId> --heading "..." --body "..."
@@ -326,9 +338,9 @@ the intake agent; relay the conversation, then surface the verdict.
 
 ## Where this content lives
 
-- This file: `AGENT_BRIEFING.md` in the `@llamaventures/cli` npm package
-- Re-printable any time: `llama agent-onboard`
-- MCP prompt: `agent_briefing` from the `llama-mcp` server
+- Canonical when authenticated: `GET /api/agent/briefing` via `llama agent-onboard` or MCP `agent_briefing`
+- Runtime home screen: `GET /api/agent/manifest` via `llama agent bootstrap` or MCP `agent_bootstrap`
+- Fallback copy: `AGENT_BRIEFING.md` in the `@llamaventures/cli` npm package
 - Public source: <https://github.com/Llama-Ventures/llama-cli/blob/main/AGENT_BRIEFING.md>
 
 You're now a Llama Ventures teammate (or an external agent helping a

package/CHANGELOG.md

@@ -6,6 +6,38 @@ this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+## [1.16.0] - 2026-06-22
+
+### Added
+- CLI and MCP requests now send bounded local-agent telemetry metadata to
+  Llama Command: client kind/version, detected agent client, session id,
+  normalized command, latency, status, sanitized args, result ids, and bounded
+  result summaries.
+- `llama eval good|bad --last` and `llama eval add "<query>" --expect ...`
+  let agents and humans turn real search usage into Golden Query Eval
+  feedback.
+- MCP tool `record_eval_feedback` mirrors the CLI eval feedback path for
+  MCP-native agents.
+
+### Changed
+- `llama agent-onboard` and MCP `agent_briefing` now prefer the authenticated
+  Llama Command `/api/agent/briefing` runtime contract, with bundled
+  `AGENT_BRIEFING.md` retained as fallback only.
+- `llama agent bootstrap` and MCP `agent_bootstrap` now pass the local CLI
+  version to Command so the server can return stale/ok CLI guidance as part of
+  the agent contract.
+
+## [1.15.1] — 2026-06-16
+
+### Changed
+- Documented the new `Outreached` Our Stage across CLI, MCP, and agent
+  briefing surfaces. Agents should use `Outreached` for logged outreach
+  without a response/effective relationship, and reserve `Sourced` for real
+  relationship signals.
+- Added `sourceDirection` / `--source-direction` guidance across CLI, MCP, and
+  agent briefing surfaces. Use `Inbound` for deals that came into the firm and
+  `Outbound` for companies Llama found/listed/reached out to first.
+
 ## [1.15.0] — 2026-06-15
 
 ### Added

package/README.md

@@ -180,11 +180,14 @@ llama token show
 
 # Pipeline — read
 llama deal search "acme ai"
+llama deal list --owner alex --status Outreached
+llama deal list --source-direction Outbound --status Outreached
 llama deal list --owner alex --status Diligence
 llama deal show <dealId>
 
 # Pipeline — write
-llama deal create "Acme AI" --description "..." --source Gavin
+llama deal create "Acme AI" --description "..." --source Gavin --source-direction Outbound --status Outreached
+llama deal create "Acme AI" --description "..." --source Gavin --source-direction Inbound --status Sourced
 llama deal update <dealId> status Diligence
 llama deal enrich <dealId> --dry-run
 llama deal enrich <dealId> --apply --executor server_agent
@@ -193,6 +196,13 @@ llama deal agent run <dealId> --message "collect founder evidence and update typ
 llama deal delete  <dealId>     # soft (audit-logged)
 llama deal restore <dealId>
 
+# Status semantics
+# Outreached = contact/logged, but no response or effective relationship yet.
+# Sourced    = response, intro, meeting, or another real relationship signal exists.
+# sourceDirection is separate:
+# Inbound    = came into the firm.
+# Outbound   = we found/listed/reached out first.
+
 # Deal Brief — ordered, typed blocks (text · link · embed · callout)
 llama brief blocks       <dealId>
 llama brief add-text     <dealId> --heading "..." --body "..."
@@ -216,6 +226,8 @@ llama agent bootstrap
 llama skills search "wiki delete tombstone"
 llama skills show llama-command
 llama explain https://command.llamaventures.vc/wiki/some-page
+llama eval bad --last --reason "missed the llamaos weekly note"
+llama eval add "last week llama dev weekly" --expect wiki:llamaos-weekly-2026-06-17
 
 # Wiki
 llama wiki search "<query>"
@@ -252,10 +264,31 @@ agents can pattern-match without parsing prose.
 
 ---
 
+### Golden Query Eval feedback
+
+The CLI and MCP server send lightweight client telemetry to Command for each
+authenticated request: client kind/version, detected agent client, local session
+id, normalized command, sanitized args, canonical result ids, status, latency,
+and bounded summaries. It records what Llama Command was asked to do, not the
+user's private Claude Code/Codex/Cursor conversation or local files.
+
+Search commands automatically become eval candidates. Agents can mark the latest
+result explicitly:
+
+```bash
+llama eval good --last
+llama eval bad --last --reason "wrong top wiki"
+llama eval add "AI陪伴" --surface deal --expect deal:<uuid>
+```
+
+MCP-native agents use `record_eval_feedback` for the same flow.
+
+---
+
 ## MCP server
 
 The bundled `llama-mcp` is a **stdio Model Context Protocol** server exposing
-**56 typed tools** that mirror the most-used CLI surface. Every tool is named
+typed tools that mirror the most-used CLI surface. Every tool is named
 and scoped — there is no generic API passthrough, by design (a public-package
 escape hatch reachable from a prompt-injectable agent context is exactly the
 shape we want to avoid).
@@ -280,9 +313,11 @@ printf '%s\n' \
 ```
 
 Auth is identical to the CLI's chain (gcloud → `$LLAMA_TOKEN` → `~/.llama/token`).
-The `agent_briefing` MCP **prompt** also returns
-[`AGENT_BRIEFING.md`](AGENT_BRIEFING.md) verbatim, so any new agent loading the
-server can self-onboard without leaving the protocol.
+The `agent_briefing` MCP **prompt** returns the server-owned Agent Runtime
+Contract when authenticated, so any new agent loading the server can
+self-onboard without leaving the protocol. The bundled
+[`AGENT_BRIEFING.md`](AGENT_BRIEFING.md) is only a fallback if the server
+briefing route is temporarily unavailable.
 
 For current Llama OS skills, use the runtime tools instead of looking for a
 local private repo: `agent_bootstrap`, `skills_search`, `skills_read`, and
@@ -342,8 +377,8 @@ extensions, no transport flags.
 
 > If you're new and want the agent to onboard itself, run
 > `llama agent-onboard` from the CLI or fetch the `agent_briefing` prompt from
-> the MCP server. It's the workflow contract — autonomy levels, attribution
-> grammar, error recovery, anti-pollution rules.
+> the MCP server. It pulls the Command-owned workflow contract — current CLI
+> guidance, attribution grammar, error recovery, and anti-pollution rules.
 
 ---
 

package/README.zh-CN.md

@@ -201,11 +201,14 @@ llama token show
 
 # Pipeline——读
 llama deal search "acme ai"
+llama deal list --owner alex --status Outreached
+llama deal list --source-direction Outbound --status Outreached
 llama deal list --owner alex --status Diligence
 llama deal show <dealId>
 
 # Pipeline——写
-llama deal create "Acme AI" --description "..." --source Gavin
+llama deal create "Acme AI" --description "..." --source Gavin --source-direction Outbound --status Outreached
+llama deal create "Acme AI" --description "..." --source Gavin --source-direction Inbound --status Sourced
 llama deal update <dealId> status Diligence
 llama deal enrich <dealId> --dry-run
 llama deal enrich <dealId> --apply --executor server_agent
@@ -214,6 +217,13 @@ llama deal agent run <dealId> --message "collect founder evidence and update typ
 llama deal delete  <dealId>     # 软删除（审计日志记录）
 llama deal restore <dealId>
 
+# Status 语义
+# Outreached = 只是联系/记录了，还没有回复或有效关系。
+# Sourced    = 已有回复、intro、会议，或其它真实关系信号。
+# sourceDirection 是单独维度：
+# Inbound    = 自然流入公司。
+# Outbound   = 我们主动发现/建名单/触达。
+
 # Deal Brief——有序的、有类型的 block（text · link · embed · callout）
 llama brief blocks       <dealId>
 llama brief add-text     <dealId> --heading "..." --body "..."
@@ -289,9 +299,10 @@ printf '%s\n' \
 ```
 
 认证链跟 CLI 完全一样（gcloud → `$LLAMA_TOKEN` → `~/.llama/token`）。
-`agent_briefing` 这个 MCP **prompt** 还会原样吐出
-[`AGENT_BRIEFING.md`](AGENT_BRIEFING.md)——刚装上 server 的 agent
-不用离开协议就能给自己 onboard。
+`agent_briefing` 这个 MCP **prompt** 会在认证后拉取 Command 服务端的
+Agent Runtime Contract——刚装上 server 的 agent 不用离开协议就能给自己
+onboard。包内 [`AGENT_BRIEFING.md`](AGENT_BRIEFING.md) 只是服务端 briefing
+临时不可用时的 fallback。
 
 要读当前 Llama OS skills，用 runtime tools：`agent_bootstrap`、
 `skills_search`、`skills_read`、`object_inspect`。公开 npm 包不打包私有
@@ -348,7 +359,7 @@ claude mcp add llama -- llama-mcp
 </details>
 
 > 想让 agent 自己 onboard？跑 `llama agent-onboard`，或者从 MCP server
-> 拉 `agent_briefing` prompt——那是 AI agent 的工作合约（autonomy 等级、
+> 拉 `agent_briefing` prompt——它会拿 Command 服务端的工作合约（CLI 状态、
 > attribution 语法、错误恢复、anti-pollution 规则）。
 
 ---

package/bin/llama-mcp.mjs

@@ -11,7 +11,14 @@ import { createRequire } from "module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { getAuthHeaders, readBriefing, request, requestSse } from "../lib/client.mjs";
+import {
+  getAuthHeaders,
+  getLastAgentEvent,
+  readBriefing,
+  request,
+  requestSse,
+  setClientRuntime,
+} from "../lib/client.mjs";
 
 const requireFromHere = createRequire(import.meta.url);
 const { version: PKG_VERSION } = requireFromHere("../package.json");
@@ -23,6 +30,8 @@ import {
   uploadExternalFile,
 } from "../lib/external.mjs";
 
+setClientRuntime({ client: "mcp" });
+
 // Wrap a request() call into the MCP CallToolResult shape. Catches errors
 // (NO_AUTH / 401 / 5xx / network) and surfaces them as `isError: true`
 // content so the calling agent sees a clean error string instead of the
@@ -56,6 +65,20 @@ 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) ?? [
@@ -209,11 +232,47 @@ server.registerTool(
   },
   async ({ limit } = {}) => {
     const params = new URLSearchParams();
+    params.set("clientVersion", PKG_VERSION);
     if (limit) params.set("limit", String(limit));
     return callApi("GET", `/api/agent/manifest${params.toString() ? `?${params}` : ""}`);
   }
 );
 
+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",
   {
@@ -280,7 +339,7 @@ server.registerTool(
   {
     description:
       "Search the Llama Ventures deal pipeline. Fuzzy match on company name, " +
-      "founders, description, founder info, notes, deal owner, source, and location. " +
+      "founders, description, founder info, notes, deal owner, source, source direction, and location. " +
       "Returns up to `limit` deals (default 200, cap 1000).",
     inputSchema: {
       q: z.string().optional().describe("fuzzy search query across all text fields"),
@@ -291,7 +350,7 @@ server.registerTool(
         .string()
         .optional()
         .describe(
-          "exact match on 'Our Stage' (Sourced, First Meeting, Diligence, Partner Meeting, Term Sheet, Invested, Passed, Stalled, Future, Unknown)"
+          "exact match on 'Our Stage' (Outreached, Sourced, First Meeting, Diligence, Partner Meeting, Term Sheet, Invested, Passed, Stalled, Future, Unknown). Outreached means contact was logged but no effective relationship/response exists yet."
         ),
       theirStage: z.string().optional().describe("exact match on 'Their Stage'"),
       stage: z
@@ -300,6 +359,10 @@ server.registerTool(
         .describe(
           "exact match on Round (Pre-Seed, Seed, Series A, Series B, Series C+, Stealth)"
         ),
+      sourceDirection: z
+        .string()
+        .optional()
+        .describe("exact match on source direction: Inbound, Outbound, or Unknown"),
       limit: z.number().optional().describe("max results (default 200, cap 1000)"),
       offset: z.number().optional(),
     },
@@ -318,7 +381,7 @@ server.registerTool(
   {
     description:
       "Get the full canonical record for one deal by uuid. Includes status, " +
-      "stage, founders, owner, source, valuation, all whitelisted writable fields, " +
+      "stage, founders, owner, source, sourceDirection, valuation, all whitelisted writable fields, " +
       "and the `extra` JSONB blob.",
     inputSchema: {
       dealId: z.string().describe("deal uuid"),
@@ -348,8 +411,17 @@ server.registerTool(
         .string()
         .optional()
         .describe("Pre-Seed | Seed | Series A | Series B | Series C+ | Stealth"),
-      status: z.string().optional().describe("Our Stage workflow position"),
+      status: z
+        .string()
+        .optional()
+        .describe(
+          "Our Stage workflow position. Use Outreached when we only contacted/logged them and have no response/effective relationship; use Sourced only once there is a response, intro, meeting, or other real relationship signal."
+        ),
       source: z.string().optional().describe("free-form sourced-by; recommend nominating a user"),
+      sourceDirection: z
+        .string()
+        .optional()
+        .describe("Separate direction tag: Inbound if the deal came into the firm; Outbound if Llama found/listed/reached out first; Unknown if unclear."),
       notes: z.string().optional(),
       location: z.string().optional(),
     },
@@ -362,7 +434,7 @@ server.registerTool(
   {
     description:
       "Update a single whitelisted field on a deal. Writable fields: status, theirStage, " +
-      "notes, stage, dealOwner, source, description, website, location, founders, " +
+      "notes, stage, dealOwner, source, sourceDirection, description, website, location, founders, " +
       "proposedAmount, roundSize, valuation, sector, subsector, foundedYear, leadInvestor, " +
       "investors. Logs a field_change event in deal_events.",
     inputSchema: {
@@ -1582,11 +1654,12 @@ server.registerPrompt(
       "skills_search, and skills_read.",
   },
   async () => {
-    // Gate the briefing behind a /api/me check so unauthenticated MCP
-    // clients can't harvest internal workflow / command surface just by
-    // requesting the prompt. Mirrors the CLI gate in bin/llama.mjs.
+    // Gate the briefing behind authenticated Command runtime. The server-owned
+    // /api/agent/briefing contract is canonical; bundled AGENT_BRIEFING.md is
+    // only a rollout/offline fallback for authenticated users.
     const headers = await getAuthHeaders();
     let stub = null;
+    let briefing = null;
     if (Object.keys(headers).length === 0) {
       stub =
         "Llama Ventures team onboarding requires credentials.\n\n" +
@@ -1597,19 +1670,28 @@ server.registerPrompt(
         "Founder / external visitor: use the `pitch_*` tools — no token required.";
     } else {
       try {
-        await request("GET", "/api/me");
+        const params = new URLSearchParams({ clientVersion: PKG_VERSION });
+        const body = await request("GET", `/api/agent/briefing?${params}`);
+        briefing = body?.briefing || null;
       } catch (err) {
-        stub =
-          "Llama Ventures team onboarding requires valid credentials. " +
-          "Server rejected the credentials we sent. Re-mint at " +
-          "https://command.llamaventures.vc/settings/tokens.";
+        const msg = err?.message || "";
+        if (msg.includes("Error[UNAUTHORIZED]") || msg.includes("Error[NO_AUTH]")) {
+          stub =
+            "Llama Ventures team onboarding requires valid credentials. " +
+            "Server rejected the credentials we sent. Re-mint at " +
+            "https://command.llamaventures.vc/settings/tokens.";
+        } else {
+          briefing =
+            "Warning: server agent briefing unavailable; using bundled fallback.\n\n" +
+            readBriefing();
+        }
       }
     }
     return {
       messages: [
         {
           role: "user",
-          content: { type: "text", text: stub ?? readBriefing() },
+          content: { type: "text", text: stub ?? briefing ?? readBriefing() },
         },
       ],
     };