@llamaventures/cli 1.18.1 → 1.20.0

package/bin/llama.mjs

@@ -2,6 +2,7 @@
 
 import { createRequire } from "module";
 import { randomUUID } from "crypto";
+import { readFile } from "fs/promises";
 import readline from "readline";
 import {
   DEFAULT_BASE_URL,
@@ -11,7 +12,6 @@ import {
   TOKEN_FILE,
   getAuthHeaders,
   getBaseUrl,
-  getLastAgentEvent,
   getToken,
   print,
   readBriefing,
@@ -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");
@@ -174,45 +175,6 @@ function slugifyTitle(title) {
   return slug;
 }
 
-function parseExpectedIds(raw) {
-  const text = typeof raw === "string" ? raw : "";
-  const expected = { dealIds: [], wikiSlugs: [], raw: [] };
-  for (const item of text.split(",").map((s) => s.trim()).filter(Boolean)) {
-    const [kind, ...rest] = item.split(":");
-    const value = rest.join(":").trim();
-    if (kind === "deal" && value) expected.dealIds.push(value);
-    else if ((kind === "wiki" || kind === "slug") && value) expected.wikiSlugs.push(value);
-    else expected.raw.push(item);
-  }
-  return expected;
-}
-
-async function submitEvalFeedback(action, flags, queryText = "") {
-  const useLast = flags.last !== false;
-  const last = useLast ? getLastAgentEvent() : null;
-  const eventId =
-    flags.event && flags.event !== true
-      ? Number(flags.event)
-      : last?.lastEventId ?? null;
-  if ((action === "good" || action === "bad") && !eventId && !queryText) {
-    throw new Error(`Usage: llama eval ${action} [--last] [--reason "..."]`);
-  }
-  const body = {
-    action,
-    eventId: Number.isFinite(eventId) ? eventId : undefined,
-    query: queryText || undefined,
-    surface: flags.surface && flags.surface !== true ? String(flags.surface) : last?.lastSurface ?? undefined,
-    expected:
-      flags.expect && flags.expect !== true
-        ? parseExpectedIds(String(flags.expect))
-        : {},
-    reason: flags.reason && flags.reason !== true ? String(flags.reason) : undefined,
-    privacyLevel:
-      flags.privacy && flags.privacy !== true ? String(flags.privacy) : "internal",
-  };
-  return request("POST", "/api/agent/eval-feedback", body);
-}
-
 // Client-side fuzzy match — used as a fallback when the server hasn't yet
 // shipped the search/filter API (Fix B, 2026-04-25). Once the server
 // returns the `{deals,total,limit,offset}` envelope, this path is never
@@ -402,8 +364,8 @@ Agent onboarding (run once on first install):
   llama activity new-deals --since 24h  # recent deal creations for agents
   llama activity updated-deals --since 7d # meaningful deal updates, grouped
   llama explain <url-or-object>         # explain Command URL/object status + lifecycle
-  llama eval good|bad --last            # mark the latest CLI/MCP result for eval
-  llama eval add "<query>" --expect wiki:<slug>|deal:<uuid>
+  llama pref list [--status proposed]   # standing agent preferences (injected every turn)
+  llama pref add reply-style "Lead with the conclusion." [--team]
 
 External pitch — talk to Llama Ventures' intake agent (no token required):
   llama pitch start --name "Jane Doe" --email "jane@acme.ai"
@@ -425,6 +387,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>
@@ -512,7 +475,7 @@ Brief blocks:
 
   Common flags on every add-*:
     --source-section <key>   Target a structured section (team, highlights, recommendation,
-                             <persona>_analysis, ...). Without this, blocks land in "_other"
+                             landscape_map, competitors). Without this, blocks land in "_other"
                              at the bottom of the TOC. AI writers want this.
     --reply-to <blockId>     Make the block a reply to <blockId>. Snapshots parent's heading
                              + 200-char excerpt into meta so the back-link survives parent
@@ -521,10 +484,9 @@ Brief blocks:
                              2026-05-03). Use bottom for batched writes that need to
                              preserve insertion order.
 
-Brief / persona refresh + agent-run revert:
+Brief refresh + agent-run revert:
   llama deal refresh-brief <dealId> [--force]                  # re-eval stale sections
                                                                 # --force = every unlocked watcher-managed section
-  llama deal refresh-persona <dealId> <persona-key>            # server validates persona key
   llama deal revert-run <dealId> <runId> --section <key>       # legacy 4-section model only
                                                                 # section: company|team|highlights|recommendation
 
@@ -534,17 +496,13 @@ Deal soft-delete / restore / trash list:
   llama deal trash                                             # list deleted deals
 
 Deal facts (AI-extracted or human-asserted, with verification):
+  llama deal ingest <dealId> --file <packet.json> [--idempotency-key <key>]  # atomic facts + optional Feed note
+    packet: {"source":{"kind":"meeting_note","title":"Office visit"},"facts":[{"category":"team","claim":"..."}],"note":"..."}
+    categories: company_basics | team | product | market | financials | fundraise | risk | milestone | meta
   llama deal fact list <dealId>
   llama deal fact add <dealId> --category <cat> --claim "<text>" [--source "..."] [--source-url <url>] [--confidence high|medium|low] [--attested]
   llama deal fact verify <dealId> <factId> --status confirmed|disputed [--corrected-value "..."]
 
-Skill corrections (persona-owner pushback — read by persona-watcher):
-  llama skill-correction list <skill-slug> [--include-deleted]
-  llama skill-correction add <skill-slug> "<correction text>" [--deal <uuid>] [--block <blockId>]
-  llama skill-correction delete <id>
-  Server enforces persona owner OR system admin on POST/DELETE; GET is open.
-  External personas (owner_email=null) are admin-only for write.
-
 Mentions / Inbox:
   llama mentions                                       # default: my unresolved cues
   llama mentions list [--everyone] [--all]             # --everyone = team-wide; --all = include resolved
@@ -661,7 +619,6 @@ Common:
   llama agent bootstrap             live Llama OS skill manifest from Command
   llama skills search "<query>"     discover which skill to read
   llama explain <url-or-object>     explain Command URLs, 404s, deleted objects
-  llama eval bad --last              mark latest CLI/MCP result as an eval candidate
 
 Command groups — run \`llama help <group>\` for that group's commands:
   deal        create · show · feed · update · enrich · search · collaborators · links · delete
@@ -670,7 +627,7 @@ Command groups — run \`llama help <group>\` for that group's commands:
   facts       deal facts + skill corrections (the sourced, trust-rated layer)
   timeline    timeline · posts · mentions
   wiki        cross-deal knowledge entries (markdown or HTML)
-  eval        mark real CLI/MCP searches good/bad or add a golden-query candidate
+  pref        standing agent preferences: list · add · retire · approve
   memo        long-form HTML investment memo
   html        deal-specific HTML artifacts (/deals/<id>/browse/<slug>)
   pitch       external founder intake (no token needed)
@@ -689,7 +646,7 @@ the CLI auto-detects it — no token needed (\`llc_\` tokens are a fallback).`;
 const HELP_AREA_MATCH = {
   deal: [/^Deals/, /^Collaborators/, /^Soft-delete/, /^Deal links/, /^Deal soft-delete/],
   activity: [/^Agent activity/],
-  brief: [/^Brief blocks/, /^Brief \/ persona/],
+  brief: [/^Brief blocks/],
   facts: [/^Deal facts/, /^Skill corrections/],
   timeline: [/^Timeline/, /^Mentions/],
   wiki: [/^Wiki/, /^Where does this HTML/],
@@ -1005,6 +962,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.
@@ -1158,6 +1119,49 @@ async function main() {
     throw new Error(`Unknown skills subcommand "${sub}". Use: list / search / show.`);
   }
 
+  // `llama pref ...` — standing agent preferences (learning-domain v1).
+  // Own user scope activates immediately; team scope needs a system admin.
+  if (area === "pref" || area === "prefs" || area === "preferences") {
+    const sub = action;
+    if (!sub || sub === "list") {
+      const { flags } = parseFlags(rest, ["json", "status"]);
+      const params = new URLSearchParams();
+      if (flags.status && flags.status !== true) params.set("status", String(flags.status));
+      const result = await request("GET", `/api/agent/preferences${params.toString() ? `?${params}` : ""}`);
+      print(result);
+      return;
+    }
+    if (sub === "add") {
+      const { flags, positional } = parseFlags(rest, ["team", "evidence", "json"]);
+      const key = positional[0];
+      const content = positional.slice(1).join(" ").trim();
+      if (!key || !content) {
+        throw new Error('Usage: llama pref add <key> "<content, max 280 chars>" [--team] [--evidence "..."]');
+      }
+      const result = await request("POST", "/api/agent/preferences", {
+        scope: flags.team ? "team" : "user",
+        key,
+        content,
+        evidence: flags.evidence && flags.evidence !== true ? String(flags.evidence) : undefined,
+      });
+      print(result);
+      return;
+    }
+    if (sub === "retire" || sub === "approve") {
+      const { positional } = parseFlags(rest, ["json"]);
+      const id = Number(positional[0]);
+      if (!Number.isInteger(id) || id <= 0) {
+        throw new Error(`Usage: llama pref ${sub} <id>`);
+      }
+      const result = await request("PATCH", `/api/agent/preferences/${id}`, {
+        status: sub === "approve" ? "active" : "retired",
+      });
+      print(result);
+      return;
+    }
+    throw new Error(`Unknown pref subcommand "${sub}". Use: list / add / retire / approve.`);
+  }
+
   if (area === "explain" || (area === "agent" && action === "explain")) {
     const args = area === "explain" ? [action, ...rest].filter(Boolean) : rest;
     const { flags, positional } = parseFlags(args, ["json", "type", "id", "lang"]);
@@ -1195,43 +1199,6 @@ async function main() {
     return;
   }
 
-  if (area === "eval") {
-    const sub = action;
-    if (sub === "good" || sub === "bad") {
-      const { flags, positional } = parseFlags(rest, [
-        "last",
-        "event",
-        "reason",
-        "expect",
-        "surface",
-        "privacy",
-      ]);
-      const q = positional.join(" ").trim();
-      print(await submitEvalFeedback(sub, flags, q));
-      return;
-    }
-    if (sub === "add") {
-      const { flags, positional } = parseFlags(rest, [
-        "event",
-        "expect",
-        "reason",
-        "surface",
-        "privacy",
-      ]);
-      const q = positional.join(" ").trim();
-      if (!q && !flags.event) {
-        throw new Error(
-          `Usage: llama eval add "<query>" --surface deal|wiki --expect wiki:<slug>|deal:<uuid>`,
-        );
-      }
-      print(await submitEvalFeedback("add", flags, q));
-      return;
-    }
-    throw new Error(
-      "Usage: llama eval good|bad [--last] [--reason ...] OR llama eval add \"<query>\" --expect wiki:<slug>|deal:<uuid>",
-    );
-  }
-
   // `llama pitch ...` — external founder-pitch family. No Llama token
   // required; bootstraps a session against /api/external/* via PoW + cookie.
   // See lib/external.mjs and AGENT_BRIEFING.md for the full surface.
@@ -1484,6 +1451,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 +1687,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`
@@ -1735,6 +1724,36 @@ async function main() {
     return;
   }
 
+  // ----- Canonical source-packet ingest (atomic facts + optional Feed note) -----
+  if (area === "deal" && action === "ingest") {
+    const dealId = rest[0];
+    const { flags } = parseFlags(rest.slice(1), ["file", "idempotency-key"]);
+    if (!dealId || !flags.file || flags.file === true) {
+      throw new Error(
+        "Usage: llama deal ingest <dealId> --file <packet.json> [--idempotency-key <key>]\n" +
+        'Packet: {"source":{"kind":"meeting_note","title":"Office visit"},' +
+        '"facts":[{"category":"team","claim":"..."}],"note":"..."}'
+      );
+    }
+
+    let packet;
+    try {
+      packet = JSON.parse(await readFile(String(flags.file), "utf8"));
+    } catch (error) {
+      throw new Error(`Cannot read ingest packet ${flags.file}: ${error?.message ?? String(error)}`);
+    }
+    if (!packet || Array.isArray(packet) || typeof packet !== "object") {
+      throw new Error("Ingest packet must be a JSON object");
+    }
+    if (flags["idempotency-key"] !== undefined && flags["idempotency-key"] !== true) {
+      packet.idempotencyKey = String(flags["idempotency-key"]);
+    }
+
+    // @core-api-operation POST /api/deals/{dealId}/ingest
+    print(await request("POST", `/api/deals/${encodeURIComponent(dealId)}/ingest`, packet));
+    return;
+  }
+
   // ----- Deal facts (AI-extracted or human-asserted, with verification) -----
   if (area === "deal" && action === "fact") {
     const sub = rest[0];
@@ -1811,24 +1830,6 @@ async function main() {
     return;
   }
 
-  // ----- Persona refresh: re-run a single persona-watcher -----
-  // Persona keys are validated server-side. Returns runId or null
-  // (debounced / deal inactive). Used by /admin and the per-block
-  // "重新生成" flow.
-  if (area === "deal" && action === "refresh-persona") {
-    const dealId = rest[0];
-    const persona = rest[1];
-    if (!dealId || !persona) {
-      throw new Error(`Usage: llama deal refresh-persona <dealId> <persona-key>`);
-    }
-    print(await request(
-      "POST",
-      `/api/deals/${encodeURIComponent(dealId)}/refresh-persona`,
-      { persona }
-    ));
-    return;
-  }
-
   // ----- Agent-run revert (legacy 4-section brief model) -----
   // Reverts a single section to the `before` value snapshotted by the
   // watcher run. Does NOT re-fire the watcher (intentional: human action).
@@ -1967,6 +1968,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;
   }
@@ -2106,7 +2108,7 @@ Routing — is this the right command?
     const meta = { updated_at: new Date().toISOString(), updated_by: "cli", by_agent: false };
 
     // --source-section <key>: target a structured section (e.g. team /
-    // highlights / <persona>_analysis). Without this, blocks land in the
+    // highlights / competitors). Without this, blocks land in the
     // "_other" group at the bottom of the TOC. AI writers want this
     // virtually always — without it they cannot contribute to existing
     // structured sections.
@@ -2298,6 +2300,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;
   }
@@ -2347,63 +2352,6 @@ Routing — is this the right command?
     throw new Error(`Unknown mentions subcommand "${sub}". Use: list / show / resolve / unread.`);
   }
 
-  // ----- Skill corrections (persona-owner pushback workflow) -----
-  // Persona owners (or system admins) record long-term rules each
-  // persona-DD skill must obey. Read by the persona-watcher and prepended
-  // to the system prompt at run time. Soft-delete is non-cascading —
-  // deleting a row does NOT auto-fire watcher; the next natural run
-  // (manual / stale_re_eval) just stops including the deleted rule.
-  //
-  // Permissions enforced server-side: only the persona owner (per
-  // PERSONA_SKILLS in src/lib/persona-skills.ts) or a system admin can
-  // POST or DELETE. Anyone can GET. External personas (owner_email=null)
-  // are admin-only for write.
-  if (area === "skill-correction") {
-    const sub = action;
-
-    if (sub === "list") {
-      const skillSlug = rest[0];
-      if (!skillSlug) {
-        throw new Error("Usage: llama skill-correction list <skill-slug> [--include-deleted]");
-      }
-      const { flags } = parseFlags(rest.slice(1));
-      const params = new URLSearchParams({ skill: skillSlug });
-      if (flags["include-deleted"]) params.set("include_deleted", "1");
-      print(await request("GET", `/api/skill-corrections?${params.toString()}`));
-      return;
-    }
-
-    if (sub === "add") {
-      const { flags, positional } = parseFlags(rest);
-      const skillSlug = positional[0];
-      const correctionText = positional.slice(1).join(" ").trim();
-      if (!skillSlug || !correctionText) {
-        throw new Error(
-          `Usage: llama skill-correction add <skill-slug> "<correction text>" ` +
-          `[--deal <uuid>] [--block <blockId>]`
-        );
-      }
-      print(await request("POST", "/api/skill-corrections", {
-        skill_slug: skillSlug,
-        correction_text: correctionText,
-        triggered_in_deal_uuid: flags.deal ? String(flags.deal) : null,
-        triggered_in_block_id: flags.block ? String(flags.block) : null,
-      }));
-      return;
-    }
-
-    if (sub === "delete") {
-      const id = rest[0];
-      if (!id) throw new Error("Usage: llama skill-correction delete <id>");
-      print(await request("DELETE", `/api/skill-corrections/${encodeURIComponent(id)}`));
-      return;
-    }
-
-    throw new Error(
-      `Unknown skill-correction subcommand "${sub || ""}". Use: list / add / delete.`
-    );
-  }
-
   // ----- Memo (long-form HTML investment memo) -----
   // The Memo tab in the deal page renders HTML stored in deal_memos.
   // Two sources of memo content:

package/contracts/core-api.json

@@ -0,0 +1,9 @@
+{
+  "format": "llama.core-api-contract.v1",
+  "name": "llama-core-api",
+  "apiVersion": "3.1.0",
+  "openapiVersion": "3.0.3",
+  "sha256": "51b134af7a63534406b3a216aeab190fd595f5270b2a10263730662f1c2f771a",
+  "pathCount": 212,
+  "operationCount": 275
+}