@llamaventures/cli 2.7.1 → 2.9.0

package/CHANGELOG.md

@@ -6,6 +6,42 @@ this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+## [2.9.0] - 2026-11-13
+
+### Changed
+
+- `llama auth login` no longer has to be running at the moment you approve in
+  the browser. The loopback listener is now a detached helper that stays open
+  for 15 minutes, finishes the sign-in when you approve, and stores the
+  credentials. If the command stops first (closed terminal, slow approval, an
+  agent tool that kills long commands), run `llama auth login` again: it picks
+  up the sign-in that is still waiting, or the approval you already gave,
+  instead of leaving the browser on a dead `127.0.0.1` page.
+- `llama auth status` reports a sign-in that is waiting for approval.
+
+### Added
+
+- `LLAMA_NO_BROWSER=1` makes `llama auth login` print the sign-in link instead
+  of opening a browser.
+
+## [2.8.0] - 2026-11-12
+
+### Added
+
+- Export the API-backed MCP tool catalog from `lib/mcp-api-tools.mjs`.
+  `registerApiTools(server, { request, formatError, version, only })` registers
+  the Deal, Deal Memory, bootstrap, Page schema, skills, preference and Wiki
+  tools against an injected request function, so a remote MCP host can serve
+  the same catalog as the stdio server. The module also exports
+  `writeDealCommandSchema`. Tools that need local credentials or files stay in
+  `llama-mcp`. No tool name, schema or behavior changed for stdio users.
+
+### Changed
+
+- `write_deal` and `wiki_save` descriptions each name the other as the
+  alternative destination: a file or HTML about one company is a Deal
+  Artifact; knowledge not tied to one company belongs in the Wiki.
+
 ## [2.7.1] - 2026-11-10
 
 ### Added

package/README.md

@@ -13,6 +13,11 @@ sign-in. Logout, administrator revocation, or account deactivation can end acces
 sooner. On systems without a credential store, credentials are stored in a local
 file readable only by your user.
 
+The sign-in stays open for 15 minutes even if the command stops (a closed
+terminal, or an agent tool that times out): run `llama auth login` again and it
+picks up the same sign-in, or the approval you already gave. Set
+`LLAMA_NO_BROWSER=1` to print the link instead of opening a browser.
+
 ## Install or upgrade
 
 ```bash

package/bin/llama-mcp.mjs

@@ -1,17 +1,16 @@
 #!/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";
 import { z } from "zod";
+import { registerApiTools, structuredBootstrapManifest, textResult } from "../lib/mcp-api-tools.mjs";
 import {
   formatErrorForDisplay,
   getAuthHeaders,
   readBriefing,
   request,
   setClientRuntime,
-  structuredBootstrapManifest,
 } from "../lib/client.mjs";
 import {
   clearExternalSession,
@@ -20,18 +19,7 @@ import {
   startExternalSession,
   uploadExternalFile,
 } from "../lib/external.mjs";
-import {
-  buildDealReadPath,
-  buildDealSearchPath,
-  verifyDealSearchResult,
-  informationReadFilter,
-  verifyInformationReadResult,
-  compactDealWriteResult,
-  prepareDealCommand,
-} from "../lib/deal-actions.mjs";
 import { submitFeedback, readFeedback, resolveFeedback } from "../lib/feedback.mjs";
-import { buildDealMemoryPath } from "../lib/deal-memory-actions.mjs";
-import { buildPageSchemaPath, MAX_PAGE_SCHEMA_FIELDS } from "../lib/page-schema.mjs";
 
 const requireFromHere = createRequire(import.meta.url);
 const { version: PKG_VERSION } = requireFromHere("../package.json");
@@ -39,13 +27,6 @@ setClientRuntime({ client: "mcp" });
 
 const server = new McpServer({ name: "llama-mcp", version: PKG_VERSION });
 
-function textResult(text, isError = false) {
-  return {
-    content: [{ type: "text", text }],
-    ...(isError ? { isError: true } : {}),
-  };
-}
-
 async function callApi(method, path, body, transform = (value) => value) {
   try {
     const result = transform(await request(method, path, body));
@@ -86,175 +67,9 @@ server.registerTool("feedback_resolve", {
   catch (error) { return textResult(formatErrorForDisplay(error), true); }
 });
 
-const originSchema = z.object({
-  kind: z.enum(["user", "agent", "system"]),
-  originalUserUtterance: z.string().min(1).optional(),
-  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().describe("Reuse the existing ID to append a complete file version, including on rename. Omit for a new document without a title collision, or explicitly use a fresh UUID for a distinct same-name source."),
-    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(
-  "search_deals",
-  {
-    description: "Search current Deal metadata by company name/key, description, sector/subsector or founder name in either stored language. Use short keywords; matching is a case-insensitive literal substring, not semantic search. Combine q with sector/status/state/limit, or use sector alone for category discovery. status filters by exact pipeline status (e.g. [\"Invested\"]); to list every invested Deal use status [\"Invested\"] with limit 200 and order by investmentDate/markedInvestedAt, instead of guessing from names. Sector filters before limit and requires a supporting Core server. Exact names rank first. Inspect searchMatch fields and search.has_more; truncated results are not exhaustive. On zero matches, try broader or alternative wording before concluding no Deal exists. Read candidates to verify specific categories and claims. Always search before creating a company.",
-    inputSchema: {
-      q: z.string().optional(),
-      sector: z.string().trim().min(1).max(200).optional(),
-      status: z.array(z.string().min(1).max(60)).min(1).max(10).optional(),
-      state: z.enum(["active", "archived", "trashed"]).optional(),
-      limit: z.number().int().min(1).max(2000).optional(),
-    },
-  },
-  // @core-api-operation GET /api/occam/deals
-  async ({ q, sector, status, state, limit } = {}) => callApi(
-    "GET", buildDealSearchPath(q, { sector, status, state, limit }), undefined,
-    (result) => verifyDealSearchResult(result, { sector, status }),
-  ),
-);
-
-server.registerTool(
-  "read_deal",
-  {
-    description: "Read one Deal. Live Page is current human-visible state; Information is memory and never updates Page automatically. Read Information selectively with informationIds (full values, up to 50), informationTypes, and/or informationQuery (literal text; returns match.snippets, and values over 8,000 characters as { omitted, chars }: then read that id). Prefer these over detail=memory, which returns up to ~2 MB. 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(),
-      informationIds: z.array(z.string().uuid()).min(1).max(50).optional(),
-      informationTypes: z.array(z.string().min(1).max(120)).min(1).max(20).optional(),
-      informationQuery: z.string().min(2).max(200).optional(),
-    },
-  },
-  async ({ dealId, detail, artifactId, informationIds, informationTypes, informationQuery, ...options }) => {
-    const filter = informationReadFilter({ ids: informationIds, types: informationTypes, q: informationQuery });
-    if (artifactId) {
-      if (detail) throw new Error("Use artifactId or detail, not both");
-      if (filter) throw new Error("Use artifactId or information filters, 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", filter), undefined,
-      (result) => verifyInformationReadResult(result, filter));
-  },
-);
-
-server.registerTool(
-  "create_deal",
-  {
-    description: "Create one Deal intent. Core owns Drive, initial resources, idempotency, and Events.",
-    inputSchema: {
-      companyName: z.string().min(1).max(240),
-      companyKey: z.string().min(1).max(240).optional(),
-      page: z.record(z.string(), z.any()).optional(),
-      information: z.array(z.record(z.string(), z.any())).optional(),
-      origin: originSchema,
-      idempotencyKey: z.string().min(1).max(240).optional(),
-    },
-  },
-  async (input) => callApi("POST", "/api/occam/deals/commands", prepareDealCommand("create", input)),
-);
-
-server.registerTool(
-  "write_deal",
-  {
-    description: "The only Deal mutation tool. Pass one command: input.submit, information.put, page.patch, or artifact.put. Before artifact.put, read Deal files: reuse artifactId for a revision; a same-kind/title collision without an ID returns OCCAM_CONFLICT. Titles are candidates, not identity. Select the intended existing ID from the request/content, or explicitly generate a fresh UUID for a distinct same-name source. Send complete revised bytes, preserve applicable metadata, and verify the ID/version. Core hosts text/html in Command; do not mirror HTML to Drive or require a Drive link. Non-HTML source files, including original transcripts and recordings, go to Drive through artifact.put. Keep source-file bodies out of Input, Information, Page and metadata; save extracted facts and summaries with source references and preserve the user request. page.patch does not edit file bytes. 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.
-    inputSchema: { command: writeDealCommandSchema },
-  },
-  async ({ command }) => callApi(
-    "POST",
-    "/api/occam/deals/commands",
-    prepareDealCommand("write", command),
-    (result) => compactDealWriteResult(command, result),
-  ),
-);
-
-// 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. A returned placeholder is an existing Story whose version is required for a write; only 404 means no Story exists.",
-    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: "Replace the complete Markdown Deal Story with one coherent current understanding; never append an update log, restate Live Deal Page/Deal Information fields, or write when understanding would not materially improve. Frontmatter must contain matching deal_id plus stable uuid and created timestamps; updated must strictly advance. Pass the version from get_deal_memory for every returned Story, including a placeholder; only 404 permits creation without expected_version.",
-    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 } : {}) },
-  ),
-);
+// Deal, Deal Memory, bootstrap, Page schema, skills, preferences and Wiki tools
+// are shared with remote MCP hosts; see lib/mcp-api-tools.mjs.
+registerApiTools(server, { request, formatError: formatErrorForDisplay, version: PKG_VERSION });
 
 server.registerTool(
   "auth_status",
@@ -274,185 +89,6 @@ server.registerTool(
   },
 );
 
-server.registerTool(
-  "agent_bootstrap",
-  {
-    description: "Mandatory before Llama work: fetch the authenticated two-part private Brain (Investment Framework V3 + Llama Command operating skill), a compact Live Deal Page schema index, runtime contract including Wiki publishing guidance, and visible Llama OS skills. Read exact Page fields separately with get_live_deal_page_schema.",
-    inputSchema: { limit: z.number().int().min(1).max(100).optional() },
-  },
-  async ({ limit } = {}) => {
-    const params = new URLSearchParams({ clientVersion: PKG_VERSION });
-    params.set("page_schema", "progressive");
-    if (limit) params.set("limit", String(limit));
-    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);
-    }
-  },
-);
-
-server.registerTool(
-  "get_live_deal_page_schema",
-  {
-    description: "Read the Live Deal Page schema progressively. Call with no selector for the compact index; before page.patch, request only exact fields or one section. This is read-only context, not a fifth Deal action.",
-    inputSchema: {
-      fields: z.array(z.string().min(1)).min(1).max(MAX_PAGE_SCHEMA_FIELDS).optional(),
-      section: z.string().min(1).optional(),
-    },
-  },
-  async ({ fields, section } = {}) => {
-    try {
-      // @core-api-operation GET /api/agent/page-schema
-      return await callApi("GET", buildPageSchemaPath({ fields, section }));
-    } catch (error) {
-      return textResult(formatErrorForDisplay(error), true);
-    }
-  },
-);
-
-server.registerTool(
-  "skills_search",
-  {
-    description: "Search authenticated runtime skills; read only the relevant result.",
-    inputSchema: { q: z.string().min(1), limit: z.number().int().min(1).max(100).optional() },
-  },
-  async ({ q, limit }) => {
-    const params = new URLSearchParams({ q });
-    if (limit) params.set("limit", String(limit));
-    return callApi("GET", `/api/agent/skills?${params}`);
-  },
-);
-
-server.registerTool(
-  "skills_read",
-  {
-    description: "Read one authenticated runtime skill by slug.",
-    inputSchema: { slug: z.string().min(1) },
-  },
-  async ({ slug }) => callApi("GET", `/api/agent/skills/${encodeURIComponent(slug)}`),
-);
-
-server.registerTool(
-  "pref_list",
-  {
-    description: "List standing agent preferences.",
-    inputSchema: { status: z.enum(["active", "proposed", "retired", "all"]).optional() },
-  },
-  async ({ status } = {}) => {
-    const params = new URLSearchParams();
-    if (status) params.set("status", status);
-    return callApi("GET", `/api/agent/preferences${params.size ? `?${params}` : ""}`);
-  },
-);
-
-server.registerTool(
-  "pref_add",
-  {
-    description: "Save a durable user or team preference; procedures belong in skills.",
-    inputSchema: {
-      key: z.string().min(1),
-      content: z.string().min(1).max(280),
-      scope: z.enum(["user", "team"]).optional(),
-      evidence: z.string().optional(),
-    },
-  },
-  async ({ key, content, scope, evidence }) =>
-    callApi("POST", "/api/agent/preferences", { key, content, scope, evidence }),
-);
-
-server.registerTool(
-  "pref_set_status",
-  {
-    description: "Activate or retire a standing preference.",
-    inputSchema: { id: z.number().int().positive(), status: z.enum(["active", "retired"]) },
-  },
-  async ({ id, status }) => callApi("PATCH", `/api/agent/preferences/${id}`, { status }),
-);
-
-server.registerTool(
-  "object_inspect",
-  {
-    description: "Explain a Command URL or object before guessing that it is broken.",
-    inputSchema: {
-      q: z.string().optional(),
-      type: z.string().optional(),
-      id: z.string().optional(),
-      lang: z.enum(["en", "zh"]).optional(),
-    },
-  },
-  async ({ q, type, id, lang } = {}) => {
-    const params = new URLSearchParams();
-    if (q) params.set("q", q);
-    if (type) params.set("type", type);
-    if (id) params.set("id", id);
-    if (lang) params.set("lang", lang);
-    return callApi("GET", `/api/agent/explain?${params}`);
-  },
-);
-
-server.registerTool(
-  "wiki_search",
-  {
-    description: "Search institutional knowledge in the internal Wiki.",
-    inputSchema: { q: z.string().min(1) },
-  },
-  async ({ q }) => callApi("GET", `/api/wiki/search?q=${encodeURIComponent(q)}`),
-);
-
-server.registerTool(
-  "wiki_read",
-  {
-    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(),
-    },
-  },
-  // @core-api-operation GET /api/wiki/{slug}
-  async ({ slug, ...options }) => callApi("GET", buildWikiReadPath(slug, options)),
-);
-
-server.registerTool(
-  "wiki_save",
-  {
-    description: "Publish institutional knowledge when authorized. Follow agent_bootstrap contract.wiki_publishing. New pages default to complete self-contained HTML with embedded rendering assets and full report content/interactions; set content_type=html. Honor explicit Markdown requests. Read the same slug/lang before edits and preserve its format unless conversion is authorized. Verify the receipt, canonical page and interactions before reporting completion.",
-    inputSchema: {
-      slug: z.string().min(1),
-      title: z.string().min(1),
-      content: z.string().describe("Complete page source. For HTML, include the full document and embedded rendering dependencies."),
-      sources: z.array(z.string()).min(1),
-      content_type: z.enum(["markdown", "html"]).optional().describe("Set html for HTML publications. Use markdown for an explicit Markdown request or an existing Markdown article."),
-      lang: z.enum(["en", "zh"]).optional().describe("Article language; Core defaults to en when omitted."),
-    },
-  },
-  async ({ slug, title, content, sources, content_type, lang }) =>
-    callApi("POST", "/api/wiki/save", { slug, title, content, sources, content_type, lang }),
-);
-
-server.registerTool(
-  "wiki_delete",
-  {
-    description: "Soft-delete a Wiki article.",
-    inputSchema: { slug: z.string().min(1), lang: z.enum(["en", "zh"]).optional() },
-  },
-  async ({ slug, lang }) =>
-    callApi("DELETE", `/api/wiki/${encodeURIComponent(slug)}?lang=${lang === "zh" ? "zh" : "en"}`),
-);
-
-server.registerTool(
-  "wiki_restore",
-  {
-    description: "Restore a soft-deleted Wiki article.",
-    inputSchema: { slug: z.string().min(1), lang: z.enum(["en", "zh"]).optional() },
-  },
-  async ({ slug, lang }) =>
-    callApi("POST", `/api/wiki/${encodeURIComponent(slug)}/restore?lang=${lang === "zh" ? "zh" : "en"}`),
-);
-
 server.registerTool(
   "pitch_start",
   {

package/bin/llama.mjs

@@ -28,8 +28,10 @@ import {
   startExternalSession,
   uploadExternalFile,
 } from "../lib/external.mjs";
-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 { fileURLToPath } from "node:url";
+import { LLAMA_CLI_CLIENT_ID, revokeToken as revokeOAuthToken } from "../lib/oauth-flow.mjs";
+import { liveLogin, readPending, runLoginListener, startOrResumeLogin } from "../lib/oauth-background.mjs";
+import { deleteBundle, detectBackend, readBundle } from "../lib/oauth-storage.mjs";
 import { getBuildInfo } from "../lib/build-info.mjs";
 import { getUpdateNudge, maybeNudgeUpdate } from "../lib/version-check.mjs";
 import {
@@ -516,6 +518,7 @@ async function handleAuth(area, action, rest) {
       }
     }
     const oauthBackend = oauth ? await detectBackend() : null;
+    const pendingLogin = readPending();
     print({
       baseUrl: getBaseUrl(),
       activeMethod: oauth?.access_token ? "oauth" : bearer ? "gcloud-bearer" : token ? "llama-token" : "none",
@@ -524,6 +527,9 @@ async function handleAuth(area, action, rest) {
       llamaToken: token ? `${token.slice(0, 8)}...${token.slice(-4)}` : "absent",
       llamaTokenSource: process.env.LLAMA_TOKEN ? "$LLAMA_TOKEN" : readCanonicalToken() ? "~/.llama/token" : null,
       serverCheck,
+      ...(liveLogin(pendingLogin, getBaseUrl())
+        ? { pendingLogin: { waitingForApproval: true, url: pendingLogin.url, expiresAt: new Date(pendingLogin.expires_at).toISOString() } }
+        : {}),
     });
     return true;
   }
@@ -531,18 +537,16 @@ async function handleAuth(area, action, rest) {
     const { flags } = parseFlags(rest, ["scope"]);
     const scope = typeof flags.scope === "string" ? flags.scope : "read write";
     const baseUrl = getBaseUrl();
-    const bundle = await pkceLoopbackFlow({ baseUrl, scope, resource: baseUrl });
-    const stored = await writeBundle({
-      access_token: bundle.access_token,
-      refresh_token: bundle.refresh_token,
-      expires_at: Date.now() + (bundle.expires_in ?? 3600) * 1000,
-      scope: bundle.scope,
-      client_id: bundle.client_id,
-      issuer: bundle.issuer,
-      resource: bundle.resource,
-      created_at: Date.now(),
-    });
-    print({ ok: true, client_id: LLAMA_CLI_CLIENT_ID, storage: stored.backend, scope: bundle.scope });
+    // The listener is a detached helper, so this login survives this command
+    // being closed or killed; see lib/oauth-background.mjs.
+    const result = await startOrResumeLogin({ baseUrl, scope, cliEntry: fileURLToPath(import.meta.url) });
+    print({ ok: true, client_id: LLAMA_CLI_CLIENT_ID, storage: result.storage, scope: result.scope, ...(result.resumed ? { resumed: true } : {}) });
+    return true;
+  }
+  if (area === "auth" && action === "login-listener") {
+    // Internal: the detached helper started by `llama auth login`.
+    const { flags } = parseFlags(rest, ["scope"]);
+    await runLoginListener({ baseUrl: getBaseUrl(), scope: typeof flags.scope === "string" ? flags.scope : "read write" });
     return true;
   }
   if (area === "auth" && action === "logout") {

package/lib/build-manifest.json

@@ -1,8 +1,8 @@
 {
   "format": "llama.cli-build.v1",
   "packageName": "@llamaventures/cli",
-  "packageVersion": "2.7.1",
-  "sourceSha": "18bbea099ee97465f3c0ba4cbc01ff7c0c8a12bf",
+  "packageVersion": "2.9.0",
+  "sourceSha": "55e2fd7670bb5667cf2c419e884620faa403d5c3",
   "sourceKind": "github",
   "sourceDirty": false,
   "coreApiContract": {

package/lib/client.mjs

@@ -594,13 +594,7 @@ export function formatErrorForDisplay(error) {
   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;
-}
+export { structuredBootstrapManifest } from "./mcp-api-tools.mjs";
 
 async function requestWithRetry(method, endpoint, body, opts, allowRetry) {
   const authHeaders = await getAuthHeaders();

package/lib/mcp-api-tools.mjs

@@ -0,0 +1,414 @@
+// The API-backed Llama tool catalog, independent of transport and of how the
+// caller authenticates. The stdio server (bin/llama-mcp.mjs) passes the local
+// HTTP client; a remote MCP endpoint hosted by Llama Command passes its own
+// in-process request function. Nothing here may touch local credentials,
+// local files, or process state: tools that need those stay in bin/.
+
+import { z } from "zod";
+import { buildArtifactReadPath, buildWikiReadPath } from "./content-read.mjs";
+import {
+  buildDealReadPath,
+  buildDealSearchPath,
+  verifyDealSearchResult,
+  informationReadFilter,
+  verifyInformationReadResult,
+  compactDealWriteResult,
+  prepareDealCommand,
+} from "./deal-actions.mjs";
+import { buildDealMemoryPath } from "./deal-memory-actions.mjs";
+import { buildPageSchemaPath, MAX_PAGE_SCHEMA_FIELDS } from "./page-schema.mjs";
+
+export function textResult(text, isError = false) {
+  return {
+    content: [{ type: "text", text }],
+    ...(isError ? { isError: true } : {}),
+  };
+}
+
+/** The manifest also carries a rendered duplicate of itself; tools return the structured half. */
+export function structuredBootstrapManifest(manifest) {
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+    return manifest;
+  }
+  const { briefing: _renderedDuplicate, ...structured } = manifest;
+  return structured;
+}
+
+export const originSchema = z.object({
+  kind: z.enum(["user", "agent", "system"]),
+  originalUserUtterance: z.string().min(1).optional(),
+  originatingChatRecordId: z.string().uuid().optional(),
+});
+
+export 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().describe("Reuse the existing ID to append a complete file version, including on rename. Omit for a new document without a title collision, or explicitly use a fresh UUID for a distinct same-name source."),
+    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(),
+]);
+
+/**
+ * Register the API-backed tools on an MCP server.
+ *
+ * @param server   an McpServer
+ * @param deps.request      async (method, path, body) => parsed JSON; throws on failure
+ * @param deps.formatError  (error) => string shown to the agent
+ * @param deps.version      client version reported to bootstrap
+ * @param deps.only         optional list of tool names; others are not registered
+ */
+export function registerApiTools(server, { request, formatError, version, only } = {}) {
+  if (typeof request !== "function") throw new Error("registerApiTools requires a request function");
+  const describeError = formatError ?? ((error) => `Error: ${error?.message ?? String(error)}`);
+  const formatErrorForDisplay = describeError;
+  const allowed = only ? new Set(only) : null;
+  const registerTool = (name, ...rest) => {
+    if (allowed && !allowed.has(name)) return;
+    server.registerTool(name, ...rest);
+  };
+
+  async function callApi(method, path, body, transform = (value) => value) {
+    try {
+      const result = transform(await request(method, path, body));
+      return textResult(typeof result === "string" ? result : JSON.stringify(result, null, 2));
+    } catch (error) {
+      return textResult(describeError(error), true);
+    }
+  }
+
+
+  // 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.
+  registerTool(
+    "search_deals",
+    {
+      description: "Search current Deal metadata by company name/key, description, sector/subsector or founder name in either stored language. Use short keywords; matching is a case-insensitive literal substring, not semantic search. Combine q with sector/status/state/limit, or use sector alone for category discovery. status filters by exact pipeline status (e.g. [\"Invested\"]); to list every invested Deal use status [\"Invested\"] with limit 200 and order by investmentDate/markedInvestedAt, instead of guessing from names. Sector filters before limit and requires a supporting Core server. Exact names rank first. Inspect searchMatch fields and search.has_more; truncated results are not exhaustive. On zero matches, try broader or alternative wording before concluding no Deal exists. Read candidates to verify specific categories and claims. Always search before creating a company.",
+      inputSchema: {
+        q: z.string().optional(),
+        sector: z.string().trim().min(1).max(200).optional(),
+        status: z.array(z.string().min(1).max(60)).min(1).max(10).optional(),
+        state: z.enum(["active", "archived", "trashed"]).optional(),
+        limit: z.number().int().min(1).max(2000).optional(),
+      },
+    },
+    // @core-api-operation GET /api/occam/deals
+    async ({ q, sector, status, state, limit } = {}) => callApi(
+      "GET", buildDealSearchPath(q, { sector, status, state, limit }), undefined,
+      (result) => verifyDealSearchResult(result, { sector, status }),
+    ),
+  );
+
+  registerTool(
+    "read_deal",
+    {
+      description: "Read one Deal. Live Page is current human-visible state; Information is memory and never updates Page automatically. Read Information selectively with informationIds (full values, up to 50), informationTypes, and/or informationQuery (literal text; returns match.snippets, and values over 8,000 characters as { omitted, chars }: then read that id). Prefer these over detail=memory, which returns up to ~2 MB. 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(),
+        informationIds: z.array(z.string().uuid()).min(1).max(50).optional(),
+        informationTypes: z.array(z.string().min(1).max(120)).min(1).max(20).optional(),
+        informationQuery: z.string().min(2).max(200).optional(),
+      },
+    },
+    async ({ dealId, detail, artifactId, informationIds, informationTypes, informationQuery, ...options }) => {
+      const filter = informationReadFilter({ ids: informationIds, types: informationTypes, q: informationQuery });
+      if (artifactId) {
+        if (detail) throw new Error("Use artifactId or detail, not both");
+        if (filter) throw new Error("Use artifactId or information filters, 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", filter), undefined,
+        (result) => verifyInformationReadResult(result, filter));
+    },
+  );
+
+  registerTool(
+    "create_deal",
+    {
+      description: "Create one Deal intent. Core owns Drive, initial resources, idempotency, and Events.",
+      inputSchema: {
+        companyName: z.string().min(1).max(240),
+        companyKey: z.string().min(1).max(240).optional(),
+        page: z.record(z.string(), z.any()).optional(),
+        information: z.array(z.record(z.string(), z.any())).optional(),
+        origin: originSchema,
+        idempotencyKey: z.string().min(1).max(240).optional(),
+      },
+    },
+    async (input) => callApi("POST", "/api/occam/deals/commands", prepareDealCommand("create", input)),
+  );
+
+  registerTool(
+    "write_deal",
+    {
+      description: "The only Deal mutation tool. Pass one command: input.submit, information.put, page.patch, or artifact.put. A file or HTML about one company belongs here as artifact.put; standalone knowledge not tied to one company belongs in wiki_save. Before artifact.put, read Deal files: reuse artifactId for a revision; a same-kind/title collision without an ID returns OCCAM_CONFLICT. Titles are candidates, not identity. Select the intended existing ID from the request/content, or explicitly generate a fresh UUID for a distinct same-name source. Send complete revised bytes, preserve applicable metadata, and verify the ID/version. Core hosts text/html in Command; do not mirror HTML to Drive or require a Drive link. Non-HTML source files, including original transcripts and recordings, go to Drive through artifact.put. Keep source-file bodies out of Input, Information, Page and metadata; save extracted facts and summaries with source references and preserve the user request. page.patch does not edit file bytes. 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.
+      inputSchema: { command: writeDealCommandSchema },
+    },
+    async ({ command }) => callApi(
+      "POST",
+      "/api/occam/deals/commands",
+      prepareDealCommand("write", command),
+      (result) => compactDealWriteResult(command, result),
+    ),
+  );
+
+  // 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.
+  registerTool(
+    "get_deal_memory",
+    {
+      description: "Read the complete canonical Markdown Deal Story and its opaque concurrency version. A returned placeholder is an existing Story whose version is required for a write; only 404 means no Story exists.",
+      inputSchema: { dealId: z.string().uuid() },
+    },
+    // @core-api-operation GET /api/deal-memory/{dealId}/story
+    async ({ dealId }) => callApi("GET", buildDealMemoryPath(dealId)),
+  );
+
+  registerTool(
+    "update_deal_memory",
+    {
+      description: "Replace the complete Markdown Deal Story with one coherent current understanding; never append an update log, restate Live Deal Page/Deal Information fields, or write when understanding would not materially improve. Frontmatter must contain matching deal_id plus stable uuid and created timestamps; updated must strictly advance. Pass the version from get_deal_memory for every returned Story, including a placeholder; only 404 permits creation without expected_version.",
+      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 } : {}) },
+    ),
+  );
+
+  registerTool(
+    "agent_bootstrap",
+    {
+      description: "Mandatory before Llama work: fetch the authenticated two-part private Brain (Investment Framework V3 + Llama Command operating skill), a compact Live Deal Page schema index, runtime contract including Wiki publishing guidance, and visible Llama OS skills. Read exact Page fields separately with get_live_deal_page_schema.",
+      inputSchema: { limit: z.number().int().min(1).max(100).optional() },
+    },
+    async ({ limit } = {}) => {
+      const params = new URLSearchParams({ clientVersion: version });
+      params.set("page_schema", "progressive");
+      if (limit) params.set("limit", String(limit));
+      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);
+      }
+    },
+  );
+
+  registerTool(
+    "get_live_deal_page_schema",
+    {
+      description: "Read the Live Deal Page schema progressively. Call with no selector for the compact index; before page.patch, request only exact fields or one section. This is read-only context, not a fifth Deal action.",
+      inputSchema: {
+        fields: z.array(z.string().min(1)).min(1).max(MAX_PAGE_SCHEMA_FIELDS).optional(),
+        section: z.string().min(1).optional(),
+      },
+    },
+    async ({ fields, section } = {}) => {
+      try {
+        // @core-api-operation GET /api/agent/page-schema
+        return await callApi("GET", buildPageSchemaPath({ fields, section }));
+      } catch (error) {
+        return textResult(formatErrorForDisplay(error), true);
+      }
+    },
+  );
+
+  registerTool(
+    "skills_search",
+    {
+      description: "Search authenticated runtime skills; read only the relevant result.",
+      inputSchema: { q: z.string().min(1), limit: z.number().int().min(1).max(100).optional() },
+    },
+    async ({ q, limit }) => {
+      const params = new URLSearchParams({ q });
+      if (limit) params.set("limit", String(limit));
+      return callApi("GET", `/api/agent/skills?${params}`);
+    },
+  );
+
+  registerTool(
+    "skills_read",
+    {
+      description: "Read one authenticated runtime skill by slug.",
+      inputSchema: { slug: z.string().min(1) },
+    },
+    async ({ slug }) => callApi("GET", `/api/agent/skills/${encodeURIComponent(slug)}`),
+  );
+
+  registerTool(
+    "pref_list",
+    {
+      description: "List standing agent preferences.",
+      inputSchema: { status: z.enum(["active", "proposed", "retired", "all"]).optional() },
+    },
+    async ({ status } = {}) => {
+      const params = new URLSearchParams();
+      if (status) params.set("status", status);
+      return callApi("GET", `/api/agent/preferences${params.size ? `?${params}` : ""}`);
+    },
+  );
+
+  registerTool(
+    "pref_add",
+    {
+      description: "Save a durable user or team preference; procedures belong in skills.",
+      inputSchema: {
+        key: z.string().min(1),
+        content: z.string().min(1).max(280),
+        scope: z.enum(["user", "team"]).optional(),
+        evidence: z.string().optional(),
+      },
+    },
+    async ({ key, content, scope, evidence }) =>
+      callApi("POST", "/api/agent/preferences", { key, content, scope, evidence }),
+  );
+
+  registerTool(
+    "pref_set_status",
+    {
+      description: "Activate or retire a standing preference.",
+      inputSchema: { id: z.number().int().positive(), status: z.enum(["active", "retired"]) },
+    },
+    async ({ id, status }) => callApi("PATCH", `/api/agent/preferences/${id}`, { status }),
+  );
+
+  registerTool(
+    "object_inspect",
+    {
+      description: "Explain a Command URL or object before guessing that it is broken.",
+      inputSchema: {
+        q: z.string().optional(),
+        type: z.string().optional(),
+        id: z.string().optional(),
+        lang: z.enum(["en", "zh"]).optional(),
+      },
+    },
+    async ({ q, type, id, lang } = {}) => {
+      const params = new URLSearchParams();
+      if (q) params.set("q", q);
+      if (type) params.set("type", type);
+      if (id) params.set("id", id);
+      if (lang) params.set("lang", lang);
+      return callApi("GET", `/api/agent/explain?${params}`);
+    },
+  );
+
+  registerTool(
+    "wiki_search",
+    {
+      description: "Search institutional knowledge in the internal Wiki.",
+      inputSchema: { q: z.string().min(1) },
+    },
+    async ({ q }) => callApi("GET", `/api/wiki/search?q=${encodeURIComponent(q)}`),
+  );
+
+  registerTool(
+    "wiki_read",
+    {
+      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(),
+      },
+    },
+    // @core-api-operation GET /api/wiki/{slug}
+    async ({ slug, ...options }) => callApi("GET", buildWikiReadPath(slug, options)),
+  );
+
+  registerTool(
+    "wiki_save",
+    {
+      description: "Publish institutional knowledge when authorized. For knowledge not tied to one company; a file or HTML about one company is a Deal Artifact (write_deal artifact.put), unless the user names the Wiki. Follow agent_bootstrap contract.wiki_publishing. New pages default to complete self-contained HTML with embedded rendering assets and full report content/interactions; set content_type=html. Honor explicit Markdown requests. Read the same slug/lang before edits and preserve its format unless conversion is authorized. Verify the receipt, canonical page and interactions before reporting completion.",
+      inputSchema: {
+        slug: z.string().min(1),
+        title: z.string().min(1),
+        content: z.string().describe("Complete page source. For HTML, include the full document and embedded rendering dependencies."),
+        sources: z.array(z.string()).min(1),
+        content_type: z.enum(["markdown", "html"]).optional().describe("Set html for HTML publications. Use markdown for an explicit Markdown request or an existing Markdown article."),
+        lang: z.enum(["en", "zh"]).optional().describe("Article language; Core defaults to en when omitted."),
+      },
+    },
+    async ({ slug, title, content, sources, content_type, lang }) =>
+      callApi("POST", "/api/wiki/save", { slug, title, content, sources, content_type, lang }),
+  );
+
+  registerTool(
+    "wiki_delete",
+    {
+      description: "Soft-delete a Wiki article.",
+      inputSchema: { slug: z.string().min(1), lang: z.enum(["en", "zh"]).optional() },
+    },
+    async ({ slug, lang }) =>
+      callApi("DELETE", `/api/wiki/${encodeURIComponent(slug)}?lang=${lang === "zh" ? "zh" : "en"}`),
+  );
+
+  registerTool(
+    "wiki_restore",
+    {
+      description: "Restore a soft-deleted Wiki article.",
+      inputSchema: { slug: z.string().min(1), lang: z.enum(["en", "zh"]).optional() },
+    },
+    async ({ slug, lang }) =>
+      callApi("POST", `/api/wiki/${encodeURIComponent(slug)}/restore?lang=${lang === "zh" ? "zh" : "en"}`),
+  );
+}

package/lib/oauth-background.mjs

@@ -0,0 +1,175 @@
+// Browser login that survives the command that started it.
+//
+// The loopback flow needs something listening on 127.0.0.1 at the moment the
+// person clicks Approve. When `llama auth login` itself was that listener, a
+// closed terminal, a slow approval, or an agent tool that kills commands after
+// a couple of minutes left the browser pointing at a dead port.
+//
+// So the listener is a small detached helper process. `llama auth login`
+// starts it, shows the link, and waits; if the command is killed the helper
+// keeps listening, finishes the login when the person approves, and stores
+// the credentials. Running `llama auth login` again picks the same login up
+// instead of starting a second one.
+//
+// The helper's state lives in ~/.llama/oauth-pending.json (0600). It holds the
+// sign-in link and a status, never a token or the PKCE verifier.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { openBrowser, pkceLoopbackFlow } from "./oauth-flow.mjs";
+import { writeBundle } from "./oauth-storage.mjs";
+
+export const LOGIN_WINDOW_MS = 15 * 60 * 1000;
+/** How long a finished result stays claimable by the next `llama auth login`. */
+const RESULT_TTL_MS = 10 * 60 * 1000;
+const POLL_MS = 400;
+
+export function defaultPendingPath() {
+  return path.join(os.homedir(), ".llama", "oauth-pending.json");
+}
+
+export function readPending(pendingPath = defaultPendingPath()) {
+  try {
+    return JSON.parse(fs.readFileSync(pendingPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writePending(pendingPath, state) {
+  fs.mkdirSync(path.dirname(pendingPath), { recursive: true, mode: 0o700 });
+  const tmp = `${pendingPath}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(state)}\n`, { mode: 0o600 });
+  fs.renameSync(tmp, pendingPath);
+}
+
+export function clearPending(pendingPath = defaultPendingPath()) {
+  try { fs.unlinkSync(pendingPath); } catch { /* not present */ }
+}
+
+function processAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+/** A login someone can still approve: same server, helper alive, inside its window. */
+export function liveLogin(pending, baseUrl, now = Date.now()) {
+  return Boolean(
+    pending && pending.status === "waiting" && pending.base_url === baseUrl &&
+    now < pending.expires_at && processAlive(pending.pid),
+  );
+}
+
+/**
+ * The helper process body: listen, finish the login, store credentials.
+ * Everything it learns is written to the pending file for whoever asks next.
+ */
+export async function runLoginListener({
+  baseUrl, scope, pendingPath = defaultPendingPath(), storeBundle = writeBundle, windowMs = LOGIN_WINDOW_MS, flow = pkceLoopbackFlow,
+}) {
+  const started = Date.now();
+  const base = { pid: process.pid, base_url: baseUrl, scope, started_at: started, expires_at: started + windowMs };
+  try {
+    const bundle = await flow({
+      baseUrl, scope, resource: baseUrl, timeoutMs: windowMs, quiet: true,
+      launchBrowser: (url) => writePending(pendingPath, { ...base, status: "waiting", url }),
+    });
+    const stored = await storeBundle({
+      access_token: bundle.access_token,
+      refresh_token: bundle.refresh_token,
+      expires_at: Date.now() + (bundle.expires_in ?? 3600) * 1000,
+      scope: bundle.scope,
+      client_id: bundle.client_id,
+      issuer: bundle.issuer,
+      resource: bundle.resource,
+      created_at: Date.now(),
+    });
+    writePending(pendingPath, { ...base, status: "done", finished_at: Date.now(), storage: stored.backend, scope: bundle.scope, client_id: bundle.client_id });
+  } catch (error) {
+    writePending(pendingPath, { ...base, status: "error", finished_at: Date.now(), error: String(error?.message ?? error) });
+  }
+}
+
+function spawnDetachedListener({ cliEntry, scope }) {
+  const child = spawn(process.execPath, [cliEntry, "auth", "login-listener", "--scope", scope], {
+    detached: true, stdio: "ignore", windowsHide: true, env: process.env,
+  });
+  child.on("error", () => {});
+  child.unref();
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Start a browser login, or pick up the one already in progress, and wait.
+ *
+ * Returns { ok, storage, scope, client_id, resumed } on success. Throws the
+ * login's own error (denied, timed out) when it failed. If the caller is
+ * killed while waiting, nothing is lost: run it again.
+ */
+export async function startOrResumeLogin({
+  baseUrl, scope, cliEntry, pendingPath = defaultPendingPath(), waitMs = LOGIN_WINDOW_MS,
+  spawnListener = spawnDetachedListener, launchBrowser = openBrowser, log = (line) => console.error(line), now = () => Date.now(),
+}) {
+  let pending = readPending(pendingPath);
+
+  // A login that finished after the previous command stopped waiting.
+  if (pending?.base_url === baseUrl && pending.status === "done" && now() - pending.finished_at < RESULT_TTL_MS) {
+    clearPending(pendingPath);
+    return { ok: true, storage: pending.storage, scope: pending.scope, client_id: pending.client_id, resumed: true };
+  }
+
+  const resumed = liveLogin(pending, baseUrl, now());
+  if (resumed) {
+    const minutes = Math.max(1, Math.round((pending.expires_at - now()) / 60000));
+    log(`A sign-in is already waiting for approval (about ${minutes} min left). Approve it in the browser:`);
+    log(`  ${pending.url}`);
+    log("If you already clicked Approve and saw an error page, reload that tab.");
+  } else {
+    clearPending(pendingPath);
+    spawnListener({ cliEntry, scope, baseUrl, pendingPath });
+    const deadline = now() + 15_000;
+    while (now() < deadline) {
+      pending = readPending(pendingPath);
+      if (pending && pending.base_url === baseUrl && pending.status !== undefined) break;
+      await sleep(100);
+    }
+    if (!pending || pending.status === undefined) {
+      throw new Error("Error[OAUTH_LISTENER_FAILED]: could not start the sign-in listener. Re-run `llama auth login`.");
+    }
+    if (pending.status === "waiting") {
+      // LLAMA_NO_BROWSER=1: print the link only (SSH, agents, a browser on another machine's profile).
+      const openIt = !process.env.LLAMA_NO_BROWSER;
+      log(openIt ? `Opening browser to ${baseUrl} for sign-in...` : `Open this link to sign in to ${baseUrl}:`);
+      log(openIt ? `(If the browser does not open, visit this URL manually:\n  ${pending.url}\n)` : `  ${pending.url}`);
+      log("This sign-in stays open for 15 minutes even if this command stops; run `llama auth login` again to pick it up.");
+      if (openIt) launchBrowser(pending.url);
+    }
+  }
+
+  const waitUntil = now() + waitMs;
+  while (now() < waitUntil) {
+    pending = readPending(pendingPath);
+    if (pending?.status === "done") {
+      clearPending(pendingPath);
+      return { ok: true, storage: pending.storage, scope: pending.scope, client_id: pending.client_id, resumed };
+    }
+    if (pending?.status === "error") {
+      clearPending(pendingPath);
+      throw new Error(pending.error);
+    }
+    if (!pending || (pending.status === "waiting" && !liveLogin(pending, baseUrl, now()))) {
+      clearPending(pendingPath);
+      throw new Error("Error[OAUTH_TIMEOUT]: the sign-in was not approved in time. Re-run `llama auth login`.");
+    }
+    await sleep(POLL_MS);
+  }
+  throw new Error("Error[OAUTH_STILL_WAITING]: still waiting for approval in the browser. Run `llama auth login` again to keep waiting.");
+}

package/lib/oauth-flow.mjs

@@ -48,7 +48,7 @@ export function challengeFor(verifier) {
 // Browser launcher
 // ============================================================
 
-function openBrowser(url) {
+export function openBrowser(url) {
   // Platform-native open. We never block on it (the user closes the
   // browser when they're done; the loopback server is what we wait for).
   let cmd, args;
@@ -112,7 +112,7 @@ function respondHtml(res, ok, message) {
  * @param {string} opts.resource  RFC 8707 audience the access token will bind to
  * @returns {Promise<Object>}     {access_token, refresh_token, expires_in, scope, token_type, redirect_uri}
  */
-export async function pkceLoopbackFlow({ baseUrl, scope, resource, launchBrowser = openBrowser }) {
+export async function pkceLoopbackFlow({ baseUrl, scope, resource, launchBrowser = openBrowser, timeoutMs = FLOW_TIMEOUT_MS, quiet = false }) {
   const verifier = generateVerifier();
   const challenge = challengeFor(verifier);
   const state = base64url(randomBytes(16));
@@ -132,9 +132,9 @@ export async function pkceLoopbackFlow({ baseUrl, scope, resource, launchBrowser
       try { server.close(); } catch { /* */ }
       reject(new Error(
         "Error[OAUTH_TIMEOUT]: Browser flow did not complete within " +
-        Math.round(FLOW_TIMEOUT_MS / 1000) + "s. Re-run `llama auth login`."
+        Math.round(timeoutMs / 1000) + "s. Re-run `llama auth login`."
       ));
-    }, FLOW_TIMEOUT_MS);
+    }, timeoutMs);
 
     server.on("request", (req, res) => {
       const url = new URL(req.url, "http://127.0.0.1");
@@ -189,8 +189,10 @@ export async function pkceLoopbackFlow({ baseUrl, scope, resource, launchBrowser
   authorizeUrl.searchParams.set("code_challenge_method", "S256");
   authorizeUrl.searchParams.set("resource", resource);
 
-  console.error(`Opening browser to ${baseUrl} for sign-in...`);
-  console.error(`(If the browser does not open, visit this URL manually:\n  ${authorizeUrl.toString()}\n)`);
+  if (!quiet) {
+    console.error(`Opening browser to ${baseUrl} for sign-in...`);
+    console.error(`(If the browser does not open, visit this URL manually:\n  ${authorizeUrl.toString()}\n)`);
+  }
   launchBrowser(authorizeUrl.toString());
 
   const code = await codePromise;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llamaventures/cli",
-  "version": "2.7.1",
+  "version": "2.9.0",
   "description": "CLI + MCP server for the Llama Ventures investment workbench (command.llamaventures.vc).",
   "type": "module",
   "scripts": {
@@ -11,7 +11,7 @@
     "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",
-    "test:auth": "node --test scripts/oauth-refresh.test.mjs scripts/oauth-flow.test.mjs"
+    "test:auth": "node --test scripts/oauth-refresh.test.mjs scripts/oauth-flow.test.mjs scripts/oauth-background.test.mjs"
   },
   "bin": {
     "llama": "bin/llama.mjs",