@llamaventures/cli 2.2.0 → 2.4.0

package/AGENT_BRIEFING.md

@@ -168,9 +168,11 @@ means the truth depends on who judges: a value or comparative word with no
 stated benchmark, or a claim about someone's future behavior or inner state. If
 yes, the type is `human_subjective_view.people` (founders or team) or
 `human_subjective_view.business` (company, product, market or deal),
-`value.speaker` names that user, and `value.rawText` quotes the user verbatim
-from `origin.originalUserUtterance`. CLI and Core reject anything else. If no,
-choose any type that fits; founder words are `founder_claim`.
+`value.speaker` names that user, `value.rawText` quotes the user verbatim
+from `origin.originalUserUtterance`, and `value.summary` is your own
+restatement of those words (never a substitute for them). CLI and Core reject
+anything else. If no, choose any type that fits; founder words are
+`founder_claim`.
 
 ```json
 {

package/CHANGELOG.md

@@ -6,6 +6,22 @@ this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-09-09
+
+### Added
+
+- Read Deal artifact text and original bytes through Core with version/hash provenance.
+- Read Wiki uploads and supported page references; paginate text with a pinned source hash.
+- Verify source downloads and refuse to overwrite local files.
+
+## [2.3.0] - 2026-09-04
+
+### Changed
+- `human_subjective_view.people|business` now also requires `value.summary`,
+  the agent's own restatement of the user's words, and rejects a summary that
+  merely repeats `value.rawText`. Core enforces the same rule; the Deal Page
+  shows both the summary and the verbatim text.
+
 ## [2.2.0] - 2026-09-04
 
 ### Added

package/README.md

@@ -214,3 +214,17 @@ npm run verify:release
 
 Release artifacts are source-SHA certified. Publishing to npm and changing the
 production server's minimum version are separate, explicit release operations.
+
+### Read original source content
+
+Use `llama deal read <dealId> --artifact <artifactId>` to read a listed file's text,
+source hash and page/paragraph anchors. Use `llama wiki read <slug> --format text`
+for a Wiki page or its original uploaded document. `--attachment <referenceId>`
+follows a supported reference listed by the Wiki read. Long reads return
+`nextOffset`; continue with `--offset N --sha256 HASH`. `--output <file>` downloads
+and hash-verifies the original bytes without overwriting a local file.
+
+These options require a Core version with source-content reads. Scanned PDFs
+may require OCR; no-text, missing files, unsupported formats and denied storage
+are explicit outcomes, not evidence that a memo has been read. MCP exposes the
+same text reads inside `read_deal` and `wiki_read`.

package/README.zh-CN.md

@@ -204,3 +204,14 @@ npm run verify:release
 
 发布包会绑定准确 source SHA。npm publish 与生产服务端强制最低版本是两个
 独立、需要明确授权的 release 动作。
+
+### 读取原始材料
+
+`llama deal read <dealId> --artifact <artifactId>` 读取文件正文、原文件哈希与页码／段落位置。
+`llama wiki read <slug> --format text` 读取 Wiki 正文或上传的原文件；
+`--attachment <referenceId>` 读取页面返回的受支持附件引用。
+长文用 `--offset <nextOffset> --sha256 <source.sha256>` 继续，文件变化时会拒绝拼接。
+`--output <文件路径>` 下载并核验原始字节，不覆盖已有文件。
+
+需要服务端支持正文读取。扫描 PDF 不自动 OCR；无文字、缺失文件、不支持的格式、
+权限不足都会明确报告。MCP 在原有 `read_deal` 和 `wiki_read` 中提供相同正文读取能力。

package/bin/llama-mcp.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { buildArtifactReadPath, buildWikiReadPath } from "../lib/content-read.mjs";
 import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -123,14 +124,27 @@ server.registerTool(
 server.registerTool(
   "read_deal",
   {
-    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.",
+    description: "Read one Deal. Live Page is current human-visible state; Information is memory and never updates Page automatically. Use artifactId to read original source text with page/paragraph anchors. Continue with nextOffset and source.sha256. 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(),
+      artifactId: z.string().uuid().optional(),
+      version: z.number().int().min(1).optional(),
+      offset: z.number().int().min(0).optional(),
+      limit: z.number().int().min(1).max(50000).optional(),
+      sha256: z.string().regex(/^[a-f0-9]{64}$/).optional(),
     },
   },
-  // @core-api-operation GET /api/occam/deals/{dealId}
-  async ({ dealId, detail }) => callApi("GET", buildDealReadPath(dealId, detail || "overview")),
+  async ({ dealId, detail, artifactId, ...options }) => {
+    if (artifactId) {
+      if (detail) throw new Error("Use artifactId or detail, not both");
+      // @core-api-operation GET /api/occam/deals/{dealId}/artifacts/{artifactId}
+      return callApi("GET", buildArtifactReadPath(dealId, artifactId, options));
+    }
+    if (Object.values(options).some(value => value !== undefined)) throw new Error("Content options require artifactId");
+    // @core-api-operation GET /api/occam/deals/{dealId}
+    return callApi("GET", buildDealReadPath(dealId, detail || "overview"));
+  },
 );
 
 server.registerTool(
@@ -152,7 +166,7 @@ server.registerTool(
 server.registerTool(
   "write_deal",
   {
-    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. Before page.patch, use get_live_deal_page_schema for the exact fields being changed and write bilingual Page prose. page.patch is JSON Merge Patch: arrays replace whole arrays, so read-modify-write and preserve sibling slots. A Llama user's own judgment is human_subjective_view.people or human_subjective_view.business and must carry value.speaker plus value.rawText quoted verbatim from origin.originalUserUtterance; it is rejected otherwise.",
+    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. Before page.patch, use get_live_deal_page_schema for the exact fields being changed and write bilingual Page prose. page.patch is JSON Merge Patch: arrays replace whole arrays, so read-modify-write and preserve sibling slots. A Llama user's own judgment is human_subjective_view.people or human_subjective_view.business and must carry value.speaker, value.rawText quoted verbatim from origin.originalUserUtterance, and value.summary (the agent's restatement); it is rejected otherwise.",
     // 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.
@@ -344,11 +358,16 @@ server.registerTool(
 server.registerTool(
   "wiki_read",
   {
-    description: "Read one Wiki article by exact slug.",
-    inputSchema: { slug: z.string().min(1), lang: z.enum(["en", "zh"]).optional() },
+    description: "Read one Wiki article. format=text extracts its original upload or page body. attachment follows an ID listed in attachments. Continuations require offset and sha256.",
+    inputSchema: {
+      slug: z.string().min(1), lang: z.enum(["en", "zh"]).optional(),
+      format: z.literal("text").optional(), attachment: z.string().optional(),
+      offset: z.number().int().min(0).optional(), limit: z.number().int().min(1).max(50000).optional(),
+      sha256: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    },
   },
-  async ({ slug, lang }) =>
-    callApi("GET", `/api/wiki/${encodeURIComponent(slug)}?lang=${lang === "zh" ? "zh" : "en"}`),
+  // @core-api-operation GET /api/wiki/{slug}
+  async ({ slug, ...options }) => callApi("GET", buildWikiReadPath(slug, options)),
 );
 
 server.registerTool(

package/bin/llama.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { buildArtifactReadPath, buildWikiReadPath, saveContentSource } from "../lib/content-read.mjs";
 import { createRequire } from "node:module";
 import { readFile } from "node:fs/promises";
 import readline from "node:readline";
@@ -70,6 +71,8 @@ Separate preserved domains:
   llama skills list|search|show
   llama pref list|add|approve|retire
   llama explain <url-or-object>
+  llama deal read <dealId> --artifact <artifactId> [--version N] [--offset N --sha256 HASH] [--limit N] [--output <file>]
+  llama wiki read <slug> --format text [--attachment <referenceId>] [--offset N --sha256 HASH] [--output <file>]
   llama wiki search|read|save|delete|restore
   llama admin auth-events|deal-events|agent-events
   llama pitch start|say|upload|status|finalize|end
@@ -84,6 +87,15 @@ Exactly four actions:
   llama deal create --json <file|->
   llama deal write --json <file|->
 
+Read original source content:
+  llama deal read <dealId> --artifact <artifactId> [--version N] [--offset N --sha256 HASH] [--limit N] [--output <file>]
+  llama wiki read <slug> --format text [--attachment <referenceId>] [--offset N --sha256 HASH] [--output <file>]
+
+Artifact reads return source hashes, text and page/paragraph anchors. Continue with
+--offset <nextOffset> --sha256 <source.sha256>. --output saves verified original
+bytes without overwriting existing files. Wiki --format text reads the original
+upload when present; --attachment follows a reference listed by the page.
+
 Before any Page write:
   llama agent bootstrap
   llama page-schema read <field> [field...]
@@ -103,7 +115,7 @@ create JSON:
 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":"..."}}
-  human judgment:  {"operation":"information.put","dealId":"<uuid>","type":"human_subjective_view.people","subject":{"topic":"founder_execution"},"value":{"speaker":"<Llama user>","rawText":"<the user's verbatim words>","summary":"<optional agent summary>"},"origin":{"kind":"user","originalUserUtterance":"<complete user input; must contain rawText>"}}
+  human judgment:  {"operation":"information.put","dealId":"<uuid>","type":"human_subjective_view.people","subject":{"topic":"founder_execution"},"value":{"speaker":"<Llama user>","rawText":"<the user's verbatim words>","summary":"<the agent's restatement>"},"origin":{"kind":"user","originalUserUtterance":"<complete user input; must contain rawText>"}}
   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","contentBase64":"<file bytes, base64>","origin":{"kind":"user","originalUserUtterance":"..."}}
 
@@ -119,8 +131,9 @@ value.source records where the evidence came from.
 human_subjective_view.people|business is a Llama user's own judgment about the
 team or the deal. Subjective = the truth depends on who judges: a value or
 comparative word with no benchmark, or a claim about someone's future behavior
-or inner state. It requires value.speaker and value.rawText quoted verbatim from
-origin.originalUserUtterance; CLI and Core reject anything else. Other types are free.
+or inner state. It requires value.speaker, value.rawText quoted verbatim from
+origin.originalUserUtterance, and value.summary, the agent's own restatement of
+those words; CLI and Core reject anything else. Other types are free.
 
 Core owns Chat Records, append-only Deal Events, Drive provisioning, audit,
 and idempotency. User-originated work must preserve exact wording in
@@ -460,7 +473,7 @@ async function handleWiki(action, rest) {
   if (action === "read") {
     if (!slug) throw new Error("Usage: llama wiki read <slug> [--lang en|zh]");
     // @core-api-operation GET /api/wiki/{slug}
-    print(await request("GET", `/api/wiki/${encodeURIComponent(slug)}?lang=${flags.lang === "zh" ? "zh" : "en"}`));
+    print(await saveContentSource(await request("GET", buildWikiReadPath(slug, flags)), flags.output));
     return;
   }
   if (action === "save") {
@@ -656,9 +669,17 @@ async function main() {
   }
   if (area === "deal" && action === "read") {
     const dealId = rest[0];
-    const { flags } = parseFlags(rest.slice(1), ["detail"]);
-    // @core-api-operation GET /api/occam/deals/{dealId}
-    print(await request("GET", buildDealReadPath(dealId, flags.detail === true ? "overview" : flags.detail || "overview")));
+    const { flags } = parseFlags(rest.slice(1), ["detail", "artifact", "version", "format", "offset", "limit", "sha256", "output"]);
+    if (flags.artifact !== undefined) {
+      if (flags.detail !== undefined) throw new Error("Use --artifact or --detail, not both");
+      // @core-api-operation GET /api/occam/deals/{dealId}/artifacts/{artifactId}
+      const result = await request("GET", buildArtifactReadPath(dealId, flags.artifact, flags));
+      print(await saveContentSource(result, flags.output));
+    } else {
+      if (["version", "format", "offset", "limit", "sha256", "output"].some(key => flags[key] !== undefined)) throw new Error("Content options require --artifact");
+      // @core-api-operation GET /api/occam/deals/{dealId}
+      print(await request("GET", buildDealReadPath(dealId, flags.detail === true ? "overview" : flags.detail || "overview")));
+    }
     return;
   }
   if (area === "deal" && ["create", "write"].includes(action)) {

package/contracts/core-api.json

@@ -1,9 +1,9 @@
 {
   "format": "llama.core-api-contract.v1",
   "name": "llama-core-api",
-  "apiVersion": "5.3.0",
+  "apiVersion": "5.8.0",
   "openapiVersion": "3.0.3",
-  "sha256": "b793f67038b48cdfbfcc9141153132689c40e84adfbe087b0dbef3a409f5e5d5",
+  "sha256": "ec68e92362c9f60eee94b81d73fb7cff2868c80d7c17c24a9e3122cc2743e7ad",
   "pathCount": 113,
   "operationCount": 140
 }

package/contracts/required-operations.json

@@ -18,6 +18,7 @@
     { "method": "GET", "path": "/api/oauth/authorize" },
     { "method": "GET", "path": "/api/occam/deals" },
     { "method": "GET", "path": "/api/occam/deals/{dealId}" },
+    { "method": "GET", "path": "/api/occam/deals/{dealId}/artifacts/{artifactId}" },
     { "method": "GET", "path": "/api/wiki/{slug}" },
     { "method": "GET", "path": "/api/wiki/search" },
     { "method": "PATCH", "path": "/api/agent/preferences/{id}" },

package/lib/build-manifest.json

@@ -1,15 +1,15 @@
 {
   "format": "llama.cli-build.v1",
   "packageName": "@llamaventures/cli",
-  "packageVersion": "2.2.0",
-  "sourceSha": "2f4c73310ed6c5d36a47a275490ff1082321ca27",
+  "packageVersion": "2.4.0",
+  "sourceSha": "5f2e08c216a111bc568e7dee925aa198674c6255",
   "sourceKind": "github",
   "sourceDirty": false,
   "coreApiContract": {
     "format": "llama.core-api-contract.v1",
     "name": "llama-core-api",
-    "apiVersion": "5.3.0",
+    "apiVersion": "5.8.0",
     "openapiVersion": "3.0.3",
-    "sha256": "b793f67038b48cdfbfcc9141153132689c40e84adfbe087b0dbef3a409f5e5d5"
+    "sha256": "ec68e92362c9f60eee94b81d73fb7cff2868c80d7c17c24a9e3122cc2743e7ad"
   }
 }

package/lib/client.mjs

@@ -291,6 +291,7 @@ function inferCommand(method, endpoint) {
   if (pathname === "/api/wiki/search") return "wiki.search";
   if (pathname === "/api/wiki/save") return "wiki.save";
   if (/^\/api\/wiki\/[^/]+$/.test(pathname)) return verb === "GET" ? "wiki.read" : "wiki.write";
+  if (/^\/api\/occam\/deals\/[^/]+\/artifacts\/[^/]+$/.test(pathname)) return "deal.read";
   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";

package/lib/content-read.mjs

@@ -0,0 +1,49 @@
+import { createHash } from "node:crypto";
+import { writeFile } from "node:fs/promises";
+
+function parameters(options) {
+  const params = new URLSearchParams();
+  const format = options.output ? "source" : options.format || "text";
+  if (!["text", "source"].includes(format)) throw new Error("--format must be text or source");
+  params.set("format", format);
+  for (const [key, min, max] of [["version", 1, Number.MAX_SAFE_INTEGER], ["offset", 0, 2000000], ["limit", 1, 50000]]) {
+    if (options[key] === undefined) continue;
+    if (!/^\d+$/.test(String(options[key])) || !Number.isSafeInteger(Number(options[key])) || Number(options[key]) < min || Number(options[key]) > max) throw new Error(`Invalid --${key}`);
+    params.set(key, String(options[key]));
+  }
+  if (options.sha256 !== undefined) {
+    if (!/^[a-f0-9]{64}$/.test(options.sha256)) throw new Error("Invalid --sha256");
+    params.set("sha256", options.sha256);
+  }
+  if (Number(options.offset) > 0 && !options.sha256) throw new Error("Continuation reads require --sha256 from the first response");
+  if (options.output !== undefined && (typeof options.output !== "string" || !options.output)) throw new Error("--output requires a file path");
+  return params;
+}
+
+export function buildArtifactReadPath(dealId, artifactId, options = {}) {
+  if (typeof dealId !== "string" || !dealId || typeof artifactId !== "string" || !artifactId) throw new Error("Usage: llama deal read <dealId> --artifact <artifactId>");
+  return `/api/occam/deals/${encodeURIComponent(dealId)}/artifacts/${encodeURIComponent(artifactId)}?${parameters(options)}`;
+}
+
+export function buildWikiReadPath(slug, options = {}) {
+  if (typeof slug !== "string" || !slug) throw new Error("Usage: llama wiki read <slug>");
+  const params = options.format || options.output || options.attachment ? parameters(options) : new URLSearchParams();
+  params.set("lang", options.lang === "zh" ? "zh" : "en");
+  if (options.attachment !== undefined) {
+    if (typeof options.attachment !== "string" || !options.attachment) throw new Error("--attachment requires a reference ID from the wiki read");
+    params.set("attachment", options.attachment);
+  }
+  if (options.version !== undefined) throw new Error("Wiki reads pin --sha256, not --version");
+  if (!options.format && !options.output && !options.attachment && [options.offset, options.limit, options.sha256].some(x => x !== undefined)) throw new Error("Use --format text with pagination options");
+  return `/api/wiki/${encodeURIComponent(slug)}?${params}`;
+}
+
+export async function saveContentSource(result, output) {
+  if (!output) return result;
+  if (result?.format !== "source" || typeof result.contentBase64 !== "string") throw new Error("Server did not return original file bytes");
+  const bytes = Buffer.from(result.contentBase64, "base64");
+  const sha256 = createHash("sha256").update(bytes).digest("hex");
+  if (sha256 !== result.source?.sha256 || bytes.length !== result.source?.byteSize) throw new Error("Downloaded file hash or size does not match the source");
+  await writeFile(output, bytes, { flag: "wx", mode: 0o600 });
+  return { saved: output, source: result.source, verified: true };
+}

package/lib/deal-actions.mjs

@@ -12,8 +12,9 @@ export const DEAL_WRITE_OPERATIONS = Object.freeze([
 /**
  * A Llama user's own subjective judgment about the team (.people) or the deal
  * (.business). An agent may record it, but the record must name the user and
- * quote them verbatim from their own input, so the type alone stays a reliable
- * filter. Core enforces the same rule; this check only fails faster.
+ * quote them verbatim from their own input, plus the agent's own restatement in
+ * value.summary, so the type alone stays a reliable filter and every record
+ * reads the same way. Core enforces the same rule; this check only fails faster.
  */
 export const HUMAN_SUBJECTIVE_VIEW_TYPES = Object.freeze([
   "human_subjective_view.people",
@@ -72,6 +73,13 @@ export function validateHumanSubjectiveView(information, origin) {
       "human_subjective_view.* value.rawText must appear verbatim inside origin.originalUserUtterance; do not paraphrase",
     );
   }
+  const summary = stringField(information.value, "summary");
+  if (!summary) {
+    throw new Error("human_subjective_view.* requires value.summary: the agent's restatement of the user's words");
+  }
+  if (normalizeWhitespace(summary) === normalizeWhitespace(rawText)) {
+    throw new Error("human_subjective_view.* value.summary must restate value.rawText, not repeat it");
+  }
   return information;
 }
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@llamaventures/cli",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "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/deal-memory-actions-cli.test.mjs scripts/deal-memory-actions.test.mjs scripts/mcp-four-action-surface.test.mjs scripts/page-schema-cli.test.mjs scripts/page-schema.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/content-read.test.mjs 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/page-schema-cli.test.mjs scripts/page-schema.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",