lark-remote 0.1.6 → 0.1.8

package/dist/card/run-state.js

@@ -1,3 +1,4 @@
+import { keepTail } from '../common/truncate.js';
 const MAX_REASONING_CHARS = 4_000;
 const MAX_TEXT_CHARS = 12_000;
 const MAX_TOOL_DETAIL_CHARS = 3_000;
@@ -64,6 +65,7 @@ export function reduceRunState(state, event) {
     if (event.type === 'approval_expired') {
         return {
             ...state,
+            approvalExpired: true,
             approvals: (state.approvals ?? []).map((a) => a.view.requestId === event.requestId ? { ...a, expired: true } : a),
         };
     }
@@ -100,14 +102,14 @@ function reduceTurnDiffEvent(state, event) {
             blocks: keepLatestBlocks(upsertSnapshotBlock(blocks, (b) => b.kind === 'text' && b.itemId === event.itemId, () => ({
                 kind: 'text',
                 itemId: event.itemId,
-                content: keepLatest(event.text, MAX_TEXT_CHARS),
+                content: keepTail(event.text, MAX_TEXT_CHARS),
                 timestamp: ts,
                 ...(complete ? { completedAt: ts } : {}),
             }), (existing) => {
                 const textBlock = existing;
                 return {
                     ...textBlock,
-                    content: keepLatest(event.text, MAX_TEXT_CHARS),
+                    content: keepTail(event.text, MAX_TEXT_CHARS),
                     ...(complete ? { completedAt: ts } : {}),
                 };
             }, !complete)),
@@ -120,7 +122,7 @@ function reduceTurnDiffEvent(state, event) {
             blocks: keepLatestBlocks(upsertSnapshotBlock(next.blocks, (b) => b.kind === 'thinking' && b.itemId === event.itemId, () => ({
                 kind: 'thinking',
                 itemId: event.itemId,
-                content: keepLatest(event.reasoning, MAX_REASONING_CHARS),
+                content: keepTail(event.reasoning, MAX_REASONING_CHARS),
                 active: !complete,
                 timestamp: ts,
                 ...(complete ? { completedAt: ts } : {}),
@@ -128,7 +130,7 @@ function reduceTurnDiffEvent(state, event) {
                 const thinkingBlock = existing;
                 return {
                     ...thinkingBlock,
-                    content: keepLatest(event.reasoning, MAX_REASONING_CHARS),
+                    content: keepTail(event.reasoning, MAX_REASONING_CHARS),
                     active: !complete,
                     ...(complete ? { completedAt: ts } : {}),
                 };
@@ -145,7 +147,7 @@ function reduceTurnDiffEvent(state, event) {
                     id: event.itemId,
                     name: 'command',
                     input: '',
-                    output: keepLatest(event.toolOutput, MAX_TOOL_DETAIL_CHARS),
+                    output: keepTail(event.toolOutput, MAX_TOOL_DETAIL_CHARS),
                     status: complete ? (event.toolStatus ?? 'ok') : 'running',
                     startedAt: ts,
                     ...(complete ? { completedAt: ts } : {}),
@@ -154,7 +156,7 @@ function reduceTurnDiffEvent(state, event) {
                 kind: 'tool',
                 tool: {
                     ...existing.tool,
-                    output: keepLatest(event.toolOutput, MAX_TOOL_DETAIL_CHARS),
+                    output: keepTail(event.toolOutput, MAX_TOOL_DETAIL_CHARS),
                     status: complete
                         ? (event.toolStatus ?? 'ok')
                         : existing.tool.status,
@@ -165,7 +167,7 @@ function reduceTurnDiffEvent(state, event) {
         };
     }
     if (event.plan !== undefined) {
-        const newPlan = keepLatest(event.plan, MAX_REASONING_CHARS * 2);
+        const newPlan = keepTail(event.plan, MAX_REASONING_CHARS * 2);
         next = {
             ...next,
             plan: newPlan,
@@ -298,7 +300,7 @@ function reduceAssistantEvent(state, event) {
                     ...next.blocks.slice(0, -1),
                     {
                         kind: 'thinking',
-                        content: keepLatest(last.content + '\n' + content.thinking, MAX_REASONING_CHARS),
+                        content: keepTail(last.content + '\n' + content.thinking, MAX_REASONING_CHARS),
                         active: true,
                         timestamp: last.timestamp ?? event.timestamp,
                     },
@@ -307,7 +309,7 @@ function reduceAssistantEvent(state, event) {
                     ...next.blocks,
                     {
                         kind: 'thinking',
-                        content: keepLatest(content.thinking, MAX_REASONING_CHARS),
+                        content: keepTail(content.thinking, MAX_REASONING_CHARS),
                         active: true,
                         timestamp: event.timestamp,
                     },
@@ -326,7 +328,7 @@ function reduceAssistantEvent(state, event) {
                     ...blocks.slice(0, -1),
                     {
                         kind: 'text',
-                        content: keepLatest(last.content + content.text, MAX_TEXT_CHARS),
+                        content: keepTail(last.content + content.text, MAX_TEXT_CHARS),
                         timestamp: last.timestamp ?? event.timestamp,
                     },
                 ]
@@ -334,7 +336,7 @@ function reduceAssistantEvent(state, event) {
                     ...blocks,
                     {
                         kind: 'text',
-                        content: keepLatest(content.text, MAX_TEXT_CHARS),
+                        content: keepTail(content.text, MAX_TEXT_CHARS),
                         timestamp: event.timestamp,
                     },
                 ];
@@ -412,7 +414,7 @@ function reducePlanEvent(state, event) {
     if (event.type !== 'plan')
         return state;
     const currentPlan = state.plan ?? '';
-    const newPlan = keepLatest(currentPlan + '\n' + event.plan, MAX_REASONING_CHARS * 2);
+    const newPlan = keepTail(currentPlan + '\n' + event.plan, MAX_REASONING_CHARS * 2);
     // Plan is a single evolving document — replace the existing plan block
     // instead of appending a new one (avoids N overlapping blocks after N events).
     const withoutOldPlan = state.blocks.filter((b) => b.kind !== 'plan');
@@ -458,12 +460,18 @@ export function finishRun(state, terminal, meta = {}) {
             return state;
         return { ...state, ...sanitizeMeta(meta) };
     }
+    // interrupted 终态的中断来源：显式传入优先；否则从顶层持久标记推导
+    // （approval_expired 已置位但调用方未传 reason 的路径，如协调器过期自动
+    // cancel。原因必须在终态确定，不依赖调用方记得传参）。
+    const derivedReason = meta.interruptedReason ??
+        (terminal === 'interrupted' && state.approvalExpired === true ? 'approval_timeout' : undefined);
     return {
         ...state,
         terminal,
         footer: null,
         blocks: markThinkingInactive(state.blocks),
         ...sanitizeMeta(meta),
+        ...(derivedReason !== undefined ? { interruptedReason: derivedReason } : {}),
     };
 }
 /** Remove undefined/null meta fields to avoid overwriting existing state with nullish values. */
@@ -483,7 +491,11 @@ function stringifyUnknown(value) {
     if (typeof value === 'string')
         return value;
     try {
-        return JSON.stringify(value);
+        // JSON.stringify(undefined) returns the value undefined, which would
+        // violate this function's string contract and crash callers that take
+        // .length on the result (2026-08-17 kimi ACP tool_call without rawInput
+        // → truncateDetail TypeError). Normalize to ''.
+        return JSON.stringify(value) ?? '';
     }
     catch {
         return String(value);
@@ -507,9 +519,6 @@ function tryParseRecord(input) {
         return null;
     }
 }
-function keepLatest(value, maxChars) {
-    return value.length <= maxChars ? value : value.slice(-maxChars);
-}
 function keepLatestBlocks(blocks) {
     return blocks.length <= MAX_BLOCKS ? blocks : blocks.slice(-MAX_BLOCKS);
 }

package/dist/card/text-truncate.d.ts

@@ -1,20 +1,27 @@
 /**
  * UTF-8 byte-safe text truncation primitives.
  *
- * Shared by the live run renderer (`run-renderer.ts`), the static card budget
- * enforcer (`card-budget.ts`), and the opencode session reader
- * (`src/session/opencode/sessions.ts`) so that huge tool outputs are folded at a single
- * place instead of being reimplemented per consumer.
+ * The core `fitUtf8` / `truncateUtf8` / `DEFAULT_TRUNCATE_SUFFIX` primitives
+ * live in `src/common/truncate.ts` (shared with session readers to avoid a
+ * card→session layer inversion); this module re-exports them and adds the
+ * card-specific markdown-table helpers.
  *
  * Why byte-safe: Feishu card size limits are measured in UTF-8 bytes, and a
  * naive `str.slice(0, n)` can split a multi-byte CJK/emoji codepoint, yielding
  * invalid UTF-8. `fitUtf8` iterates by Unicode codepoint (via `Array.from` /
  * `for...of`) so it never breaks a surrogate pair or a multi-byte sequence.
  */
+import { DEFAULT_TRUNCATE_SUFFIX, truncateUtf8 } from '../common/truncate.js';
+export { DEFAULT_TRUNCATE_SUFFIX, truncateUtf8 };
 /** Feishu 11310 limit: max markdown tables per card. */
 export declare const FEISHU_MAX_TABLES = 5;
-/** Default truncation suffix, shared across all consumers for UX consistency. */
-export declare const DEFAULT_TRUNCATE_SUFFIX = "\u2026\uFF08\u5DF2\u622A\u65AD\uFF09";
+/**
+ * Feishu 单卡字节上限（安全阈值）。
+ *
+ * 供 run-renderer（流式卡）、card-budget（静态卡）、bash-renderer（bash 卡）
+ * 共用，避免三处各自定义后数值漂移。
+ */
+export declare const CARD_BUDGET_BYTES = 28000;
 /**
  * Max byte budget for a single session `tool_result` event's content when
  * replaying an opencode session (L2 pre-fold). The static card budget enforcer
@@ -24,12 +31,6 @@ export declare const DEFAULT_TRUNCATE_SUFFIX = "\u2026\uFF08\u5DF2\u622A\u65AD\u
  * 500KB file listing) never inflates the replay payload to megabytes.
  */
 export declare const TOOL_RESULT_MAX_BYTES = 4000;
-/**
- * Truncate a UTF-8 string to fit within `maxBytes`, appending `suffix`
- * (default `…（已截断）`) when truncation occurs. When `fromEnd` is true, keeps
- * the tail and prepends the suffix (useful for "show the most recent N bytes").
- */
-export declare function truncateUtf8(value: string, maxBytes: number, fromEnd?: boolean, suffix?: string): string;
 /**
  * Count the number of markdown tables in a string.
  *

package/dist/card/text-truncate.js

@@ -1,20 +1,27 @@
 /**
  * UTF-8 byte-safe text truncation primitives.
  *
- * Shared by the live run renderer (`run-renderer.ts`), the static card budget
- * enforcer (`card-budget.ts`), and the opencode session reader
- * (`src/session/opencode/sessions.ts`) so that huge tool outputs are folded at a single
- * place instead of being reimplemented per consumer.
+ * The core `fitUtf8` / `truncateUtf8` / `DEFAULT_TRUNCATE_SUFFIX` primitives
+ * live in `src/common/truncate.ts` (shared with session readers to avoid a
+ * card→session layer inversion); this module re-exports them and adds the
+ * card-specific markdown-table helpers.
  *
  * Why byte-safe: Feishu card size limits are measured in UTF-8 bytes, and a
  * naive `str.slice(0, n)` can split a multi-byte CJK/emoji codepoint, yielding
  * invalid UTF-8. `fitUtf8` iterates by Unicode codepoint (via `Array.from` /
  * `for...of`) so it never breaks a surrogate pair or a multi-byte sequence.
  */
+import { DEFAULT_TRUNCATE_SUFFIX, truncateUtf8 } from '../common/truncate.js';
+export { DEFAULT_TRUNCATE_SUFFIX, truncateUtf8 };
 /** Feishu 11310 limit: max markdown tables per card. */
 export const FEISHU_MAX_TABLES = 5;
-/** Default truncation suffix, shared across all consumers for UX consistency. */
-export const DEFAULT_TRUNCATE_SUFFIX = '…（已截断）';
+/**
+ * Feishu 单卡字节上限（安全阈值）。
+ *
+ * 供 run-renderer（流式卡）、card-budget（静态卡）、bash-renderer（bash 卡）
+ * 共用，避免三处各自定义后数值漂移。
+ */
+export const CARD_BUDGET_BYTES = 28_000;
 /**
  * Max byte budget for a single session `tool_result` event's content when
  * replaying an opencode session (L2 pre-fold). The static card budget enforcer
@@ -24,63 +31,6 @@ export const DEFAULT_TRUNCATE_SUFFIX = '…（已截断）';
  * 500KB file listing) never inflates the replay payload to megabytes.
  */
 export const TOOL_RESULT_MAX_BYTES = 4000;
-/**
- * Fit a UTF-8 string into `maxBytes` by iterating Unicode codepoints, never
- * splitting a multi-byte sequence. When `fromEnd` is true, keeps the TAIL
- * (useful for logs/tails); otherwise keeps the HEAD.
- *
- * P1-2 (2026-08-02): 单遍累计单字符字节数，替代逐字符 `Buffer.byteLength(result +
- * char)` + `result += char`（后者每轮新建并扫描不断增长的字符串，O(budget²)）。
- * 字节长度对拼接可加（byteLength(a+b) = byteLength(a) + byteLength(b)），故累计
- * 与旧实现的逐字符判断逐字节等价；最后一次 slice/join 物化结果。混合 CJK/emoji
- * 样本实测 ~150× 提速（33.7ms/次 → 0.2ms/次，见 tests/anchor/priority/p0-fit-utf8.test.ts）。
- */
-function fitUtf8(value, maxBytes, fromEnd = false) {
-    if (fromEnd) {
-        // tail 分支：需要从末尾找截断起点，Array.from 一次物化（旧实现同样 Array.from().reverse()，
-        // 无内存回归）；数组仅用于定位，之后 slice+join。
-        const codepoints = Array.from(value);
-        let bytes = 0;
-        let start = codepoints.length;
-        for (let i = codepoints.length - 1; i >= 0; i--) {
-            const cb = Buffer.byteLength(codepoints[i], 'utf8');
-            if (bytes + cb > maxBytes)
-                break;
-            bytes += cb;
-            start = i;
-        }
-        return codepoints.slice(start).join('');
-    }
-    // head 分支：惰性 for-of 迭代 + 字符串索引累计（旧实现同 O(1) 内存）。
-    // 不物化数组——opencode-sessions 会对 MB 级 tool_result 做 head 截断，
-    // Array.from 全量分配会引入不必要的瞬态内存。
-    let bytes = 0;
-    let end = 0;
-    for (const char of value) {
-        const cb = Buffer.byteLength(char, 'utf8');
-        if (bytes + cb > maxBytes)
-            break;
-        bytes += cb;
-        end += char.length; // for-of 产出完整码点；char.length 为 1 或 2（代理对），
-        // end 落在码点边界上，value.slice(0, end) 不会切分代理对
-    }
-    return value.slice(0, end);
-}
-/**
- * Truncate a UTF-8 string to fit within `maxBytes`, appending `suffix`
- * (default `…（已截断）`) when truncation occurs. When `fromEnd` is true, keeps
- * the tail and prepends the suffix (useful for "show the most recent N bytes").
- */
-export function truncateUtf8(value, maxBytes, fromEnd = false, suffix = DEFAULT_TRUNCATE_SUFFIX) {
-    if (Buffer.byteLength(value, 'utf8') <= maxBytes)
-        return value;
-    const suffixBytes = Buffer.byteLength(suffix, 'utf8');
-    const budget = maxBytes - suffixBytes;
-    if (budget <= 0)
-        return suffix;
-    const truncated = fitUtf8(value, budget, fromEnd);
-    return fromEnd ? `${suffix}\n${truncated}` : `${truncated}${suffix}`;
-}
 /**
  * Count the number of markdown tables in a string.
  *

package/dist/common/fs.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Unlink a file, silently ignoring ENOENT and other errors.
+ *
+ * Use for cleanup paths (pid files, temp files, stale locks) where the
+ * file may already be gone or was never created — a missing file is not
+ * an error worth propagating.
+ */
+export declare function silentlyUnlink(path: string): void;

package/dist/common/fs.js

@@ -0,0 +1,17 @@
+import fs from 'node:fs';
+/**
+ * Unlink a file, silently ignoring ENOENT and other errors.
+ *
+ * Use for cleanup paths (pid files, temp files, stale locks) where the
+ * file may already be gone or was never created — a missing file is not
+ * an error worth propagating.
+ */
+export function silentlyUnlink(path) {
+    try {
+        fs.unlinkSync(path);
+    }
+    catch {
+        /* ignore — file may not exist */
+    }
+}
+//# sourceMappingURL=fs.js.map

package/dist/common/guards.d.ts

@@ -11,27 +11,7 @@
  * Used as a prerequisite before accessing string-keyed properties.
  */
 export declare function isRecord(v: unknown): v is Record<string, unknown>;
-/**
- * Narrows `v` to `Record<string, unknown>` when it is a non-null object,
- * otherwise returns `undefined`.
- */
-export declare function recordValue(v: unknown): Record<string, unknown> | undefined;
 /**
  * Returns the string value when `v` is a `string`, otherwise `undefined`.
  */
 export declare function stringValue(v: unknown): string | undefined;
-/**
- * Returns the number value when `v` is a `number`, otherwise `undefined`.
- */
-export declare function numberValue(v: unknown): number | undefined;
-/**
- * Extracts a human-readable error message from an opaque error object.
- *
- * Priority:
- *  1. `raw.message`  (string)
- *  2. `raw.error.message`  (string, when `raw.error` is a record)
- *  3. `raw.error.data.message`  (string, AI SDK wraps provider errors as {error:{data:{message}}})
- *  4. `raw.error` itself  (when it is a string)
- *  5. `fallback`
- */
-export declare function extractErrorMessage(raw: Record<string, unknown>, fallback: string): string;

package/dist/common/guards.js

@@ -13,53 +13,10 @@
 export function isRecord(v) {
     return typeof v === 'object' && v !== null;
 }
-/**
- * Narrows `v` to `Record<string, unknown>` when it is a non-null object,
- * otherwise returns `undefined`.
- */
-export function recordValue(v) {
-    return isRecord(v) ? v : undefined;
-}
 /**
  * Returns the string value when `v` is a `string`, otherwise `undefined`.
  */
 export function stringValue(v) {
     return typeof v === 'string' ? v : undefined;
 }
-/**
- * Returns the number value when `v` is a `number`, otherwise `undefined`.
- */
-export function numberValue(v) {
-    return typeof v === 'number' ? v : undefined;
-}
-/**
- * Extracts a human-readable error message from an opaque error object.
- *
- * Priority:
- *  1. `raw.message`  (string)
- *  2. `raw.error.message`  (string, when `raw.error` is a record)
- *  3. `raw.error.data.message`  (string, AI SDK wraps provider errors as {error:{data:{message}}})
- *  4. `raw.error` itself  (when it is a string)
- *  5. `fallback`
- */
-export function extractErrorMessage(raw, fallback) {
-    const msg = stringValue(raw.message);
-    if (msg !== undefined)
-        return msg;
-    const err = raw.error;
-    if (isRecord(err)) {
-        const subMsg = stringValue(err.message);
-        if (subMsg !== undefined)
-            return subMsg;
-        const data = recordValue(err.data);
-        if (data) {
-            const dataMsg = stringValue(data.message);
-            if (dataMsg !== undefined)
-                return dataMsg;
-        }
-    }
-    if (typeof err === 'string')
-        return err;
-    return fallback;
-}
 //# sourceMappingURL=guards.js.map

package/dist/common/sleep.d.ts

@@ -0,0 +1,2 @@
+/** Wait for `ms` milliseconds. */
+export declare function sleep(ms: number): Promise<void>;

package/dist/common/sleep.js

@@ -0,0 +1,5 @@
+/** Wait for `ms` milliseconds. */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=sleep.js.map

package/dist/common/truncate.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared text truncation primitives.
+ *
+ * Centralizes the two truncation utilities previously split across the card
+ * layer (`card-shared.ts` char-based `truncate` and `card/text-truncate.ts`
+ * byte-safe `truncateUtf8`). Session readers import from here instead of the
+ * card layer (fixing the layer inversion), and the card layer re-exports for
+ * backward compatibility.
+ */
+/** Default truncation suffix, shared across all consumers for UX consistency. */
+export declare const DEFAULT_TRUNCATE_SUFFIX = "\u2026\uFF08\u5DF2\u622A\u65AD\uFF09";
+/**
+ * Max byte budget for a single session `tool_result` event's content when
+ * replaying an opencode session (L2 pre-fold). Pre-folding here bounds the
+ * in-memory `events[]` array and the intermediate card JSON so a single
+ * pathological tool_result never inflates the replay payload to megabytes.
+ */
+export declare const TOOL_RESULT_MAX_BYTES = 4000;
+/**
+ * Fit a UTF-8 string into `maxBytes` by iterating Unicode codepoints, never
+ * splitting a multi-byte sequence. When `fromEnd` is true, keeps the TAIL
+ * (useful for logs/tails); otherwise keeps the HEAD.
+ */
+export declare function fitUtf8(value: string, maxBytes: number, fromEnd?: boolean): string;
+/**
+ * Truncate a UTF-8 string to fit within `maxBytes`, appending `suffix`
+ * (default `…（已截断）`) when truncation occurs. When `fromEnd` is true, keeps
+ * the tail and prepends the suffix (useful for "show the most recent N bytes").
+ */
+export declare function truncateUtf8(value: string, maxBytes: number, fromEnd?: boolean, suffix?: string): string;
+interface TruncateOptions {
+    suffix?: string;
+    normalizeWhitespace?: boolean;
+}
+/** Char-based truncation with optional suffix / whitespace normalization. */
+export declare function truncate(str: string, max: number, options?: TruncateOptions): string;
+/** Char-level tail keep (used for store-time caps, e.g. bash output). */
+export declare function keepTail(value: string, maxChars: number): string;
+export {};

package/dist/common/truncate.js

@@ -0,0 +1,92 @@
+/**
+ * Shared text truncation primitives.
+ *
+ * Centralizes the two truncation utilities previously split across the card
+ * layer (`card-shared.ts` char-based `truncate` and `card/text-truncate.ts`
+ * byte-safe `truncateUtf8`). Session readers import from here instead of the
+ * card layer (fixing the layer inversion), and the card layer re-exports for
+ * backward compatibility.
+ */
+/** Default truncation suffix, shared across all consumers for UX consistency. */
+export const DEFAULT_TRUNCATE_SUFFIX = '…（已截断）';
+/**
+ * Max byte budget for a single session `tool_result` event's content when
+ * replaying an opencode session (L2 pre-fold). Pre-folding here bounds the
+ * in-memory `events[]` array and the intermediate card JSON so a single
+ * pathological tool_result never inflates the replay payload to megabytes.
+ */
+export const TOOL_RESULT_MAX_BYTES = 4000;
+/**
+ * Fit a UTF-8 string into `maxBytes` by iterating Unicode codepoints, never
+ * splitting a multi-byte sequence. When `fromEnd` is true, keeps the TAIL
+ * (useful for logs/tails); otherwise keeps the HEAD.
+ */
+export function fitUtf8(value, maxBytes, fromEnd = false) {
+    if (fromEnd) {
+        const codepoints = Array.from(value);
+        let bytes = 0;
+        let start = codepoints.length;
+        for (let i = codepoints.length - 1; i >= 0; i--) {
+            const cb = Buffer.byteLength(codepoints[i], 'utf8');
+            if (bytes + cb > maxBytes)
+                break;
+            bytes += cb;
+            start = i;
+        }
+        return codepoints.slice(start).join('');
+    }
+    // head 分支：惰性 for-of 迭代 + 字符串索引累计（O(1) 内存）。
+    let bytes = 0;
+    let end = 0;
+    for (const char of value) {
+        const cb = Buffer.byteLength(char, 'utf8');
+        if (bytes + cb > maxBytes)
+            break;
+        bytes += cb;
+        end += char.length;
+    }
+    return value.slice(0, end);
+}
+/**
+ * Truncate a UTF-8 string to fit within `maxBytes`, appending `suffix`
+ * (default `…（已截断）`) when truncation occurs. When `fromEnd` is true, keeps
+ * the tail and prepends the suffix (useful for "show the most recent N bytes").
+ */
+export function truncateUtf8(value, maxBytes, fromEnd = false, suffix = DEFAULT_TRUNCATE_SUFFIX) {
+    if (Buffer.byteLength(value, 'utf8') <= maxBytes)
+        return value;
+    const suffixBytes = Buffer.byteLength(suffix, 'utf8');
+    const budget = maxBytes - suffixBytes;
+    if (budget <= 0)
+        return suffix;
+    const truncated = fitUtf8(value, budget, fromEnd);
+    return fromEnd ? `${suffix}\n${truncated}` : `${truncated}${suffix}`;
+}
+/** Char-based truncation with optional suffix / whitespace normalization. */
+export function truncate(str, max, options) {
+    const suffix = options?.suffix ?? '…';
+    const normalize = options?.normalizeWhitespace ?? false;
+    let s = str;
+    if (normalize)
+        s = s.replace(/\s+/g, ' ').trim();
+    if (s.length <= max)
+        return s;
+    const suffixLen = suffix.length;
+    const budget = max - suffixLen;
+    if (budget <= 0)
+        return suffix;
+    // Iterate by Unicode codepoint (for...of) so the cut never lands inside a
+    // surrogate pair (P2-31 anchor: must not emit a lone surrogate).
+    let end = 0;
+    for (const ch of s) {
+        if (end + ch.length > budget)
+            break;
+        end += ch.length; // 1 (BMP) or 2 (surrogate pair) — slice lands on a boundary
+    }
+    return s.slice(0, end) + suffix;
+}
+/** Char-level tail keep (used for store-time caps, e.g. bash output). */
+export function keepTail(value, maxChars) {
+    return value.length <= maxChars ? value : value.slice(-maxChars);
+}
+//# sourceMappingURL=truncate.js.map

package/dist/config/codex-config.d.ts

@@ -80,7 +80,7 @@ export declare function getCodexCatalogModels(codexHome?: string): BundledModelI
 /**
  * Test utility: clear the catalog cache. Tests that exercise the bundled
  * command path (`--bundled`) directly use `invalidateCodexBundledTestCache`
- * from `codex-bundled-test-helpers.ts`.
+ * from `tests/lib/codex-bundled-test-helpers.ts`.
  */
 export declare function invalidateCodexBundledCache(): void;
 /**

package/dist/config/codex-config.js

@@ -208,7 +208,7 @@ export function getCodexCatalogModels(codexHome) {
 /**
  * Test utility: clear the catalog cache. Tests that exercise the bundled
  * command path (`--bundled`) directly use `invalidateCodexBundledTestCache`
- * from `codex-bundled-test-helpers.ts`.
+ * from `tests/lib/codex-bundled-test-helpers.ts`.
  */
 export function invalidateCodexBundledCache() {
     catalogCache = null;