@llamaventures/cli 2.0.3 → 2.1.1

package/AGENT_BRIEFING.md

@@ -44,6 +44,14 @@ working memory; it never becomes Page automatically. Page is the bounded,
 human-visible current projection, so patch the exact semantic fields described
 by the live contract instead of hiding structured analysis in `notes`.
 
+The Markdown Deal Story is a separate sidecar domain, not a sixth Occam
+resource. Use `get_deal_memory` / `llama memory read` for accumulated narrative
+understanding, and `update_deal_memory` / `llama memory write` to replace its
+complete Markdown. Read first and pass the returned opaque version on every
+update; a conflict means read again and reconcile. These calls still go only
+through authenticated Core. Never request AWS credentials or call S3 or the
+sidecar directly.
+
 Every Page content field is Agent-writable. A field's `author` or
 `semanticOwner` describes attribution, not permission. Preserve a real human
 judgment with its author; otherwise label the value as an Agent proposal / 待人确认.
@@ -207,4 +215,5 @@ artifact, then decide whether its content deserves Information or a Page patch.
   `DEAL_COMMAND_RETIRED`. Upgrade the CLI and retry the intended four-action
   command.
 - Wiki, admin audit, external pitch, authentication, and skill discovery are
-  separate domains. They do not expand the Deal action space.
+  separate domains. Deal Memory is also separate. None expands the four-action
+  Occam Deal space.

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+All notable changes to `@llamaventures/cli` are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+this project adheres to [Semantic Versioning](https://semver.org).
+
+## [Unreleased]
+
+## [2.1.1] - 2026-09-03
+
+### Changed
+- `llama help deal` no longer hardcodes the Page field count; the count is
+  live in `llama agent bootstrap`.
+- Show `contentBase64` as the primary `artifact.put` example. Core stores the
+  bytes in the Deal's Drive folder and derives `byteSize` / `sha256` itself;
+  `storageKey` remains only for artifacts that already live elsewhere.
+
+## [2.1.0] - 2026-09-03
+
+### Added
+- Add `llama memory read|write` and matching `get_deal_memory` /
+  `update_deal_memory` MCP tools for one canonical Markdown Deal Story, using
+  the existing Llama login through Core's authenticated sidecar adapter.
+
+### Changed
+- Make the authenticated live bootstrap mandatory before Deal work and clarify
+  that it loads the server-owned two-part private Brain plus the separate Live
+  Deal Page field contract. CLI remains only the tool/transport layer.
+- Teach CLI and MCP Agents that Information never updates Page automatically,
+  every Page content field is Agent-writable, and field authorship controls
+  attribution rather than permission.
+- Pin the additive Deal Memory operations to Core API 5.1.0 while preserving
+  exactly four Occam Deal actions and five Occam resources.
+
 ## [2.0.3] - 2026-08-31
 
 - Show Core validation codes and field paths instead of collapsing malformed
@@ -49,20 +81,6 @@
 - Keep Wiki, admin audit, external pitch, authentication, preferences, and
   progressive skill discovery as separate non-Deal domains.
 
-All notable changes to `@llamaventures/cli` are documented here.
-The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
-this project adheres to [Semantic Versioning](https://semver.org).
-
-## [Unreleased]
-
-### Changed
-- Make the authenticated live bootstrap mandatory before Deal work and clarify
-  that it loads the server-owned two-part private Brain plus the separate Live
-  Deal Page field contract. CLI remains only the tool/transport layer.
-- Teach CLI and MCP Agents that Information never updates Page automatically,
-  every Page content field is Agent-writable, and field authorship controls
-  attribution rather than permission.
-
 ## [1.26.0] - 2026-08-11
 
 ### Added

package/README.md

@@ -122,6 +122,27 @@ For user-originated work, preserve the exact words in
 Chat and Event are system-owned. There is no caller-controlled Event append or
 general Chat-forging operation.
 
+## Deal Memory sidecar
+
+Deal Memory is a separate domain alongside the five-resource Deal model. Each
+deal can have one canonical, human-readable Markdown Deal Story:
+
+```bash
+llama memory read <dealId>
+llama memory read <dealId> --raw
+llama memory write <dealId> --markdown deal-story.md
+llama memory write <dealId> --markdown deal-story.md --expected-version '"etag-from-read"'
+```
+
+The first write omits `--expected-version`. Updating an existing story requires
+the opaque `version` returned by `read`; a stale value fails instead of losing a
+concurrent edit. This uses the same `llama auth login` identity. CLI calls the
+authenticated Command Core adapter only—it has no sidecar URL, service token,
+S3 credentials, or direct database access.
+
+`llama deal read --detail memory` still means structured Deal Information.
+`llama memory read` means the separate accumulated Markdown Deal Story.
+
 ## Five Deal resources
 
 1. Live Deal Page — current human-visible state.
@@ -149,7 +170,9 @@ Its Deal surface is also exactly four tools:
 - `write_deal`
 
 Authentication, skill discovery, Wiki, admin audit, preferences, and external
-pitch remain separate non-Deal domains.
+pitch remain separate non-Deal domains. Deal Memory likewise has two separate
+MCP tools, `get_deal_memory` and `update_deal_memory`; it does not add a fifth
+Occam Deal tool.
 
 ## Agent bootstrap
 

package/README.zh-CN.md

@@ -116,6 +116,26 @@ llama deal write --json write.json
 Chat 和 Event 由系统拥有。Agent 不能自行伪造 Event 类型、顺序、作者、
 时间，也没有通用的 Chat 写入工具。
 
+## Deal Memory sidecar
+
+Deal Memory 是与五资源 Deal 模型并行、完全解耦的领域。每个 Deal 可以有一个
+人和 Agent 都能直接阅读的 Markdown Deal Story：
+
+```bash
+llama memory read <dealId>
+llama memory read <dealId> --raw
+llama memory write <dealId> --markdown deal-story.md
+llama memory write <dealId> --markdown deal-story.md --expected-version '"read 返回的 etag"'
+```
+
+第一次创建时不传 `--expected-version`；以后更新必须使用前一次 `read` 返回的
+不透明 `version`，旧版本会安全失败，不会覆盖他人的新内容。它复用同一个
+`llama auth login` 身份。CLI 只调用经过认证的 Command Core adapter，不持有
+sidecar URL、service token、S3 凭证，也不直接访问数据库。
+
+`llama deal read --detail memory` 仍表示结构化 Deal Information；
+`llama memory read` 表示独立的 Markdown Deal Story。
+
 ## Deal 只有五种业务资源
 
 1. Live Deal Page：人类看到的当前状态；
@@ -141,7 +161,9 @@ MCP 的 Deal 工具同样恰好四个：
 - `write_deal`
 
 认证、skill discovery、Wiki、admin audit、preferences 和 external pitch
-属于其他独立领域，不会扩大 Deal action space。
+属于其他独立领域，不会扩大 Deal action space。Deal Memory 同样是独立领域，
+对应 `get_deal_memory` 和 `update_deal_memory` 两个 MCP 工具，并不增加第五个
+Occam Deal 工具。
 
 ## Agent 启动
 

package/bin/llama-mcp.mjs

@@ -25,6 +25,7 @@ import {
   compactDealWriteResult,
   prepareDealCommand,
 } from "../lib/deal-actions.mjs";
+import { buildDealMemoryPath } from "../lib/deal-memory-actions.mjs";
 
 const requireFromHere = createRequire(import.meta.url);
 const { version: PKG_VERSION } = requireFromHere("../package.json");
@@ -164,6 +165,36 @@ server.registerTool(
   ),
 );
 
+// Deal Memory is a separate sidecar domain. These do not add an Occam Deal
+// business resource or widen the deliberately closed four-tool Deal surface.
+server.registerTool(
+  "get_deal_memory",
+  {
+    description: "Read the complete canonical Markdown Deal Story and its opaque concurrency version.",
+    inputSchema: { dealId: z.string().uuid() },
+  },
+  // @core-api-operation GET /api/deal-memory/{dealId}/story
+  async ({ dealId }) => callApi("GET", buildDealMemoryPath(dealId)),
+);
+
+server.registerTool(
+  "update_deal_memory",
+  {
+    description: "Create or replace the complete Markdown Deal Story. Existing stories require the version returned by get_deal_memory; stale writes fail safely.",
+    inputSchema: {
+      dealId: z.string().uuid(),
+      markdown: z.string().min(1).max(1_048_576),
+      expected_version: z.string().min(1).optional(),
+    },
+  },
+  // @core-api-operation PUT /api/deal-memory/{dealId}/story
+  async ({ dealId, markdown, expected_version }) => callApi(
+    "PUT",
+    buildDealMemoryPath(dealId),
+    { markdown, ...(expected_version ? { expected_version } : {}) },
+  ),
+);
+
 server.registerTool(
   "auth_status",
   {

package/bin/llama.mjs

@@ -39,6 +39,10 @@ import {
   prepareDealCommand,
   readJsonInput,
 } from "../lib/deal-actions.mjs";
+import {
+  buildDealMemoryPath,
+  readMarkdownInput,
+} from "../lib/deal-memory-actions.mjs";
 
 const requireFromHere = createRequire(import.meta.url);
 const { version: PKG_VERSION } = requireFromHere("../package.json");
@@ -51,6 +55,10 @@ Deal has exactly four actions:
   llama deal create --json <file|->
   llama deal write --json <file|->
 
+Deal Memory is a separate sidecar domain through the same login:
+  llama memory read <dealId> [--raw]
+  llama memory write <dealId> --markdown <file|-> [--expected-version <version>]
+
 Separate preserved domains:
   llama auth status|login|logout
   llama token set|show
@@ -77,8 +85,9 @@ Before any Page write:
 
 The authenticated bootstrap contains the two-part private Llama Brain:
 Investment Framework V3 plus the Llama Command operating skill. It also
-contains the separate current 61-field Page contract. CLI is the tool, not
-Brain. Information never updates Page automatically. page.patch is JSON
+contains the separate current Page field contract; its field count is live,
+so read it there. CLI is the tool, not Brain. Information never updates
+Page automatically. page.patch is JSON
 Merge Patch: objects merge, null deletes, and arrays replace whole arrays, so
 read-modify-write complete Page arrays and preserve sibling slots.
 
@@ -89,7 +98,13 @@ 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":"..."}}
+  artifact.put:    {"operation":"artifact.put","dealId":"<uuid>","kind":"deck","title":"deck.pdf","mimeType":"application/pdf","contentBase64":"<file bytes, base64>","origin":{"kind":"user","originalUserUtterance":"..."}}
+
+artifact.put sends the bytes as contentBase64; Core stores them in the Deal's
+own Drive folder and derives byteSize and sha256 itself. Do not supply a
+folder, storage key or URL for a file you hold. Write the JSON to a file and
+pass its path. Only an artifact that already lives elsewhere is referenced
+with storageKey (+ optional storageUrl) plus byteSize and sha256 instead.
 
 For Information, origin records who caused the write and preserves user words;
 value.source records where the evidence came from.
@@ -98,6 +113,19 @@ Core owns Chat Records, append-only Deal Events, Drive provisioning, audit,
 and idempotency. User-originated work must preserve exact wording in
 origin.originalUserUtterance or reference origin.originatingChatRecordId.`;
 
+const HELP_MEMORY = `Llama Deal Memory — one canonical Markdown Deal Story
+
+  llama memory read <dealId> [--raw]
+  llama memory write <dealId> --markdown <file|-> [--expected-version <version>]
+
+Read returns the full JSON record, including its opaque version. --raw prints
+only the exact Markdown. A first write creates the story without a version.
+Every later write must pass the version from the preceding read; stale writes
+fail instead of overwriting newer understanding.
+
+This uses your existing Llama authentication. The CLI talks only to Command
+Core and never receives Deal Memory service credentials or AWS access.`;
+
 function parseFlags(args, allowed = null) {
   const flags = {};
   const positional = [];
@@ -124,7 +152,7 @@ function parseFlags(args, allowed = null) {
 }
 
 function usage(area) {
-  console.log(area === "deal" ? HELP_DEAL : HELP_ROOT);
+  console.log(area === "deal" ? HELP_DEAL : area === "memory" ? HELP_MEMORY : HELP_ROOT);
 }
 
 function assertDealAction(area, action) {
@@ -576,6 +604,32 @@ async function main() {
     return;
   }
 
+  if (area === "memory" && action === "read") {
+    const { flags, positional } = parseFlags(rest, ["raw"]);
+    const path = buildDealMemoryPath(positional[0]);
+    // @core-api-operation GET /api/deal-memory/{dealId}/story
+    const result = await request("GET", path);
+    if (flags.raw) process.stdout.write(result.markdown);
+    else print(result);
+    return;
+  }
+  if (area === "memory" && action === "write") {
+    const { flags, positional } = parseFlags(rest, ["markdown", "expected-version"]);
+    const path = buildDealMemoryPath(positional[0]);
+    const markdown = await readMarkdownInput(flags.markdown);
+    // @core-api-operation PUT /api/deal-memory/{dealId}/story
+    print(await request("PUT", path, {
+      markdown,
+      ...(typeof flags["expected-version"] === "string"
+        ? { expected_version: flags["expected-version"] }
+        : {}),
+    }));
+    return;
+  }
+  if (area === "memory") {
+    throw new Error("Memory actions: read, write.");
+  }
+
   if (area === "wiki") {
     await handleWiki(action, rest);
     return;

package/contracts/core-api.json

@@ -1,9 +1,9 @@
 {
   "format": "llama.core-api-contract.v1",
   "name": "llama-core-api",
-  "apiVersion": "5.0.0",
+  "apiVersion": "5.1.0",
   "openapiVersion": "3.0.3",
-  "sha256": "c48ed580f9930b06445f62b94959a2ca4bf9780e59473f17588e1e6554914014",
-  "pathCount": 110,
-  "operationCount": 136
+  "sha256": "948a8d02ae833e8cfa2302bc3c615fc1d3c792ae774ebc25b16be81fd1b85fee",
+  "pathCount": 111,
+  "operationCount": 138
 }

package/contracts/required-operations.json

@@ -12,6 +12,7 @@
     { "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" },
@@ -28,6 +29,7 @@
     { "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": "POST", "path": "/api/wiki/save" },
+    { "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.0.3",
-  "sourceSha": "dc1618ab65b6cb2e73b107e7d56315ce2076744e",
+  "packageVersion": "2.1.1",
+  "sourceSha": "335bf5d6c510d38616754100568a64f385d62607",
   "sourceKind": "github",
   "sourceDirty": false,
   "coreApiContract": {
     "format": "llama.core-api-contract.v1",
     "name": "llama-core-api",
-    "apiVersion": "5.0.0",
+    "apiVersion": "5.1.0",
     "openapiVersion": "3.0.3",
-    "sha256": "c48ed580f9930b06445f62b94959a2ca4bf9780e59473f17588e1e6554914014"
+    "sha256": "948a8d02ae833e8cfa2302bc3c615fc1d3c792ae774ebc25b16be81fd1b85fee"
   }
 }

package/lib/client.mjs

@@ -294,6 +294,9 @@ function inferCommand(method, endpoint) {
   if (pathname === "/api/occam/deals") return "deal.search";
   if (pathname === "/api/occam/deals/commands") return "deal.write";
   if (/^\/api\/occam\/deals\/[^/]+$/.test(pathname)) return "deal.read";
+  if (/^\/api\/deal-memory\/[^/]+\/story$/.test(pathname)) {
+    return verb === "GET" ? "memory.read" : "memory.write";
+  }
   if (pathname === "/api/me") return "auth.status";
   if (pathname.startsWith("/api/agent/skills")) return "skills.read";
   if (pathname === "/api/agent/manifest") return "agent.bootstrap";

package/lib/deal-memory-actions.mjs

@@ -0,0 +1,31 @@
+import { readFile } from "node:fs/promises";
+
+export const MAX_DEAL_STORY_BYTES = 1_048_576;
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export function buildDealMemoryPath(dealId) {
+  if (!UUID.test(String(dealId || ""))) {
+    throw new Error("Deal Memory requires a valid deal UUID");
+  }
+  return `/api/deal-memory/${encodeURIComponent(dealId)}/story`;
+}
+
+export async function readMarkdownInput(path, stdin = process.stdin) {
+  if (!path || path === true) throw new Error("--markdown <file|-> is required");
+  const markdown = path === "-"
+    ? await new Promise((resolve, reject) => {
+        let value = "";
+        stdin.setEncoding("utf8");
+        stdin.on("data", (chunk) => { value += chunk; });
+        stdin.on("end", () => resolve(value));
+        stdin.on("error", reject);
+      })
+    : await readFile(path, "utf8");
+  if (!markdown) throw new Error("Deal Story Markdown cannot be empty");
+  const bytes = Buffer.byteLength(markdown, "utf8");
+  if (bytes > MAX_DEAL_STORY_BYTES) {
+    throw new Error(`Deal Story is ${bytes} bytes; maximum is ${MAX_DEAL_STORY_BYTES}`);
+  }
+  return markdown;
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@llamaventures/cli",
-  "version": "2.0.3",
+  "version": "2.1.1",
   "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/build-manifest.test.mjs scripts/core-api-call-sites.test.mjs scripts/deal-actions-cli.test.mjs scripts/deal-actions.test.mjs scripts/mcp-four-action-surface.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/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/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",