@llamaventures/cli 1.18.1 → 1.19.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+## [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

@@ -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
 ```
 

package/README.zh-CN.md

@@ -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 验证
 ```
 

package/bin/llama.mjs

@@ -35,6 +35,7 @@ import {
 import { LLAMA_CLI_CLIENT_ID, pkceLoopbackFlow, revokeToken as revokeOAuthToken } from "../lib/oauth-flow.mjs";
 import { deleteBundle, detectBackend, readBundle, writeBundle } from "../lib/oauth-storage.mjs";
 import { maybeNudgeUpdate, getUpdateNudge } from "../lib/version-check.mjs";
+import { getBuildInfo } from "../lib/build-info.mjs";
 
 const requireFromHere = createRequire(import.meta.url);
 const { version: PKG_VERSION } = requireFromHere("../package.json");
@@ -425,6 +426,7 @@ Manually-set \`llc_\` tokens are used as a fallback.
 
 Deals:
   llama deal create "Company" --source <name> --deal-owner <name|email|userId> --source-direction Inbound|Outbound --description "..." --status Interested|Outreached|Sourced --website https://...
+  llama deal founders set <dealId> --json '[{"name":"Ada","email":"ada@example.com","linkedin_url":"https://linkedin.com/in/ada"}]'
   llama deal show <dealId>
   llama deal feed <dealId>                                     # every contribution (facts + notes), human-typed or assistant-drafted, newest first
   llama deal update <dealId> <field> <value>
@@ -1005,6 +1007,10 @@ async function runPitchRepl() {
 async function main() {
   const [area, action, ...rest] = process.argv.slice(2);
   if (area === "--version" || area === "-v" || area === "version") {
+    if (action === "--json" || action === "json") {
+      print(getBuildInfo());
+      return;
+    }
     // `llama version --check` — explicitly check npm for a newer release and
     // print the upgrade line (or "up to date"). Lets an agent surface the
     // nudge on demand, separate from the throttled, TTY-gated auto-nudge.
@@ -1484,6 +1490,26 @@ async function main() {
     return;
   }
 
+  if (area === "deal" && action === "founders") {
+    const sub = rest[0];
+    const dealId = rest[1];
+    const { flags } = parseFlags(rest.slice(2), ["json"]);
+    if (sub !== "set" || !dealId || typeof flags.json !== "string") {
+      throw new Error(
+        "Usage: llama deal founders set <dealId> --json '[{\"name\":\"Ada\",\"email\":\"ada@example.com\"}]'"
+      );
+    }
+    let founders;
+    try {
+      founders = JSON.parse(flags.json);
+    } catch {
+      throw new Error("--json must be a valid JSON array");
+    }
+    if (!Array.isArray(founders)) throw new Error("--json must be a JSON array");
+    print(await request("PUT", `/api/deals/${encodeURIComponent(dealId)}/founders`, { founders }));
+    return;
+  }
+
   // ----- deals.extra JSONB patches (system-admin only, server-gated) -----
   // Same endpoint as `deal update`, but `extraKey` instead of `field`.
   // Server patches one top-level key via jsonb_set and audits the change
@@ -1700,6 +1726,8 @@ async function main() {
       const linkId = rest[2];
       if (!linkId) throw new Error(`Usage: llama deal link ${sub} <dealId> <linkId>`);
       const path = `/api/deals/${encodeURIComponent(dealId)}/links/${encodeURIComponent(linkId)}`;
+      // @core-api-operation DELETE /api/deals/{dealId}/links/{linkId}
+      // @core-api-operation POST /api/deals/{dealId}/links/{linkId}/restore
       print(await request(
         sub === "delete" ? "DELETE" : "POST",
         sub === "delete" ? path : `${path}/restore`
@@ -1967,6 +1995,7 @@ async function main() {
     if (!slug) throw new Error("Usage: llama wiki read <slug> [--lang en|zh]");
     const lang = flags.lang === "zh" ? "zh" : "en";
     const path = `/api/wiki/${encodeURIComponent(slug)}?lang=${lang}`;
+    // @core-api-operation GET /api/wiki/{slug}
     print(await request("GET", path));
     return;
   }
@@ -2298,6 +2327,9 @@ Routing — is this the right command?
       if (flags["errors-only"]) params.set("errors_only", "1");
     }
     const qs = params.toString() ? `?${params.toString()}` : "";
+    // @core-api-operation GET /api/admin/auth-events
+    // @core-api-operation GET /api/admin/deal-events
+    // @core-api-operation GET /api/admin/agent-events
     print(await request("GET", `/api/admin/${sub}${qs}`));
     return;
   }

package/contracts/core-api.json

@@ -0,0 +1,9 @@
+{
+  "format": "llama.core-api-contract.v1",
+  "name": "llama-core-api",
+  "apiVersion": "1.0.1",
+  "openapiVersion": "3.0.3",
+  "sha256": "95ce3639aeee15b0fed09830116838f2a11fd2e40e4f35bf80d785664ecf8d96",
+  "pathCount": 211,
+  "operationCount": 273
+}

package/contracts/required-operations.json

@@ -0,0 +1,91 @@
+{
+  "format": "llama.cli-core-api-operations.v1",
+  "coreApiContract": "contracts/core-api.json",
+  "requiredOperations": [
+    { "method": "DELETE", "path": "/api/deals/{dealId}" },
+    { "method": "DELETE", "path": "/api/deals/{dealId}/blocks/{blockId}" },
+    { "method": "DELETE", "path": "/api/deals/{dealId}/collaborators/{userId}" },
+    { "method": "DELETE", "path": "/api/deals/{dealId}/documents/{slug}" },
+    { "method": "DELETE", "path": "/api/deals/{dealId}/documents/{slug}/html" },
+    { "method": "DELETE", "path": "/api/deals/{dealId}/links/{linkId}" },
+    { "method": "DELETE", "path": "/api/deals/{dealId}/memo" },
+    { "method": "DELETE", "path": "/api/skill-corrections/{id}" },
+    { "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/activity" },
+    { "method": "GET", "path": "/api/agent/briefing" },
+    { "method": "GET", "path": "/api/agent/explain" },
+    { "method": "GET", "path": "/api/agent/manifest" },
+    { "method": "GET", "path": "/api/agent/skills" },
+    { "method": "GET", "path": "/api/agent/skills/{slug}" },
+    { "method": "GET", "path": "/api/deals" },
+    { "method": "GET", "path": "/api/deals/{dealId}" },
+    { "method": "GET", "path": "/api/deals/{dealId}/blocks" },
+    { "method": "GET", "path": "/api/deals/{dealId}/blocks/{blockId}" },
+    { "method": "GET", "path": "/api/deals/{dealId}/blocks/{blockId}/history" },
+    { "method": "GET", "path": "/api/deals/{dealId}/collaborators" },
+    { "method": "GET", "path": "/api/deals/{dealId}/command-center" },
+    { "method": "GET", "path": "/api/deals/{dealId}/documents" },
+    { "method": "GET", "path": "/api/deals/{dealId}/documents/{slug}/html" },
+    { "method": "GET", "path": "/api/deals/{dealId}/documents/{slug}/html/history" },
+    { "method": "GET", "path": "/api/deals/{dealId}/facts" },
+    { "method": "GET", "path": "/api/deals/{dealId}/feed" },
+    { "method": "GET", "path": "/api/deals/{dealId}/links" },
+    { "method": "GET", "path": "/api/deals/{dealId}/memo" },
+    { "method": "GET", "path": "/api/deals/{dealId}/timeline" },
+    { "method": "GET", "path": "/api/deals/deleted" },
+    { "method": "GET", "path": "/api/me" },
+    { "method": "GET", "path": "/api/me/nominations" },
+    { "method": "GET", "path": "/api/mentions" },
+    { "method": "GET", "path": "/api/mentions/unread-count" },
+    { "method": "GET", "path": "/api/oauth/authorize" },
+    { "method": "GET", "path": "/api/partner/approvals" },
+    { "method": "GET", "path": "/api/skill-corrections" },
+    { "method": "GET", "path": "/api/users" },
+    { "method": "GET", "path": "/api/wiki/{slug}" },
+    { "method": "GET", "path": "/api/wiki/search" },
+    { "method": "PATCH", "path": "/api/deals/{dealId}/blocks/{blockId}" },
+    { "method": "PATCH", "path": "/api/deals/{dealId}/documents/{slug}" },
+    { "method": "PATCH", "path": "/api/deals/{dealId}/facts/{factId}" },
+    { "method": "POST", "path": "/api/agent/client-events" },
+    { "method": "POST", "path": "/api/agent/eval-feedback" },
+    { "method": "POST", "path": "/api/deals/{dealId}/agent-runs/{runId}/revert" },
+    { "method": "POST", "path": "/api/deals/{dealId}/blocks/{blockId}/history" },
+    { "method": "POST", "path": "/api/deals/{dealId}/blocks/{blockId}/restore" },
+    { "method": "POST", "path": "/api/deals/{dealId}/collaborators" },
+    { "method": "POST", "path": "/api/deals/{dealId}/collaborators/{userId}/restore" },
+    { "method": "POST", "path": "/api/deals/{dealId}/documents" },
+    { "method": "POST", "path": "/api/deals/{dealId}/documents/{slug}/html/restore/{version}" },
+    { "method": "POST", "path": "/api/deals/{dealId}/enrich" },
+    { "method": "POST", "path": "/api/deals/{dealId}/facts" },
+    { "method": "POST", "path": "/api/deals/{dealId}/links" },
+    { "method": "POST", "path": "/api/deals/{dealId}/links/{linkId}/restore" },
+    { "method": "POST", "path": "/api/deals/{dealId}/memo" },
+    { "method": "POST", "path": "/api/deals/{dealId}/posts" },
+    { "method": "POST", "path": "/api/deals/{dealId}/propose-owner" },
+    { "method": "POST", "path": "/api/deals/{dealId}/refresh-brief" },
+    { "method": "POST", "path": "/api/deals/{dealId}/refresh-persona" },
+    { "method": "POST", "path": "/api/deals/{dealId}/restore" },
+    { "method": "POST", "path": "/api/deals/{dealId}/threads" },
+    { "method": "POST", "path": "/api/deals/{dealId}/threads/{threadId}" },
+    { "method": "POST", "path": "/api/deals/create" },
+    { "method": "POST", "path": "/api/deals/update" },
+    { "method": "POST", "path": "/api/external/chat" },
+    { "method": "POST", "path": "/api/external/start-session" },
+    { "method": "POST", "path": "/api/external/upload" },
+    { "method": "POST", "path": "/api/mentions/{id}/resolve" },
+    { "method": "POST", "path": "/api/nominations/{approvalId}" },
+    { "method": "POST", "path": "/api/oauth/revoke" },
+    { "method": "POST", "path": "/api/oauth/token" },
+    { "method": "POST", "path": "/api/partner/approvals" },
+    { "method": "POST", "path": "/api/skill-corrections" },
+    { "method": "POST", "path": "/api/wiki/{slug}/restore" },
+    { "method": "POST", "path": "/api/wiki/save" },
+    { "method": "PUT", "path": "/api/deals/{dealId}/blocks" },
+    { "method": "PUT", "path": "/api/deals/{dealId}/documents/{slug}/html" },
+    { "method": "PUT", "path": "/api/deals/{dealId}/founders" },
+    { "method": "PUT", "path": "/api/deals/{dealId}/memo" }
+  ]
+}

package/lib/build-info.mjs

@@ -0,0 +1,34 @@
+import { createRequire } from "node:module";
+
+const requireFromHere = createRequire(import.meta.url);
+
+function readJson(relativePath) {
+  try {
+    return requireFromHere(relativePath);
+  } catch {
+    return null;
+  }
+}
+
+export function getBuildInfo() {
+  const built = readJson("./build-manifest.json");
+  if (built) return built;
+
+  const packageJson = readJson("../package.json") || {};
+  const contract = readJson("../contracts/core-api.json") || {};
+  return {
+    format: "llama.cli-build.v1",
+    packageName: packageJson.name || "@llamaventures/cli",
+    packageVersion: packageJson.version || "unknown",
+    sourceSha: "local/unknown",
+    sourceKind: "local",
+    sourceDirty: null,
+    coreApiContract: {
+      format: contract.format || "unknown",
+      name: contract.name || "llama-core-api",
+      apiVersion: contract.apiVersion || "unknown",
+      openapiVersion: contract.openapiVersion || "unknown",
+      sha256: contract.sha256 || "unknown",
+    },
+  };
+}

package/lib/build-manifest.json

@@ -0,0 +1,15 @@
+{
+  "format": "llama.cli-build.v1",
+  "packageName": "@llamaventures/cli",
+  "packageVersion": "1.19.0",
+  "sourceSha": "5f615ca16d607fc0da09887952afdf42301a43f8",
+  "sourceKind": "github",
+  "sourceDirty": false,
+  "coreApiContract": {
+    "format": "llama.core-api-contract.v1",
+    "name": "llama-core-api",
+    "apiVersion": "1.0.1",
+    "openapiVersion": "3.0.3",
+    "sha256": "95ce3639aeee15b0fed09830116838f2a11fd2e40e4f35bf80d785664ecf8d96"
+  }
+}

package/lib/client.mjs

@@ -14,6 +14,7 @@ import { fileURLToPath } from "url";
 import { execFile as _execFile } from "child_process";
 import { promisify } from "util";
 import { createHash, randomUUID } from "crypto";
+import { getBuildInfo } from "./build-info.mjs";
 
 const execFile = promisify(_execFile);
 
@@ -207,9 +208,13 @@ function rememberAgentEvent(event) {
 }
 
 function agentClientHeaders(command) {
+  const build = getBuildInfo();
   return {
     "X-Llama-Client": runtimeClient,
     "X-Llama-Client-Version": getPackageVersion(),
+    "X-Llama-Client-Source-Sha": build.sourceSha,
+    "X-Llama-API-Contract-Version": build.coreApiContract.apiVersion,
+    "X-Llama-API-Contract-Digest": build.coreApiContract.sha256,
     "X-Llama-Agent-Client": detectAgentClient(),
     "X-Llama-Agent-Session": currentAgentSessionId(),
     "X-Llama-Command": command || "unknown",

package/lib/oauth-flow.mjs

@@ -173,6 +173,7 @@ export async function pkceLoopbackFlow({ baseUrl, scope, resource }) {
   });
 
   // Build authorize URL and open browser.
+  // @core-api-operation GET /api/oauth/authorize
   const authorizeUrl = new URL(`${baseUrl}/api/oauth/authorize`);
   authorizeUrl.searchParams.set("response_type", "code");
   authorizeUrl.searchParams.set("client_id", CLIENT_ID);

package/lib/version-check.mjs

@@ -73,6 +73,7 @@ async function fetchLatest() {
     // The /latest convenience endpoint returns full JSON under the default
     // Accept. (The abbreviated "vnd.npm.install-v1+json" metadata type is only
     // valid on the full packument endpoint — it 406s here.)
+    // @core-api-ignore external npm registry version check
     const res = await fetch(REGISTRY_URL, { signal: controller.signal });
     if (!res.ok) return null;
     const data = await res.json();

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@llamaventures/cli",
-  "version": "1.18.1",
+  "version": "1.19.0",
   "description": "CLI + MCP server for the Llama Ventures investment workbench (command.llamaventures.vc).",
   "type": "module",
   "scripts": {
-    "test": "npm run test:agent-routing",
+    "test": "npm run test:agent-routing && npm run test:contract",
     "test:agent-routing": "node scripts/verify-agent-routing.mjs",
-    "verify:release": "npm test && node scripts/verify-tarball-clean.mjs && npm pack --dry-run"
+    "test:contract": "node --test scripts/build-manifest.test.mjs scripts/core-api-call-sites.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",
+    "postpack": "node scripts/cleanup-build-manifest.mjs"
   },
   "bin": {
     "llama": "bin/llama.mjs",
@@ -14,6 +18,7 @@
   },
   "files": [
     "bin/",
+    "contracts/",
     "lib/",
     "AGENT_BRIEFING.md",
     "CHANGELOG.md",