@theokit/sdk-tools 0.25.0 → 0.26.0

package/dist/index.d.cts

@@ -1099,24 +1099,59 @@ declare function todoItemsToPlanNodes(items: readonly TodoItem[]): PlanNode[];
 /**
  * `truncateOutput` — utility for truncating large tool output.
  *
- * When output exceeds `maxBytes`, writes the full content to a temp file
- * and returns a truncated version with a reference to the full output.
+ * When output exceeds `maxBytes`, writes the full content to a temp file and returns a truncated
+ * version with a reference to the full output.
+ *
+ * ## M77 — why this grew instead of a new truncator being written
+ *
+ * The M77 discovery measured **six** output ceilings across `sdk-tools`, with five different values
+ * and no coordination between them (`web-fetch.ts` 1 MB, `shell-exec.ts` 5 MB, `git-diff.ts` 5 MB,
+ * `run-vitest.ts` 10 MB, `git-status.ts` configurable, and this helper's 30 000 B). It also found
+ * that this helper — exported from the barrel — had **zero production consumers**: the SDK had
+ * already paid for a shared truncator that nobody used while every tool rolled its own.
+ *
+ * Adding a seventh ceiling in the runtime would have been the defect, not the fix. So `toolResultBudget`
+ * extends this one instead (parsimony-ladder rung 4), gaining the two things it lacked:
+ *
+ *  - **`head-tail` mode** — the previous cut was head-only, which for command output discards
+ *    exactly the part that matters: the error, the summary, the final prompt.
+ *  - **`originalBytes`** — a machine-readable marker. The only prior signal was an English sentence
+ *    injected into the text (`"[Output truncated. Full output: …]"`), so a consumer wanting to know
+ *    how much was lost had to parse prose.
+ *
+ * Consolidating the MECHANISM is deliberately not the same as unifying the VALUES: 1 MB for
+ * `web-fetch` and 10 MB for `run-vitest` may differ for good reasons. That second step is out of
+ * scope here (plan ADR D2).
  *
  * Return shape:
- *   - `{ content: string, truncated: false }`
- *   - `{ content: string, truncated: true, overflowPath: string }`
+ *   - `{ content, truncated: false, originalBytes }`
+ *   - `{ content, truncated: true, originalBytes, overflowPath }`
  */
+/** How the middle is dropped when output exceeds the budget. */
+type TruncationMode = "head" | "head-tail";
 interface TruncationOptions {
     /** Maximum output size in bytes before truncation. Default: 30_000. */
     maxBytes?: number;
     /** Directory for overflow files. Default: ".theocode/tool-output". */
     outputDir?: string;
+    /**
+     * `"head"` (default) keeps the first `maxBytes` — the historical behaviour, preserved because this
+     * helper is public API. `"head-tail"` splits the budget between the start and the END, which is
+     * where command output usually carries its conclusion.
+     */
+    mode?: TruncationMode;
 }
 interface TruncationResult {
     /** The (possibly truncated) content. */
     content: string;
     /** Whether the output was truncated. */
     truncated: boolean;
+    /**
+     * Byte length of the ORIGINAL output, present on both paths. Always present by design: a field
+     * that only appears on failure forces every consumer through an `undefined` check, which is the
+     * door magic values come in through.
+     */
+    originalBytes: number;
     /** Path to the full output file, present only when truncated. */
     overflowPath?: string;
 }

package/dist/index.d.ts

@@ -1099,24 +1099,59 @@ declare function todoItemsToPlanNodes(items: readonly TodoItem[]): PlanNode[];
 /**
  * `truncateOutput` — utility for truncating large tool output.
  *
- * When output exceeds `maxBytes`, writes the full content to a temp file
- * and returns a truncated version with a reference to the full output.
+ * When output exceeds `maxBytes`, writes the full content to a temp file and returns a truncated
+ * version with a reference to the full output.
+ *
+ * ## M77 — why this grew instead of a new truncator being written
+ *
+ * The M77 discovery measured **six** output ceilings across `sdk-tools`, with five different values
+ * and no coordination between them (`web-fetch.ts` 1 MB, `shell-exec.ts` 5 MB, `git-diff.ts` 5 MB,
+ * `run-vitest.ts` 10 MB, `git-status.ts` configurable, and this helper's 30 000 B). It also found
+ * that this helper — exported from the barrel — had **zero production consumers**: the SDK had
+ * already paid for a shared truncator that nobody used while every tool rolled its own.
+ *
+ * Adding a seventh ceiling in the runtime would have been the defect, not the fix. So `toolResultBudget`
+ * extends this one instead (parsimony-ladder rung 4), gaining the two things it lacked:
+ *
+ *  - **`head-tail` mode** — the previous cut was head-only, which for command output discards
+ *    exactly the part that matters: the error, the summary, the final prompt.
+ *  - **`originalBytes`** — a machine-readable marker. The only prior signal was an English sentence
+ *    injected into the text (`"[Output truncated. Full output: …]"`), so a consumer wanting to know
+ *    how much was lost had to parse prose.
+ *
+ * Consolidating the MECHANISM is deliberately not the same as unifying the VALUES: 1 MB for
+ * `web-fetch` and 10 MB for `run-vitest` may differ for good reasons. That second step is out of
+ * scope here (plan ADR D2).
  *
  * Return shape:
- *   - `{ content: string, truncated: false }`
- *   - `{ content: string, truncated: true, overflowPath: string }`
+ *   - `{ content, truncated: false, originalBytes }`
+ *   - `{ content, truncated: true, originalBytes, overflowPath }`
  */
+/** How the middle is dropped when output exceeds the budget. */
+type TruncationMode = "head" | "head-tail";
 interface TruncationOptions {
     /** Maximum output size in bytes before truncation. Default: 30_000. */
     maxBytes?: number;
     /** Directory for overflow files. Default: ".theocode/tool-output". */
     outputDir?: string;
+    /**
+     * `"head"` (default) keeps the first `maxBytes` — the historical behaviour, preserved because this
+     * helper is public API. `"head-tail"` splits the budget between the start and the END, which is
+     * where command output usually carries its conclusion.
+     */
+    mode?: TruncationMode;
 }
 interface TruncationResult {
     /** The (possibly truncated) content. */
     content: string;
     /** Whether the output was truncated. */
     truncated: boolean;
+    /**
+     * Byte length of the ORIGINAL output, present on both paths. Always present by design: a field
+     * that only appears on failure forces every consumer through an `undefined` check, which is the
+     * door magic values come in through.
+     */
+    originalBytes: number;
     /** Path to the full output file, present only when truncated. */
     overflowPath?: string;
 }

package/dist/index.js

@@ -11,6 +11,7 @@ import { spawn } from 'child_process';
 import { resolveInteractive, InteractiveUnavailableError, NoSuchSessionError } from '@theokit/sdk/interactive';
 import { lookup } from 'dns/promises';
 import { isIP } from 'net';
+import { randomUUID } from 'crypto';
 
 // src/apply-patch.ts
 
@@ -2543,24 +2544,44 @@ function createTodolistTool() {
     getItems: (threadId) => ops(threadId).getItems()
   };
 }
+function decodeWholeCodePoints(buf) {
+  return new TextDecoder("utf-8").decode(buf, { stream: true });
+}
 function truncateOutput(output, opts) {
   const maxBytes = opts?.maxBytes ?? 3e4;
   const outputDir = opts?.outputDir ?? ".theocode/tool-output";
-  const byteLength = Buffer.byteLength(output, "utf-8");
-  if (byteLength <= maxBytes) {
-    return { content: output, truncated: false };
+  const mode = opts?.mode ?? "head";
+  const originalBytes = Buffer.byteLength(output, "utf-8");
+  if (originalBytes <= maxBytes) {
+    return { content: output, truncated: false, originalBytes };
   }
   mkdirSync(outputDir, { recursive: true });
-  const filename = `overflow-${Date.now()}.txt`;
+  const filename = `overflow-${Date.now()}-${randomUUID().slice(0, 8)}.txt`;
   const overflowPath = join(outputDir, filename);
   writeFileSync(overflowPath, output, "utf-8");
-  const truncated = Buffer.from(output, "utf-8").subarray(0, maxBytes).toString("utf-8");
+  const buf = Buffer.from(output, "utf-8");
   const trailer = `
 
 [Output truncated. Full output: ${overflowPath}]`;
+  if (mode === "head-tail") {
+    const half = Math.floor(maxBytes / 2);
+    const head = decodeWholeCodePoints(buf.subarray(0, half));
+    const tail = decodeWholeCodePoints(buf.subarray(buf.length - half));
+    return {
+      content: `${head}
+
+[\u2026 ${String(originalBytes - maxBytes)} bytes omitted \u2026]
+
+${tail}${trailer}`,
+      truncated: true,
+      originalBytes,
+      overflowPath
+    };
+  }
   return {
-    content: truncated + trailer,
+    content: decodeWholeCodePoints(buf.subarray(0, maxBytes)) + trailer,
     truncated: true,
+    originalBytes,
     overflowPath
   };
 }