@lumoai/cli 1.32.0 → 1.33.0

package/assets/skill/SKILL.md

@@ -49,7 +49,7 @@ The command catalog below is a **map**: it lists every command grouped by domain
 - `lumo task slack show <id> <contextId>` — full stored Slack thread
 - `lumo task web show <id> <linkId>` — fetched web link body
 - `lumo task figma context <id> <linkId>` — Figma link metadata (v1)
-- `lumo task comments list <id>` — full comment thread (read-only; ≠ `task comment`)
+- `lumo task comments list <id>` — comment thread, capped to the output budget (`--full` prints every comment; read-only; ≠ `task comment`)
 - `lumo task pr show <id> <number>` — synced PR metadata (v1)
 - `lumo task lineage <id>` — show the causal trail: fragments that fed the task + each one's outcome + the run's token/loop cost (read-only audit view); `lumo task lineage <id> --signal` also appends workspace-level usage signal-health (used distribution, per-session variance, used-vs-base merge rate)
 

package/assets/skill/references/docs.md

@@ -139,6 +139,8 @@ lumo doc show cmd_xxx --section "D 状态表" > sec.md  # one section only (revi
 
 Note: the markdown rendered by **default-mode** `doc show` is still best-effort (tables flatten). Round-trip via `doc show > tmp.md && doc update --file tmp.md` is NOT a no-op — use `--raw` as the edit base instead.
 
+Output budget (LUM-428): **default-mode** `doc show` caps the rendered body to the output-token budget (25,000 tokens) and, when truncated, ends in a pointer to `--section "<heading>"` (just-in-time slice) / `--raw` (full source). `--raw` and `--section` are **never** capped — they are byte-faithful edit bases.
+
 **`--section <heading>` (LUM-409)** prints just one heading-addressed section of the markdown source — a byte-faithful slice from the heading line through (not including) the next same-or-higher-level heading, subsections included. No header on stdout (the slice is a legal `doc patch` base); the current revision is printed to **stderr** as `Revision: N`. Mutually exclusive with `--raw`.
 
 - Section addressing: pass the heading text (`--section "D 状态表"`), case-insensitive fallback after an exact pass. Prefix with `#…` to pin the level when the same text exists at several depths (`--section "## Status"`).

package/assets/skill/references/task-context.md

@@ -48,6 +48,12 @@ or the PR detail — run the matching command below. Pass the same identifier
 (`LUM-N`) plus the id the card shows for that source (a Slack `contextId`, a web
 `linkId`, a Figma `linkId`, or a PR `number`).
 
+**Output budget (LUM-428):** the whole `task context` handoff is capped to the
+output-token budget (25,000 tokens). If a memory-rich task with a long thread
+overflows, the output is truncated and ends in a pointer to the precise
+sub-commands (`lumo task status` / `task comments list --full` / `task lineage`
+/ `doc show`) to pull any dropped section just-in-time.
+
 All five are **read-only** (no live Slack/GitHub/Figma calls except the web body
 fetch). Web/Figma/PR are v1 metadata-degraded: they print a `note:` explaining
 that live content needs an external integration.
@@ -83,15 +89,24 @@ server, so the command ends with a `note:` saying so.
 lumo task figma context LUM-42 cfl_abc123
 ```
 
-### `lumo task comments list <identifier>` — full comment thread
+### `lumo task comments list <identifier>` — comment thread
+
+Prints the comment thread: each comment as `author · createdAt` followed by its
+plain-text body (comment bodies are stored as HTML and stripped to text).
+Replies are indented two spaces under their parent. Author falls back to
+`unknown`. No comments prints `(no comments)`.
 
-Prints the **entire** comment thread: each comment as `author · createdAt`
-followed by its plain-text body (comment bodies are stored as HTML and stripped
-to text). Replies are indented two spaces under their parent. Author falls back
-to `unknown`. No comments prints `(no comments)`.
+**Output budget (LUM-428).** By default the thread is capped to the
+output-token budget (25,000 tokens — every line you print spends from your
+context). When it overflows, the output is truncated to the budget and ends in
+a fetch-more pointer (`… +N more comments not shown (output capped at 25,000
+tokens) — read the whole thread with: lumo task comments list <id> --full`).
+Pass **`--full`** to print every comment uncapped — only when you actually need
+the whole thread.
 
 ```bash
-lumo task comments list LUM-42
+lumo task comments list LUM-42          # capped to the output budget
+lumo task comments list LUM-42 --full   # every comment, no cap
 ```
 
 **Plural, and distinct from `task comment`.** `task comments list` _reads_ the

package/dist/cli/src/commands/doc-show.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatShowOutput = formatShowOutput;
+exports.selectDocShowOutput = selectDocShowOutput;
 exports.docShow = docShow;
 const config_1 = require("../lib/config");
 const api_1 = require("../lib/api");
@@ -8,6 +9,7 @@ const markdown_tiptap_1 = require("../lib/markdown-tiptap");
 const markdown_sections_1 = require("../lib/markdown-sections");
 const resolve_doc_id_1 = require("../lib/resolve-doc-id");
 const sanitize_1 = require("../lib/sanitize");
+const output_budget_1 = require("../../../shared/src/output-budget");
 function scopeLabel(s) {
     if (s === 'PRIVATE')
         return 'personal';
@@ -27,43 +29,21 @@ function formatShowOutput(vm) {
         `Mentioned tasks: ${vm.mentionedTasks.length ? vm.mentionedTasks.join(', ') : '-'}`,
     ];
     const header = lines.join('\n');
-    return vm.bodyMarkdown ? `${header}\n\n${(0, sanitize_1.sanitizeField)(vm.bodyMarkdown)}` : header;
+    if (!vm.bodyMarkdown)
+        return header;
+    const full = `${header}\n\n${(0, sanitize_1.sanitizeField)(vm.bodyMarkdown)}`;
+    // The *rendered* view is the only doc-show path with a budget (LUM-428): a
+    // book-length doc would otherwise swallow the agent's context. The pointer
+    // routes to the byte-faithful reads — `--section` for a just-in-time slice,
+    // `--raw` for the whole source — which are NEVER capped (they are edit bases).
+    return (0, output_budget_1.capRenderedOutput)(full, {
+        fetchHint: `read one section with: lumo doc show ${vm.id} --section "<heading>", ` +
+            `or the full markdown source with: lumo doc show ${vm.id} --raw`,
+        unitNoun: 'lines',
+    }).text;
 }
-async function docShow(reference, opts = {}) {
-    if (!reference) {
-        console.error('Error: missing <doc>. Usage: lumo doc show <doc> [--raw | --section <heading>]');
-        return 1;
-    }
-    if (opts.raw && opts.section !== undefined) {
-        console.error('Error: --raw and --section are mutually exclusive (--raw prints the whole source)');
-        return 1;
-    }
-    const creds = (0, config_1.readCredentials)();
-    if (!creds) {
-        console.error('Error: not logged in. Run `lumo auth login` first.');
-        return 1;
-    }
-    const apiUrl = (0, api_1.resolveAuthedApiUrl)(creds.apiUrl);
-    const id = await (0, resolve_doc_id_1.lookupDocId)(apiUrl, creds.token, reference);
-    if (!id) {
-        console.error(`Error: Document not found: ${reference}`);
-        return 1;
-    }
-    const res = await fetch(`${(0, api_1.trimTrailingSlash)(apiUrl)}/api/documents/${id}`, {
-        headers: { Authorization: `Bearer ${creds.token}` },
-    });
-    if (!res.ok) {
-        const text = await res.text();
-        console.error(`Error: ${res.status} ${res.statusText}: ${(0, sanitize_1.sanitizeField)(text)}`);
-        return 1;
-    }
-    // The exact shape of the GET response is not guaranteed; defensively unwrap.
-    const data = (await res.json());
-    const d = data.document;
-    if (!d) {
-        console.error('Error: server returned an empty document response');
-        return 1;
-    }
+function selectDocShowOutput(d, opts) {
+    const revision = typeof d.contentRevision === 'number' ? d.contentRevision : null;
     if (opts.raw) {
         // Byte-identical markdown source of the last markdown upload (LUM-408).
         // Written verbatim (no header, no sanitization, no added newline) so the
@@ -71,30 +51,28 @@ async function docShow(reference, opts = {}) {
         // No silent fallback to the lossy HTML→markdown reverse render — that
         // fallback is exactly what flattened tables in LUM-349.
         if (typeof d.sourceMarkdown !== 'string') {
-            console.error(`Error: ${d.id} has no stored markdown source (last edit was HTML-direct ` +
-                `or predates markdown source storage). --raw refuses to fall back to the ` +
-                `lossy HTML→markdown render. Rebuild a base instead: run \`lumo doc show ${d.id}\`, ` +
-                `reconstruct the markdown faithfully, then \`lumo doc update ${d.id} --file <rebuilt.md>\` ` +
-                `— from then on --raw works.`);
-            return 1;
+            return {
+                kind: 'error',
+                message: `Error: ${d.id} has no stored markdown source (last edit was HTML-direct ` +
+                    `or predates markdown source storage). --raw refuses to fall back to the ` +
+                    `lossy HTML→markdown render. Rebuild a base instead: run \`lumo doc show ${d.id}\`, ` +
+                    `reconstruct the markdown faithfully, then \`lumo doc update ${d.id} --file <rebuilt.md>\` ` +
+                    `— from then on --raw works.`,
+            };
         }
-        process.stdout.write(d.sourceMarkdown);
-        // Revision goes to stderr so stdout stays a byte-pure edit base while
-        // the agent still sees the number to pass back as --if-revision.
-        if (typeof d.contentRevision === 'number') {
-            console.error(`Revision: ${d.contentRevision}`);
-        }
-        return;
+        return { kind: 'bytes', text: d.sourceMarkdown, revision };
     }
     if (opts.section !== undefined) {
         // Section reads slice the stored markdown source — same no-fallback rule
         // as --raw: a rendered-output slice would not be a legal edit base.
         if (typeof d.sourceMarkdown !== 'string') {
-            console.error(`Error: ${d.id} has no stored markdown source (last edit was HTML-direct ` +
-                `or predates markdown source storage), so --section cannot slice it. ` +
-                `Rebuild a base first: run \`lumo doc show ${d.id}\`, reconstruct the markdown ` +
-                `faithfully, then \`lumo doc update ${d.id} --file <rebuilt.md>\`.`);
-            return 1;
+            return {
+                kind: 'error',
+                message: `Error: ${d.id} has no stored markdown source (last edit was HTML-direct ` +
+                    `or predates markdown source storage), so --section cannot slice it. ` +
+                    `Rebuild a base first: run \`lumo doc show ${d.id}\`, reconstruct the markdown ` +
+                    `faithfully, then \`lumo doc update ${d.id} --file <rebuilt.md>\`.`,
+            };
         }
         const match = (0, markdown_sections_1.findSection)(d.sourceMarkdown, opts.section);
         if (match.kind === 'not-found') {
@@ -102,24 +80,27 @@ async function docShow(reference, opts = {}) {
                 .slice(0, 30)
                 .map(s => `  ${'#'.repeat(s.depth)} ${(0, sanitize_1.sanitizeField)(s.heading)}`)
                 .join('\n');
-            console.error(`Error: section not found: "${opts.section}". Available headings:\n${list || '  (none)'}`);
-            return 1;
+            return {
+                kind: 'error',
+                message: `Error: section not found: "${opts.section}". Available headings:\n${list || '  (none)'}`,
+            };
         }
         if (match.kind === 'ambiguous') {
             const list = match.candidates
                 .map(s => `  ${'#'.repeat(s.depth)} ${(0, sanitize_1.sanitizeField)(s.heading)} (line ${s.line + 1})`)
                 .join('\n');
-            console.error(`Error: section "${opts.section}" is ambiguous — ${match.candidates.length} headings match:\n${list}\n` +
-                `Disambiguate by depth, e.g. --section "${'#'.repeat(match.candidates[0].depth)} ${match.candidates[0].heading}"`);
-            return 1;
-        }
-        // Byte-faithful slice, verbatim on stdout (legal patch base); revision on
-        // stderr for the follow-up `doc patch --if-revision`.
-        process.stdout.write((0, markdown_sections_1.extractSection)(d.sourceMarkdown, match.section));
-        if (typeof d.contentRevision === 'number') {
-            console.error(`Revision: ${d.contentRevision}`);
+            return {
+                kind: 'error',
+                message: `Error: section "${opts.section}" is ambiguous — ${match.candidates.length} headings match:\n${list}\n` +
+                    `Disambiguate by depth, e.g. --section "${'#'.repeat(match.candidates[0].depth)} ${match.candidates[0].heading}"`,
+            };
         }
-        return;
+        // Byte-faithful slice, verbatim (legal patch base).
+        return {
+            kind: 'bytes',
+            text: (0, markdown_sections_1.extractSection)(d.sourceMarkdown, match.section),
+            revision,
+        };
     }
     // Server returns `contentMarkdown` derived from the HTML body (LUM-83+).
     // Fall back to parsing the raw content as legacy Tiptap JSON for docs
@@ -149,15 +130,71 @@ async function docShow(reference, opts = {}) {
         return null;
     })
         .filter((x) => x !== null);
-    console.log(formatShowOutput({
-        id: d.id,
-        title: d.title,
-        scope: d.visibility ?? 'PRIVATE',
-        projectName: d.project?.name ?? null,
-        createdAt: d.createdAt ?? '',
-        updatedAt: d.updatedAt ?? '',
-        revision: typeof d.contentRevision === 'number' ? d.contentRevision : null,
-        mentionedTasks,
-        bodyMarkdown: body,
-    }));
+    return {
+        kind: 'rendered',
+        text: formatShowOutput({
+            id: d.id,
+            title: d.title,
+            scope: d.visibility ?? 'PRIVATE',
+            projectName: d.project?.name ?? null,
+            createdAt: d.createdAt ?? '',
+            updatedAt: d.updatedAt ?? '',
+            revision,
+            mentionedTasks,
+            bodyMarkdown: body,
+        }),
+    };
+}
+async function docShow(reference, opts = {}) {
+    if (!reference) {
+        console.error('Error: missing <doc>. Usage: lumo doc show <doc> [--raw | --section <heading>]');
+        return 1;
+    }
+    if (opts.raw && opts.section !== undefined) {
+        console.error('Error: --raw and --section are mutually exclusive (--raw prints the whole source)');
+        return 1;
+    }
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        console.error('Error: not logged in. Run `lumo auth login` first.');
+        return 1;
+    }
+    const apiUrl = (0, api_1.resolveAuthedApiUrl)(creds.apiUrl);
+    const id = await (0, resolve_doc_id_1.lookupDocId)(apiUrl, creds.token, reference);
+    if (!id) {
+        console.error(`Error: Document not found: ${reference}`);
+        return 1;
+    }
+    const res = await fetch(`${(0, api_1.trimTrailingSlash)(apiUrl)}/api/documents/${id}`, {
+        headers: { Authorization: `Bearer ${creds.token}` },
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        console.error(`Error: ${res.status} ${res.statusText}: ${(0, sanitize_1.sanitizeField)(text)}`);
+        return 1;
+    }
+    // The exact shape of the GET response is not guaranteed; defensively unwrap.
+    const data = (await res.json());
+    const d = data.document;
+    if (!d) {
+        console.error('Error: server returned an empty document response');
+        return 1;
+    }
+    const sel = selectDocShowOutput(d, opts);
+    if (sel.kind === 'error') {
+        console.error(sel.message);
+        return 1;
+    }
+    if (sel.kind === 'bytes') {
+        // Byte-faithful read (--raw / --section): written verbatim, NEVER routed
+        // through the output cap — it is a legal edit base for `doc patch`
+        // (LUM-408/409/428). Revision goes to stderr so stdout stays byte-pure
+        // while the agent still sees the number to pass back as --if-revision.
+        process.stdout.write(sel.text);
+        if (sel.revision !== null) {
+            console.error(`Revision: ${sel.revision}`);
+        }
+        return;
+    }
+    console.log(sel.text);
 }

package/dist/cli/src/commands/task-comment-list.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatCommentThread = formatCommentThread;
 exports.taskCommentList = taskCommentList;
 const config_1 = require("../lib/config");
 const api_1 = require("../lib/api");
 const sanitize_1 = require("../lib/sanitize");
+const output_budget_1 = require("../../../shared/src/output-budget");
 /**
  * Strip TipTap/HTML markup to readable plain text. Comment bodies are stored as
  * HTML; the CLI only needs the visible text. We collapse block tags to newlines
@@ -23,17 +25,42 @@ function htmlToPlainText(html) {
         .replace(/\n{3,}/g, '\n\n')
         .trim();
 }
-function printComment(c, indent) {
+/** Render one comment (and its nested replies) as an indented text block. */
+function renderCommentBlock(c, indent) {
+    const lines = [];
     const author = (0, sanitize_1.sanitizeField)(c.authorActorId ?? 'unknown');
-    console.log(`${indent}${author} · ${c.createdAt}`);
+    lines.push(`${indent}${author} · ${c.createdAt}`);
     const text = (0, sanitize_1.sanitizeField)(htmlToPlainText(c.body));
     for (const line of (text || '(empty)').split('\n')) {
-        console.log(`${indent}${line}`);
+        lines.push(`${indent}${line}`);
     }
-    console.log('');
     for (const reply of c.replies ?? []) {
-        printComment(reply, indent + '  ');
+        lines.push('');
+        lines.push(renderCommentBlock(reply, indent + '  '));
     }
+    return lines.join('\n');
+}
+/**
+ * Render the full comment thread as agent-facing text. One block per top-level
+ * comment (replies indented underneath). Capped to the output-token budget by
+ * default (LUM-428) — a long-running task's thread is one of the easiest ways
+ * to blow the agent's context — with a fetch-more pointer to `--full`. Pass
+ * `{ full: true }` to print everything.
+ */
+function formatCommentThread(comments, opts = {}) {
+    if (comments.length === 0)
+        return '(no comments)';
+    const blocks = comments.map(c => renderCommentBlock(c, ''));
+    if (opts.full)
+        return blocks.join('\n\n');
+    const id = opts.identifier ?? '<LUM-N>';
+    return (0, output_budget_1.truncateUnitsToBudget)({
+        units: blocks,
+        maxTokens: opts.maxTokens,
+        unitNoun: 'comments',
+        fetchHint: `read the whole thread with: lumo task comments list ${id} --full`,
+        separator: '\n\n',
+    }).text;
 }
 /**
  * `lumo task comments list <LUM-N>`
@@ -43,7 +70,7 @@ function printComment(c, indent) {
  * thread from `/api/tasks/:id/comments` and prints each top-level comment
  * (replies indented) as `author · time` followed by the plain-text body.
  */
-async function taskCommentList(identifier) {
+async function taskCommentList(identifier, opts = {}) {
     if (!identifier) {
         console.error('Error: usage: lumo task comments list <LUM-42>');
         return 1;
@@ -105,7 +132,8 @@ async function taskCommentList(identifier) {
         console.log('(no comments)');
         return;
     }
-    for (const c of comments) {
-        printComment(c, '');
-    }
+    console.log(formatCommentThread(comments, {
+        full: opts.full,
+        identifier: resolved.identifier,
+    }));
 }

package/dist/cli/src/commands/task-context.js

@@ -6,6 +6,7 @@ const config_1 = require("../lib/config");
 const api_1 = require("../lib/api");
 const sanitize_1 = require("../lib/sanitize");
 const format_1 = require("../lib/format");
+const output_budget_1 = require("../../../shared/src/output-budget");
 async function taskContext(identifier) {
     if (!identifier) {
         console.error('Error: missing <identifier>. Usage: lumo task context <LUM-42>');
@@ -144,5 +145,15 @@ function formatTaskContextMarkdown(data, now) {
         lines.push((0, sanitize_1.sanitizeField)(data.lineageSection.trimEnd()));
         lines.push('');
     }
-    return lines.join('\n');
+    // A memory-rich task with a long comment thread and many sessions is the
+    // single most context-hungry agent-facing command (LUM-428). Cap the
+    // assembled handoff to the output budget; the pointer routes the agent to the
+    // precise sub-commands to pull any dropped section just-in-time.
+    const id = data.task.identifier;
+    return (0, output_budget_1.capRenderedOutput)(lines.join('\n'), {
+        fetchHint: `pull the dropped sections individually: lumo task status ${id} · ` +
+            `lumo task comments list ${id} --full · lumo task lineage ${id} · ` +
+            `lumo doc show <doc>`,
+        unitNoun: 'lines',
+    }).text;
 }

package/dist/cli/src/index.js

@@ -344,8 +344,9 @@ const taskComments = task
     .description('Inspect the full task comment thread');
 taskComments
     .command('list <identifier>')
-    .description('List the full task comment thread')
-    .action(wrap(id => (0, task_comment_list_1.taskCommentList)(id)));
+    .description('List the task comment thread (capped to the output budget; --full prints every comment)')
+    .option('--full', 'Print every comment, bypassing the output-token cap')
+    .action(wrap((id, opts) => (0, task_comment_list_1.taskCommentList)(id, opts)));
 const taskDeps = task
     .command('deps')
     .description('Task dependency edges — detected candidates + confirmed blockers');

package/dist/shared/src/index.js

@@ -1,7 +1,7 @@
 "use strict";
 // ── Agent Error types ────────────────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildCmdEvidencePointer = exports.isValidEvidencePointer = exports.EVIDENCE_POINTER_MAX = exports.EVIDENCE_POINTER_FORMAT_HINT = exports.EVIDENCE_POINTER_PATTERNS = exports.sanitizeField = exports.parseStreamJsonUsage = exports.tiptapToMarkdown = exports.markdownToTiptap = exports.AgentError = void 0;
+exports.capRenderedOutput = exports.truncateUnitsToBudget = exports.OUTPUT_TOKEN_BUDGET = exports.estimateTokens = exports.buildCmdEvidencePointer = exports.isValidEvidencePointer = exports.EVIDENCE_POINTER_MAX = exports.EVIDENCE_POINTER_FORMAT_HINT = exports.EVIDENCE_POINTER_PATTERNS = exports.sanitizeField = exports.parseStreamJsonUsage = exports.tiptapToMarkdown = exports.markdownToTiptap = exports.AgentError = void 0;
 exports.userFriendlyError = userFriendlyError;
 class AgentError extends Error {
     code;
@@ -46,3 +46,9 @@ Object.defineProperty(exports, "EVIDENCE_POINTER_FORMAT_HINT", { enumerable: tru
 Object.defineProperty(exports, "EVIDENCE_POINTER_MAX", { enumerable: true, get: function () { return acceptance_evidence_1.EVIDENCE_POINTER_MAX; } });
 Object.defineProperty(exports, "isValidEvidencePointer", { enumerable: true, get: function () { return acceptance_evidence_1.isValidEvidencePointer; } });
 Object.defineProperty(exports, "buildCmdEvidencePointer", { enumerable: true, get: function () { return acceptance_evidence_1.buildCmdEvidencePointer; } });
+// ── Agent-facing CLI output-token budget (LUM-428) ───────────────────────────
+var output_budget_1 = require("./output-budget");
+Object.defineProperty(exports, "estimateTokens", { enumerable: true, get: function () { return output_budget_1.estimateTokens; } });
+Object.defineProperty(exports, "OUTPUT_TOKEN_BUDGET", { enumerable: true, get: function () { return output_budget_1.OUTPUT_TOKEN_BUDGET; } });
+Object.defineProperty(exports, "truncateUnitsToBudget", { enumerable: true, get: function () { return output_budget_1.truncateUnitsToBudget; } });
+Object.defineProperty(exports, "capRenderedOutput", { enumerable: true, get: function () { return output_budget_1.capRenderedOutput; } });

package/dist/shared/src/output-budget.js

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * LUM-428 — output-token budget for agent-facing CLI stdout.
+ *
+ * Anthropic's "Writing effective tools for AI agents" + "Effective context
+ * engineering": a tool's response is a contract that spends from the agent's
+ * context budget, and Claude Code defaults to truncating a tool result to
+ * 25,000 tokens. Lumo's agent-facing commands (`task comments list`,
+ * `task context`, `doc show`, …) print straight into that budget, so a single
+ * fat comment thread / huge doc must not be allowed to blow it.
+ *
+ * This module is the CLI-side primitive: a token estimate, the budget anchor,
+ * and two cappers that truncate to the budget and append a *lightweight
+ * fetch-more pointer* — a just-in-time identifier telling the agent how to pull
+ * the rest on demand instead of receiving it all up front.
+ *
+ * It lives in `shared/` (not the app's `lib/context/budget.ts`) because the CLI
+ * imports `shared/` and never the app `lib/`. It is deliberately decoupled from
+ * the LUM-402 *injection-side* budget (session-start additionalContext): that
+ * one allocates the context window; this one caps command stdout.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OUTPUT_TOKEN_BUDGET = void 0;
+exports.estimateTokens = estimateTokens;
+exports.truncateUnitsToBudget = truncateUnitsToBudget;
+exports.capRenderedOutput = capRenderedOutput;
+/**
+ * Rough token estimate: char-count / 4, rounded up. Stable proxy that avoids a
+ * tokenizer dependency — the same heuristic the canonical injection-side budget
+ * (`lib/context/budget.ts`) uses, duplicated here only because `shared/` must
+ * stay free of any app-`lib/` import.
+ */
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Default per-command output ceiling for agent-facing CLI stdout, in tokens.
+ * Anchored to Anthropic's published Claude Code default (tool results truncated
+ * to 25,000 tokens). Generous on purpose: normal outputs sit far below it, so
+ * the cap only ever engages on a pathological input (a thousand-comment thread,
+ * a book-length doc) — exactly the case that would otherwise silently swallow
+ * the agent's whole budget.
+ */
+exports.OUTPUT_TOKEN_BUDGET = 25_000;
+/**
+ * Chars reserved for the appended pointer line so the final string (body +
+ * pointer) still fits the budget. Comfortably larger than any pointer this
+ * module builds.
+ */
+const POINTER_RESERVE_CHARS = 320;
+function buildPointer(omitted, unitNoun, maxTokens, fetchHint) {
+    return (`… +${omitted.toLocaleString('en-US')} more ${unitNoun} not shown ` +
+        `(output capped at ${maxTokens.toLocaleString('en-US')} tokens) — ${fetchHint}`);
+}
+/**
+ * Truncate an explicit list of repeatable units (e.g. one comment each) to the
+ * budget, appending the fetch-more pointer when anything is dropped. Always
+ * keeps at least one unit so the output is never just a pointer. The returned
+ * `text` is guaranteed to estimate at or under `maxTokens`.
+ */
+function truncateUnitsToBudget(params) {
+    const maxTokens = params.maxTokens ?? exports.OUTPUT_TOKEN_BUDGET;
+    const separator = params.separator ?? '\n\n';
+    const { units, unitNoun, fetchHint } = params;
+    const full = units.join(separator);
+    if (units.length === 0 || estimateTokens(full) <= maxTokens) {
+        return {
+            text: full,
+            truncated: false,
+            shownUnits: units.length,
+            omittedUnits: 0,
+        };
+    }
+    const charBudget = Math.max(0, maxTokens * 4 - POINTER_RESERVE_CHARS);
+    const kept = [];
+    let used = 0;
+    for (const unit of units) {
+        const add = (kept.length === 0 ? 0 : separator.length) + unit.length;
+        if (kept.length > 0 && used + add > charBudget)
+            break;
+        kept.push(unit);
+        used += add;
+        if (used >= charBudget)
+            break;
+    }
+    let body = kept.join(separator);
+    // A single oversized leading unit can still bust the budget — hard-slice it.
+    if (body.length > charBudget)
+        body = body.slice(0, charBudget);
+    const omitted = units.length - kept.length;
+    const pointer = buildPointer(omitted, unitNoun, maxTokens, fetchHint);
+    return {
+        text: `${body}${separator}${pointer}`,
+        truncated: true,
+        shownUnits: kept.length,
+        omittedUnits: omitted,
+    };
+}
+/**
+ * Cap an already-rendered multi-line string to the budget at a line boundary,
+ * appending the fetch-more pointer when truncated. For commands that assemble a
+ * single body (a doc render, the task-context handoff) rather than an explicit
+ * unit list. The returned `text` estimates at or under `maxTokens`.
+ */
+function capRenderedOutput(text, opts) {
+    const maxTokens = opts.maxTokens ?? exports.OUTPUT_TOKEN_BUDGET;
+    const unitNoun = opts.unitNoun ?? 'lines';
+    if (estimateTokens(text) <= maxTokens) {
+        return { text, truncated: false, shownUnits: 0, omittedUnits: 0 };
+    }
+    const charBudget = Math.max(0, maxTokens * 4 - POINTER_RESERVE_CHARS);
+    // Fill the budget with a hard char-slice (so a single very long line is
+    // sliced, not dropped wholesale), then back up to a line boundary when one
+    // sits in the kept tail — keeps the output from ending mid-line.
+    let body = text.slice(0, charBudget);
+    const lastNewline = body.lastIndexOf('\n');
+    if (lastNewline > charBudget / 2)
+        body = body.slice(0, lastNewline);
+    const totalLines = text.split('\n').length;
+    const keptLines = body.length === 0 ? 0 : body.split('\n').length;
+    const omitted = Math.max(0, totalLines - keptLines);
+    const pointer = buildPointer(omitted, unitNoun, maxTokens, opts.fetchHint);
+    return {
+        text: `${body}\n\n${pointer}`,
+        truncated: true,
+        shownUnits: keptLines,
+        omittedUnits: omitted,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumoai/cli",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "description": "Lumo CLI — manage tasks and sessions from the terminal",
   "license": "MIT",
   "author": "cli@uselumo.ai",