@llamaventures/cli 2.0.2 → 2.0.3

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [2.0.3] - 2026-08-31
+
+- Show Core validation codes and field paths instead of collapsing malformed
+  Deal writes into `Invalid Occam command`.
+- Publish `write_deal` as four operation-specific MCP command shapes while
+  retaining one mutation tool.
+- Add copyable write examples to `llama help deal` and omit the duplicate
+  rendered briefing from structured bootstrap output.
+- Let Core's private Page contract classify prose and enums instead of keeping
+  a second, drifting public-CLI field whitelist.
+- Return a compact `page.patch` revision receipt with exact read-back fields
+  instead of echoing the full Live Deal Page after every write.
+- Turn retired top-level commands such as `llama brief`, `fact`, `post`,
+  `timeline`, `html`, `memo`, and `pipeline` into self-correcting errors that
+  name the CLI 2 replacement and live contract entrypoint.
+
 ## [2.0.2] - 2026-08-31
 
 - Correct the authenticated runtime model: Brain has exactly two private

package/README.md

@@ -90,8 +90,9 @@ When Page prose is human-visible, write one bilingual field value as
 `{"en":"natural English","zh":"自然中文"}`. The Web language switch selects
 the reader's version from the same Page revision. Keep language-neutral names,
 enums, URLs, numbers, dates, and source IDs scalar. Information and raw Input
-stay in their original language with provenance. The CLI rejects new scalar
-Page prose and incomplete language pairs before they reach Core; historical
+stay in their original language with provenance. Core rejects new scalar Page
+prose according to its private Page contract; the public CLI catches malformed
+half-localized pairs without maintaining a second field whitelist. Historical
 scalar prose remains readable.
 
 Raw user input example:

package/bin/llama-mcp.mjs

@@ -5,10 +5,12 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import {
+  formatErrorForDisplay,
   getAuthHeaders,
   readBriefing,
   request,
   setClientRuntime,
+  structuredBootstrapManifest,
 } from "../lib/client.mjs";
 import {
   clearExternalSession,
@@ -20,6 +22,7 @@ import {
 import {
   buildDealReadPath,
   buildDealSearchPath,
+  compactDealWriteResult,
   prepareDealCommand,
 } from "../lib/deal-actions.mjs";
 
@@ -36,12 +39,12 @@ function textResult(text, isError = false) {
   };
 }
 
-async function callApi(method, path, body) {
+async function callApi(method, path, body, transform = (value) => value) {
   try {
-    const result = await request(method, path, body);
+    const result = transform(await request(method, path, body));
     return textResult(typeof result === "string" ? result : JSON.stringify(result, null, 2));
   } catch (error) {
-    return textResult(`Error: ${error?.message ?? String(error)}`, true);
+    return textResult(formatErrorForDisplay(error), true);
   }
 }
 
@@ -51,6 +54,54 @@ const originSchema = z.object({
   originatingChatRecordId: z.string().uuid().optional(),
 });
 
+const writeDealCommandSchema = z.discriminatedUnion("operation", [
+  z.object({
+    operation: z.literal("input.submit"),
+    dealId: z.string().uuid(),
+    format: z.string().min(1).max(120).optional(),
+    content: z.any(),
+    source: z.record(z.string(), z.any()).optional(),
+    origin: originSchema,
+    idempotencyKey: z.string().min(1).max(240).optional(),
+  }).strict(),
+  z.object({
+    operation: z.literal("information.put"),
+    dealId: z.string().uuid(),
+    informationId: z.string().uuid().optional(),
+    type: z.string().min(1).max(120),
+    labels: z.array(z.string()).optional(),
+    subject: z.record(z.string(), z.any()).optional(),
+    value: z.any(),
+    expectedVersion: z.number().int().positive().optional(),
+    origin: originSchema,
+    idempotencyKey: z.string().min(1).max(240).optional(),
+  }).strict(),
+  z.object({
+    operation: z.literal("page.patch"),
+    dealId: z.string().uuid(),
+    patch: z.record(z.string(), z.any()),
+    expectedRevision: z.number().int().nonnegative().optional(),
+    origin: originSchema,
+    idempotencyKey: z.string().min(1).max(240).optional(),
+  }).strict(),
+  z.object({
+    operation: z.literal("artifact.put"),
+    dealId: z.string().uuid(),
+    artifactId: z.string().uuid().optional(),
+    kind: z.string().min(1).max(120),
+    title: z.string().min(1).max(500),
+    mimeType: z.string().min(1).max(240),
+    contentBase64: z.string().min(1).optional(),
+    storageKey: z.string().min(1).optional(),
+    storageUrl: z.string().url().optional(),
+    byteSize: z.number().int().nonnegative().optional(),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/).optional(),
+    metadata: z.record(z.string(), z.any()).optional(),
+    origin: originSchema,
+    idempotencyKey: z.string().min(1).max(240).optional(),
+  }).strict(),
+]);
+
 // Deal is deliberately a closed four-tool surface. Do not add split resource
 // tools here: one more tool is one more branch every agent must reason about.
 server.registerTool(
@@ -70,7 +121,7 @@ server.registerTool(
 server.registerTool(
   "read_deal",
   {
-    description: "Read one Deal. Live Page and its current private field contract are always returned; Information is memory and never updates Page automatically.",
+    description: "Read one Deal. Live Page is current human-visible state; Information is memory and never updates Page automatically. Page field semantics come from agent_bootstrap, not every Deal read.",
     inputSchema: {
       dealId: z.string().min(1),
       detail: z.enum(["overview", "memory", "files", "conversation", "history", "all"]).optional(),
@@ -99,36 +150,18 @@ server.registerTool(
 server.registerTool(
   "write_deal",
   {
-    description: "The only Deal mutation tool: input.submit, information.put, page.patch, or artifact.put. All Page content fields are Agent-writable; author controls attribution, not permission. Use the read/bootstrap field contract and bilingual Page prose. page.patch is JSON Merge Patch: arrays replace whole arrays, so read-modify-write and preserve sibling slots.",
-    inputSchema: {
-      operation: z.enum(["input.submit", "information.put", "page.patch", "artifact.put"]),
-      dealId: z.string().uuid(),
-      patch: z.record(z.string(), z.any()).optional(),
-      expectedRevision: z.number().int().nonnegative().optional(),
-      informationId: z.string().uuid().optional(),
-      type: z.string().min(1).max(120).optional(),
-      labels: z.array(z.string()).optional(),
-      subject: z.record(z.string(), z.any()).optional(),
-      value: z.any().optional(),
-      expectedVersion: z.number().int().positive().optional(),
-      format: z.string().min(1).max(120).optional(),
-      content: z.any().optional(),
-      source: z.record(z.string(), z.any()).optional(),
-      artifactId: z.string().uuid().optional(),
-      kind: z.string().min(1).max(120).optional(),
-      title: z.string().min(1).max(500).optional(),
-      mimeType: z.string().min(1).max(240).optional(),
-      contentBase64: z.string().min(1).optional(),
-      storageKey: z.string().min(1).optional(),
-      storageUrl: z.string().url().optional(),
-      byteSize: z.number().int().nonnegative().optional(),
-      sha256: z.string().regex(/^[0-9a-f]{64}$/).optional(),
-      metadata: z.record(z.string(), z.any()).optional(),
-      origin: originSchema,
-      idempotencyKey: z.string().min(1).max(240).optional(),
-    },
+    description: "The only Deal mutation tool. Pass one command: input.submit, information.put, page.patch, or artifact.put. All Page content fields are Agent-writable; author controls attribution, not permission. Use the bootstrap field contract and bilingual Page prose. page.patch is JSON Merge Patch: arrays replace whole arrays, so read-modify-write and preserve sibling slots.",
+    // MCP SDK 1.30 only publishes object schemas at the tool root. Nesting one
+    // command preserves the real discriminated union instead of flattening four
+    // incompatible operations into false affordances.
+    inputSchema: { command: writeDealCommandSchema },
   },
-  async (input) => callApi("POST", "/api/occam/deals/commands", prepareDealCommand("write", input)),
+  async ({ command }) => callApi(
+    "POST",
+    "/api/occam/deals/commands",
+    prepareDealCommand("write", command),
+    (result) => compactDealWriteResult(command, result),
+  ),
 );
 
 server.registerTool(
@@ -158,7 +191,12 @@ server.registerTool(
   async ({ limit } = {}) => {
     const params = new URLSearchParams({ clientVersion: PKG_VERSION });
     if (limit) params.set("limit", String(limit));
-    return callApi("GET", `/api/agent/manifest?${params}`);
+    try {
+      const result = await request("GET", `/api/agent/manifest?${params}`);
+      return textResult(JSON.stringify(structuredBootstrapManifest(result), null, 2));
+    } catch (error) {
+      return textResult(formatErrorForDisplay(error), true);
+    }
   },
 );
 

package/bin/llama.mjs

@@ -4,6 +4,7 @@ import { createRequire } from "node:module";
 import { readFile } from "node:fs/promises";
 import readline from "node:readline";
 import {
+  formatErrorForDisplay,
   getAuthHeaders,
   getBaseUrl,
   getToken,
@@ -12,6 +13,7 @@ import {
   readCanonicalToken,
   readLegacyConfig,
   request,
+  structuredBootstrapManifest,
   tryGcloudIdentityToken,
   writeCanonicalToken,
   writeLegacyConfig,
@@ -33,6 +35,7 @@ import {
   DEAL_ACTIONS,
   buildDealReadPath,
   buildDealSearchPath,
+  compactDealWriteResult,
   prepareDealCommand,
   readJsonInput,
 } from "../lib/deal-actions.mjs";
@@ -82,8 +85,14 @@ read-modify-write complete Page arrays and preserve sibling slots.
 create JSON:
   {"companyName":"Acme","page":{},"information":[],"origin":{"kind":"user","originalUserUtterance":"..."}}
 
-write operation:
-  input.submit | information.put | page.patch | artifact.put
+write JSON (CLI derives idempotencyKey when omitted):
+  input.submit:    {"operation":"input.submit","dealId":"<uuid>","content":"<original input>","format":"text","source":{},"origin":{"kind":"user","originalUserUtterance":"..."}}
+  information.put:{"operation":"information.put","dealId":"<uuid>","type":"founder_claim","labels":["founder-stated"],"subject":{"topic":"traction"},"value":{"content":"...","source":{"kind":"first_meeting_transcript"}},"origin":{"kind":"user","originalUserUtterance":"..."}}
+  page.patch:      {"operation":"page.patch","dealId":"<uuid>","patch":{"description":{"en":"...","zh":"..."}},"origin":{"kind":"agent"}}
+  artifact.put:    {"operation":"artifact.put","dealId":"<uuid>","kind":"deck","title":"deck.pdf","mimeType":"application/pdf","storageKey":"<drive-file-id>","storageUrl":"https://drive.google.com/...","byteSize":123,"sha256":"<64 hex>","origin":{"kind":"user","originalUserUtterance":"..."}}
+
+For Information, origin records who caused the write and preserves user words;
+value.source records where the evidence came from.
 
 Core owns Chat Records, append-only Deal Events, Drive provisioning, audit,
 and idempotency. User-originated work must preserve exact wording in
@@ -127,6 +136,28 @@ function assertDealAction(area, action) {
   }
 }
 
+const RETIRED_TOP_LEVEL_COMMANDS = Object.freeze({
+  brief: "llama deal write --json  (operation: page.patch)",
+  fact: "llama deal write --json  (operation: information.put)",
+  post: "llama deal write --json  (operation: input.submit)",
+  timeline: "llama deal read <dealId> --detail history",
+  html: "llama deal write --json  (operation: artifact.put)",
+  memo: "llama deal write --json  (operation: artifact.put)",
+  pipeline: "llama deal search|read|create|write",
+});
+
+function unknownCommandError(area, action) {
+  const replacement = RETIRED_TOP_LEVEL_COMMANDS[area];
+  if (replacement) {
+    return new Error(
+      `\`llama ${area}\` was retired in CLI 2.0.\n` +
+      `  → Use: ${replacement}\n` +
+      "  → Contract: llama agent bootstrap",
+    );
+  }
+  return new Error(`Unknown command: llama ${[area, action].filter(Boolean).join(" ")}`);
+}
+
 function onboardingNoAuth() {
   return `Llama team onboarding requires credentials.
 
@@ -441,7 +472,7 @@ async function main() {
     const params = new URLSearchParams({ clientVersion: PKG_VERSION });
     if (flags.limit && flags.limit !== true) params.set("limit", String(flags.limit));
     const manifest = await request("GET", `/api/agent/manifest?${params}`);
-    if (flags.json) print(manifest);
+    if (flags.json) print(structuredBootstrapManifest(manifest));
     else process.stdout.write(`${manifest.briefing || JSON.stringify(manifest, null, 2)}\n`);
     return;
   }
@@ -539,7 +570,9 @@ async function main() {
   if (area === "deal" && ["create", "write"].includes(action)) {
     const { flags } = parseFlags(rest, ["json"]);
     const input = await readJsonInput(flags.json);
-    print(await request("POST", "/api/occam/deals/commands", prepareDealCommand(action, input)));
+    const command = prepareDealCommand(action, input);
+    const response = await request("POST", "/api/occam/deals/commands", command);
+    print(compactDealWriteResult(command, response));
     return;
   }
 
@@ -565,12 +598,12 @@ async function main() {
     return;
   }
 
-  throw new Error(`Unknown command: llama ${[area, action].filter(Boolean).join(" ")}`);
+  throw unknownCommandError(area, action);
 }
 
 main()
   .then(() => maybeNudgeUpdate())
   .catch((error) => {
-    console.error(`Error: ${error.message}`);
+    console.error(formatErrorForDisplay(error));
     process.exit(1);
   });

package/lib/build-manifest.json

@@ -1,8 +1,8 @@
 {
   "format": "llama.cli-build.v1",
   "packageName": "@llamaventures/cli",
-  "packageVersion": "2.0.2",
-  "sourceSha": "dc52c43363b050072c70f45144909d93b4f42028",
+  "packageVersion": "2.0.3",
+  "sourceSha": "dc1618ab65b6cb2e73b107e7d56315ce2076744e",
   "sourceKind": "github",
   "sourceDirty": false,
   "coreApiContract": {

package/lib/client.mjs

@@ -534,7 +534,21 @@ function apiResponseError(data, status) {
     return error;
   }
   if (data?.code !== "MENTION_APPROVAL_REQUIRED") {
-    const error = new Error(message);
+    const issues = Array.isArray(data?.issues)
+      ? data.issues.map((issue) => {
+          const path = Array.isArray(issue?.path) && issue.path.length
+            ? issue.path.reduce(
+                (result, part) => typeof part === "number"
+                  ? `${result}[${part}]`
+                  : result ? `${result}.${part}` : String(part),
+                "",
+              )
+            : "$";
+          const detail = issue?.message || issue?.code || "Invalid value";
+          return `- ${path}: ${detail}`;
+        })
+      : [];
+    const error = new Error([message, ...issues].join("\n"));
     if (typeof data?.code === "string") error.code = data.code;
     error.details = data;
     error.status = status;
@@ -563,6 +577,21 @@ function apiResponseError(data, status) {
   return error;
 }
 
+export function formatErrorForDisplay(error) {
+  const message = error?.message ?? String(error);
+  if (/^Error(?:\[[^\]]+\])?:/u.test(message)) return message;
+  const code = typeof error?.code === "string" ? `[${error.code}]` : "";
+  return `Error${code}: ${message}`;
+}
+
+export function structuredBootstrapManifest(manifest) {
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+    return manifest;
+  }
+  const { briefing: _renderedDuplicate, ...structured } = manifest;
+  return structured;
+}
+
 async function requestWithRetry(method, endpoint, body, opts, allowRetry) {
   const authHeaders = await getAuthHeaders();
   if (Object.keys(authHeaders).length === 0) throw noAuthError();

package/lib/deal-actions.mjs

@@ -72,62 +72,6 @@ function validateLocalizedTextPairs(value, path = "page") {
   }
 }
 
-const LANGUAGE_NEUTRAL_PAGE_KEYS = new Set([
-  "companyName", "companyKey", "state", "pipelineStatus", "stage",
-  "theirStage", "ownerUserId", "sourceUserId", "website", "dealOwner",
-  "source", "sourceDirection", "proposedAmount", "roundSize", "valuation",
-  "founders", "deckLink", "location", "foundedYear", "leadInvestor",
-  "dateAdded", "tab", "sourcePerson", "createdByName", "createdByLabel",
-  "createdVia", "id", "name", "key", "slug", "url", "href", "email",
-  "linkedin", "handle", "status", "kind", "type", "tier", "confidence",
-  "currency", "unit", "format", "mimeType", "sha256", "timestamp",
-  "date", "year",
-]);
-const LANGUAGE_NEUTRAL_PAGE_CONTAINERS = new Set([
-  "manualTags", "investors", "founderEmails", "labels", "tags",
-]);
-const OPAQUE_PAGE_CONTAINERS = new Set([
-  "migration", "extra", "fieldProvenance",
-]);
-
-function pathKeys(path) {
-  return path.match(/[^.[\]]+/g)?.filter((part) => !/^\d+$/u.test(part)) ?? [];
-}
-
-function isLanguageNeutralPagePath(path) {
-  const keys = pathKeys(path);
-  if (keys.some((key) => OPAQUE_PAGE_CONTAINERS.has(key))) return true;
-  if (keys.some((key) => LANGUAGE_NEUTRAL_PAGE_CONTAINERS.has(key))) return true;
-  const key = keys.at(-1) ?? "";
-  if (LANGUAGE_NEUTRAL_PAGE_KEYS.has(key)) return true;
-  return /(?:Id|Ids|URL|Url|URI|Uri|Link|Email|Emails|At|Date|Year|Key|Slug|Hash)$/u.test(key);
-}
-
-function validateAgentAuthoredPageProse(value, path = "page") {
-  if (typeof value === "string") {
-    if (!isLanguageNeutralPagePath(path)) {
-      throw new Error(
-        `${path} agent-authored prose must be one value with non-empty en and zh`,
-      );
-    }
-    return;
-  }
-  if (Array.isArray(value)) {
-    value.forEach((item, index) => validateAgentAuthoredPageProse(item, `${path}[${index}]`));
-    return;
-  }
-  if (!value || typeof value !== "object") return;
-  if (
-    Object.prototype.hasOwnProperty.call(value, "en") ||
-    Object.prototype.hasOwnProperty.call(value, "zh")
-  ) {
-    return;
-  }
-  for (const [key, child] of Object.entries(value)) {
-    validateAgentAuthoredPageProse(child, `${path}.${key}`);
-  }
-}
-
 export async function readJsonInput(path, stdin = process.stdin) {
   if (!path || path === true) throw new Error("--json <file|-> is required");
   const text = path === "-"
@@ -170,6 +114,32 @@ export function buildDealReadPath(dealId, detail = "overview") {
   return `/api/occam/deals/${encodeURIComponent(dealId)}${expansion ? `?expand=${expansion}` : ""}`;
 }
 
+/**
+ * page.patch previously echoed the entire Live Deal Page after every write.
+ * Keep the authoritative revision receipt and tell the Agent exactly what to
+ * read back, without paying another full-page context cost before verification.
+ */
+export function compactDealWriteResult(command, response) {
+  if (command?.operation !== "page.patch" || !response?.result?.page) return response;
+  const page = response.result.page;
+  return {
+    ...response,
+    result: {
+      idempotent: Boolean(response.result.idempotent),
+      page: {
+        id: page.id,
+        revision: page.revision,
+        updatedAt: page.updatedAt,
+      },
+      verify: {
+        dealId: command.dealId,
+        fields: Object.keys(command.patch ?? {}),
+        command: `llama deal read ${command.dealId}`,
+      },
+    },
+  };
+}
+
 export function prepareDealCommand(action, input) {
   if (!input || typeof input !== "object" || Array.isArray(input)) {
     throw new Error("Mutation JSON must be an object");
@@ -183,11 +153,9 @@ export function prepareDealCommand(action, input) {
   }
   if (action === "create") {
     validateLocalizedTextPairs(command.page ?? {});
-    validateAgentAuthoredPageProse(command.page ?? {});
   }
   if (action === "write" && command.operation === "page.patch") {
     validateLocalizedTextPairs(command.patch ?? {});
-    validateAgentAuthoredPageProse(command.patch ?? {});
   }
   return ensureIdempotencyKey(validateCommandOrigin(command));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llamaventures/cli",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "CLI + MCP server for the Llama Ventures investment workbench (command.llamaventures.vc).",
   "type": "module",
   "scripts": {