@humain/terminal 0.1.1 → 0.2.1

package/dist/humain/mcp-adapter/vendor/mcp-code.ts

@@ -1,17 +1,19 @@
 import type { ToolInfo } from "@earendil-works/pi-coding-agent";
 import { formatWithOptions } from "node:util";
 import { Worker } from "node:worker_threads";
+import { throwIfAborted } from "./abort.ts";
 import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions } from "./mcp-output-guard.ts";
 import { executeCall } from "./proxy-modes.ts";
 import { combineAbortSignals } from "./runtime-owner.ts";
 import { paginate, rankSuggestions, rankToolMatches } from "./search-ranking.ts";
 import { isServerInActiveFailureBackoff } from "./failure-backoff.ts";
 import type { McpExtensionState } from "./state.ts";
-import { findToolByName, formatSchema } from "./tool-metadata.ts";
+import { findToolByName, formatSchema, hasSchemaDescriptions } from "./tool-metadata.ts";
 import { renderTsShape } from "./ts-shape.ts";
 import type { ContentBlock } from "./types.ts";
 
 export const DEFAULT_MCP_SCRIPT_TIMEOUT_MS = 30_000;
+const MCP_SCRIPT_INTERMEDIATE_MAX_BYTES = 16 * 1024 * 1024;
 
 class McpScriptTimeoutError extends Error {
   constructor(timeoutMs: number) {
@@ -30,7 +32,8 @@ type WorkerMessage =
   | { type: "done"; returnBlock?: unknown }
   | { type: "error"; message: string };
 
-type WorkerResultMessage = { type: "result"; id: number; envelope: unknown };
+type WorkerResultPayload = { envelope: unknown } | { dataJson: string };
+type WorkerResultMessage = { type: "result"; id: number } & WorkerResultPayload;
 
 function needsInspectableFormatting(value: unknown, stack = new WeakSet<object>()): boolean {
   if (value === undefined || typeof value === "bigint" || typeof value === "function" || typeof value === "symbol") return true;
@@ -136,11 +139,18 @@ export async function runMcpScript(
       : operation.durationMs,
   }));
   let callsSnapshot: ScriptOperation[] | undefined;
-  const callTool = async (path: string, args?: Record<string, unknown>) => {
+  let intermediateBytes = 0;
+  const callTool = async (path: string, args?: Record<string, unknown>): Promise<WorkerResultPayload> => {
     // Record before dispatch so calls still in flight at timeout/abort appear in the trace.
     const startedAt = Date.now();
     const index = calls.push({ operation: "call", path, ok: false, error: "incomplete", durationMs: 0, startedAt }) - 1;
-    const result = await executeCall(state, path, args, undefined, getPiTools, callSignal, "script");
+    let dataJson: string | undefined;
+    const result = await executeCall(state, path, args, undefined, getPiTools, callSignal, "script", {
+      onSuccess(data) {
+        // Serialize once for both byte accounting and worker transfer, never for display.
+        dataJson = JSON.stringify(data);
+      },
+    });
     const details = result.details;
     if (details.error !== undefined) {
       const errorCode = String(details.error);
@@ -154,15 +164,26 @@ export async function runMcpScript(
           : textFromContent(result.content);
       calls[index] = { operation: "call", path, ok: false, error: errorCode, durationMs: Date.now() - startedAt, startedAt };
       return {
-        ok: false as const,
-        error: { code: errorCode, message },
+        envelope: { ok: false, error: { code: errorCode, message } },
+      };
+    }
+    throwIfAborted(callSignal);
+    if (dataJson === undefined) throw new Error("MCP intermediate result was not JSON serializable");
+    const bytes = Buffer.byteLength(dataJson, "utf8");
+    if (bytes > MCP_SCRIPT_INTERMEDIATE_MAX_BYTES - intermediateBytes) {
+      const code = "intermediate_result_too_large";
+      calls[index] = { operation: "call", path, ok: false, error: code, durationMs: Date.now() - startedAt, startedAt };
+      return {
+        envelope: {
+          ok: false,
+          error: { code, message: "MCP result exceeds the remaining mcpScript intermediate transfer budget (16 MiB per script). Request less data or use a new script." },
+        },
       };
     }
+    // Rejected responses do not consume budget. This bounds transfer, not upstream allocation.
+    intermediateBytes += bytes;
     calls[index] = { operation: "call", path, ok: true, durationMs: Date.now() - startedAt, startedAt };
-    return {
-      ok: true as const,
-      data: details.mcpResult !== undefined ? details.mcpResult : textFromContent(result.content),
-    };
+    return { dataJson };
   };
 
   const searchTools = (input?: SearchInput) => {
@@ -206,15 +227,20 @@ export async function runMcpScript(
         if (isServerInActiveFailureBackoff(state, server)) continue;
         const tool = findToolByName(metadata, path);
         if (!tool) continue;
-        const inputTypeScript = tool.inputSchema
-          ? renderTsShape(tool.inputSchema) ?? formatSchema(tool.inputSchema)
-          : null;
+        const inputShape = tool.inputSchema ? renderTsShape(tool.inputSchema) : null;
+        const inputTypeScript = inputShape ?? (tool.inputSchema ? formatSchema(tool.inputSchema) : null);
         return {
           path: tool.name,
           name: tool.originalName,
           server,
           ...(tool.description ? { description: tool.description } : {}),
           ...(inputTypeScript ? { inputTypeScript } : {}),
+          ...(inputShape && hasSchemaDescriptions(tool.inputSchema)
+            ? { inputGuidance: formatSchema(tool.inputSchema) } : {}),
+          ...(tool.outputSchema !== undefined ? {
+            outputSchemaTarget: "data.structuredContent",
+            outputSchema: tool.outputSchema,
+          } : {}),
         };
       }
       const suggestions = path ? rankSuggestions(state, path, 5) : [];
@@ -279,15 +305,16 @@ export async function runMcpScript(
         }
 
         void (async () => {
-          let envelope: unknown;
+          let payload: WorkerResultPayload;
           if (message.type === "call") {
-            envelope = await callTool(message.path, message.args as Record<string, unknown> | undefined);
+            payload = await callTool(message.path, message.args as Record<string, unknown> | undefined);
           } else if (message.type === "search") {
-            envelope = searchTools(message.input as SearchInput | undefined);
+            payload = { envelope: searchTools(message.input as SearchInput | undefined) };
           } else {
-            envelope = describeTool(message.input as DescribeInput | undefined);
+            payload = { envelope: describeTool(message.input as DescribeInput | undefined) };
           }
-          const response: WorkerResultMessage = { type: "result", id: message.id, envelope };
+          if (completed || callSignal?.aborted) return;
+          const response: WorkerResultMessage = { type: "result", id: message.id, ...payload };
           activeWorker.postMessage(response);
         })().catch(reject);
       });

package/dist/humain/mcp-adapter/vendor/mcp-install.ts

@@ -0,0 +1,60 @@
+const SERVER_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+
+export interface McpInstallRequest {
+  url: string;
+  serverName?: string;
+}
+
+export interface NormalizedMcpInstallRequest {
+  url: string;
+  serverName: string;
+}
+
+function isLoopbackHostname(hostname: string): boolean {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
+}
+
+function deriveServerName(url: URL): string {
+  const hostname = url.hostname.replace(/^\[|\]$/g, "");
+  const firstLabel = isLoopbackHostname(url.hostname) ? "local-mcp" : hostname.split(".")[0];
+  const normalized = (firstLabel || "mcp")
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 64);
+  return normalized || "mcp";
+}
+
+export function normalizeMcpInstallRequest(request: McpInstallRequest): NormalizedMcpInstallRequest {
+  if (typeof request.url !== "string" || request.url.trim() === "") {
+    throw new Error("MCP install requires a non-empty URL");
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(request.url.trim());
+  } catch (error) {
+    throw new Error("MCP install URL must be an absolute URL", { cause: error });
+  }
+
+  if (parsed.username || parsed.password) throw new Error("MCP install URL must not contain credentials");
+  if (parsed.hash) throw new Error("MCP install URL must not contain a fragment");
+  if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && isLoopbackHostname(parsed.hostname))) {
+    throw new Error("MCP install URL must use HTTPS, except for loopback HTTP servers");
+  }
+
+  const serverName = request.serverName?.trim() || deriveServerName(parsed);
+  if (!SERVER_NAME_PATTERN.test(serverName)) {
+    throw new Error("MCP server name must be 1-64 letters, numbers, underscores, or hyphens and start with a letter or number");
+  }
+
+  return { url: parsed.toString(), serverName };
+}
+
+export function canonicalMcpServerUrl(value: string): string | undefined {
+  try {
+    return new URL(value).toString();
+  } catch {
+    return undefined;
+  }
+}

package/dist/humain/mcp-adapter/vendor/mcp-oauth-provider.ts

@@ -7,6 +7,7 @@
 
 import {
   UnauthorizedError,
+  type FetchLike,
   type AddClientAuthentication,
   type OAuthClientInformationContext,
   type OAuthClientProvider,
@@ -24,12 +25,15 @@ import {
   clearAllCredentials,
   clearCodeVerifier,
   invalidateAuthEntryCache,
+  captureOAuthAuthority,
   type AuthEntry,
   type AuthStorageOptions,
+  type OAuthAuthority,
   type StoredTokens,
   type StoredClientInfo,
 } from "./mcp-auth.ts"
 import { OAuthMetadataSchema, OpenIdProviderDiscoveryMetadataSchema } from "@modelcontextprotocol/core"
+import { createOAuthFetch, type OAuthFetch } from "./mcp-auth-fetch.ts"
 import { resolveCommandSecret } from "./utils.ts"
 import { getAppClientUri, getAppName } from "./agent-dir.ts"
 
@@ -125,6 +129,7 @@ export interface McpOAuthConfig {
   grantType?: "authorization_code" | "client_credentials"
   clientId?: string
   clientSecret?: string
+  clientMetadataUrl?: string
   scope?: string
   authorizationParams?: Record<string, string>
   redirectUri?: string
@@ -213,11 +218,10 @@ async function loadConfiguredDiscoveryState(
   metadataUrl: string,
   serverUrl: string,
   skipIssuerValidation: boolean,
-  signal?: AbortSignal,
+  fetchFn: FetchLike,
 ): Promise<OAuthDiscoveryState> {
-  const response = await fetch(metadataUrl, {
+  const response = await fetchFn(metadataUrl, {
     headers: { accept: "application/json" },
-    ...(signal !== undefined ? { signal } : {}),
   })
   if (!response.ok) {
     await response.text().catch(() => {})
@@ -247,7 +251,9 @@ async function loadConfiguredDiscoveryState(
  * Implements the OAuthClientProvider interface from the MCP SDK.
  */
 export class McpOAuthProvider implements OAuthClientProvider {
+  readonly clientMetadataUrl?: string
   private readonly redirectUrlSnapshot: string | undefined
+  private authFetch: OAuthFetch
   private active = true
   private flowClientInfo: StoredClientInfo | undefined
   private flowCodeVerifier: string | undefined
@@ -256,9 +262,11 @@ export class McpOAuthProvider implements OAuthClientProvider {
   private flowState: string | undefined
   private invalidatedAccessToken: string | undefined
   private invalidatedClientId: string | undefined
+  private staleRedirectClientId: string | undefined
   private lastObservedClientId: string | undefined
   private lastSavedAccessToken: string | undefined
   private pendingAuthAccessToken: string | undefined
+  private readonly assertAuthority: OAuthAuthority
 
   constructor(
     private serverName: string,
@@ -268,13 +276,24 @@ export class McpOAuthProvider implements OAuthClientProvider {
     private storageOptions: AuthStorageOptions = {},
     private runtimeSignal?: AbortSignal,
     initialState?: string,
+    authority?: OAuthAuthority,
   ) {
+    this.assertAuthority = authority ?? captureOAuthAuthority(serverName)
+    this.assertAuthority()
+    if (config.clientId === undefined && config.clientMetadataUrl !== undefined) {
+      this.clientMetadataUrl = config.clientMetadataUrl
+    }
+    this.authFetch = createOAuthFetch(serverUrl, undefined, runtimeSignal)
     this.flowState = initialState
     this.redirectUrlSnapshot = config.grantType === "client_credentials"
       ? undefined
       : config.redirectUri ?? `http://localhost:${getOAuthCallbackPort()}${getOAuthCallbackPath()}`
   }
 
+  setAuthFetch(fetchFn: OAuthFetch): void {
+    this.authFetch = fetchFn
+  }
+
   private get usesClientCredentials(): boolean {
     return this.config.grantType === "client_credentials"
   }
@@ -288,6 +307,7 @@ export class McpOAuthProvider implements OAuthClientProvider {
     this.active = false
     this.invalidatedAccessToken = undefined
     this.invalidatedClientId = undefined
+    this.staleRedirectClientId = undefined
     this.lastObservedClientId = undefined
     this.lastSavedAccessToken = undefined
     this.pendingAuthAccessToken = undefined
@@ -313,7 +333,11 @@ export class McpOAuthProvider implements OAuthClientProvider {
 
   private throwIfInactive(): void {
     if (!this.active) throw new Error("OAuth flow is no longer active")
+    this.assertAuthority()
     this.runtimeSignal?.throwIfAborted()
+    // The SDK can swallow refresh fetch errors and attempt browser authorization.
+    // A failed service credential must stop that fallback and token persistence.
+    this.authFetch.throwIfHeaderResolutionFailed()
   }
 
   /**
@@ -367,11 +391,13 @@ export class McpOAuthProvider implements OAuthClientProvider {
    * Returns undefined if no client info exists or if the server URL has changed.
    */
   async clientInformation(): Promise<OAuthClientInformationMixed | undefined> {
+    this.throwIfInactive()
     if (this.invalidatedClientId !== undefined) {
       invalidateAuthEntryCache(this.serverName)
     }
     const issuer = this.discoveredIssuer
     const stored = await getAuthForUrl(this.serverName, this.serverUrl, this.storageOptions)
+    this.throwIfInactive()
     this.assertStoredIssuerBindings(stored, issuer)
 
     // Check config first (pre-registered client). Store only its issuer binding.
@@ -381,6 +407,7 @@ export class McpOAuthProvider implements OAuthClientProvider {
         ? stored.clientInfo
         : undefined
       if (issuer && (storedClient?.issuer !== issuer || storedClient.configPreRegistered !== true)) {
+        this.throwIfInactive()
         updateClientInfo(
           this.serverName,
           { clientId: this.config.clientId, issuer, configPreRegistered: true },
@@ -405,6 +432,22 @@ export class McpOAuthProvider implements OAuthClientProvider {
     // another runtime writes the shared persistent entry for the same name.
     const clientInfo = this.flowClientInfo ?? stored?.clientInfo
     if (clientInfo?.clientId === this.invalidatedClientId) return undefined
+
+    const clientMetadataUrl = this.clientMetadataUrl
+    const supportsClientMetadataDocument = this.flowDiscoveryState
+      ?.authorizationServerMetadata?.client_id_metadata_document_supported
+    if (clientMetadataUrl !== undefined && supportsClientMetadataDocument !== undefined) {
+      if (supportsClientMetadataDocument === true
+        && clientInfo?.clientId !== clientMetadataUrl
+        && (stored?.tokens?.refreshToken === undefined || this.invalidatedAccessToken !== undefined)) {
+        // With no DCR refresh pair to preserve, let the SDK select CIMD now.
+        return undefined
+      }
+      if (supportsClientMetadataDocument !== true && clientInfo?.clientId === clientMetadataUrl) {
+        return undefined
+      }
+    }
+
     if (clientInfo) {
       this.invalidatedClientId = undefined
       // A stored SEP-2352 issuer stub for a config-pre-registered client
@@ -415,12 +458,14 @@ export class McpOAuthProvider implements OAuthClientProvider {
       // would let a token refresh go out with a client_id but no secret,
       // causing invalid_client and credential invalidation. Return undefined
       // so callers treat this as "no client info".
+      const isConfiguredCimd = clientMetadataUrl !== undefined
+        && clientInfo.clientId === clientMetadataUrl
       const isConfigStub = clientInfo.configPreRegistered === true
         || (clientInfo.clientSecret === undefined
           && clientInfo.clientIdIssuedAt === undefined
           && clientInfo.clientSecretExpiresAt === undefined
           && clientInfo.redirectUris === undefined)
-      if (isConfigStub) {
+      if (isConfigStub && !isConfiguredCimd) {
         return undefined
       }
       // Check if client secret has expired
@@ -433,8 +478,16 @@ export class McpOAuthProvider implements OAuthClientProvider {
       if (issuer && clientInfo.issuer === undefined) {
         clientInfo.issuer = issuer
         this.flowClientInfo = clientInfo
+        this.throwIfInactive()
         updateClientInfo(this.serverName, clientInfo, this.serverUrl, this.storageOptions)
       }
+      // Keep a stale dynamic registration available for its refresh attempt,
+      // but suppress it if that attempt invalidates the token and auth falls
+      // back to an interactive flow. The next clientInformation() call then
+      // makes the SDK register the current callback URI.
+      const redirectUriIsStale = this.redirectUrl !== undefined
+        && (!Array.isArray(clientInfo.redirectUris) || !clientInfo.redirectUris.includes(this.redirectUrl))
+      this.staleRedirectClientId = redirectUriIsStale ? clientInfo.clientId : undefined
       // Return all registration metadata and the local issuer extension.
       // This keeps the SDK OAuth view and the stored issuer binding consistent.
       this.lastObservedClientId = clientInfo.clientId
@@ -499,6 +552,7 @@ export class McpOAuthProvider implements OAuthClientProvider {
    * Returns undefined if no tokens exist or if the server URL has changed.
    */
   async tokens(ctx?: OAuthClientInformationContext): Promise<OAuthTokens | undefined> {
+    this.throwIfInactive()
     // Once this provider rejects a token, bypass its process-local cache until
     // another process replaces that token in shared secure storage.
     if (this.invalidatedAccessToken !== undefined) {
@@ -507,12 +561,14 @@ export class McpOAuthProvider implements OAuthClientProvider {
 
     // Use getAuthForUrl to validate tokens are for the current server URL.
     const entry = await getAuthForUrl(this.serverName, this.serverUrl, this.storageOptions)
+    this.throwIfInactive()
     if (!entry?.tokens || entry.tokens.accessToken === this.invalidatedAccessToken) return undefined
     this.invalidatedAccessToken = undefined
     const issuer = this.discoveredIssuer
     this.assertStoredIssuerBindings(entry, issuer)
     if (issuer && entry.tokens.issuer === undefined) {
       entry.tokens.issuer = issuer
+      this.throwIfInactive()
       updateTokens(this.serverName, entry.tokens, this.serverUrl, this.storageOptions)
     }
     if (ctx !== undefined) {
@@ -607,16 +663,20 @@ export class McpOAuthProvider implements OAuthClientProvider {
   async discoveryState(): Promise<OAuthDiscoveryState | undefined> {
     this.throwIfInactive()
     if (!this.flowDiscoveryState && this.config.authServerMetadataUrl !== undefined) {
-      this.flowDiscoveryState = await loadConfiguredDiscoveryState(
+      const discoveryState = await loadConfiguredDiscoveryState(
         this.config.authServerMetadataUrl,
         this.serverUrl,
         this.config.skipIssuerMetadataValidation === true,
-        this.runtimeSignal,
+        this.authFetch,
       )
+      this.throwIfInactive()
+      this.flowDiscoveryState = discoveryState
     }
+    this.throwIfInactive()
     return this.flowDiscoveryState ? structuredClone(this.flowDiscoveryState) : undefined
   }
 
+  /** Internal connection-attempt identity check for manager cleanup. */
   /**
    * Save the OAuth state parameter for CSRF protection.
    */
@@ -657,6 +717,7 @@ export class McpOAuthProvider implements OAuthClientProvider {
         this.flowState = undefined
         this.invalidatedAccessToken = undefined
         this.invalidatedClientId = undefined
+        this.staleRedirectClientId = undefined
         this.lastObservedClientId = undefined
         this.lastSavedAccessToken = undefined
         this.pendingAuthAccessToken = undefined
@@ -679,6 +740,9 @@ export class McpOAuthProvider implements OAuthClientProvider {
         this.invalidatedAccessToken = this.pendingAuthAccessToken ?? this.lastSavedAccessToken
         this.lastSavedAccessToken = undefined
         this.pendingAuthAccessToken = undefined
+        if (this.staleRedirectClientId !== undefined) {
+          this.invalidatedClientId = this.staleRedirectClientId
+        }
         invalidateAuthEntryCache(this.serverName)
         break
       case "verifier":

package/dist/humain/mcp-adapter/vendor/mcp-output-guard.ts

@@ -2,10 +2,17 @@ import { randomBytes } from "node:crypto";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  formatSize,
+  truncateHead,
+  type TruncationResult,
+} from "../../../core/tools/truncate.ts";
 import type { ContentBlock, McpSettings } from "./types.ts";
 
-export const DEFAULT_MCP_OUTPUT_MAX_BYTES = 50 * 1024;
-export const DEFAULT_MCP_OUTPUT_MAX_LINES = 2000;
+export const DEFAULT_MCP_OUTPUT_MAX_BYTES = DEFAULT_MAX_BYTES;
+export const DEFAULT_MCP_OUTPUT_MAX_LINES = DEFAULT_MAX_LINES;
 export const DEFAULT_MCP_DETAILS_MAX_BYTES = 16 * 1024;
 
 const CONTENT_SUMMARY_LIMIT = 20;
@@ -22,6 +29,16 @@ export interface McpOutputGuardDetails {
   returnedBytes: number;
   originalLines: number;
   returnedLines: number;
+  /** Host truncation classification and preview counts for the composed text before the MCP notice is added. */
+  truncatedBy: TruncationResult["truncatedBy"];
+  totalLines: number;
+  totalBytes: number;
+  outputLines: number;
+  outputBytes: number;
+  lastLinePartial: boolean;
+  firstLineExceedsLimit: boolean;
+  maxLines: number;
+  maxBytes: number;
   /** Number of image content blocks returned untouched alongside the truncated text. */
   imageBlocksPassedThrough?: number;
   fullOutputPath?: string;
@@ -119,26 +136,43 @@ export async function guardMcpOutput(
     .map((block) => (block as { text: string }).text)
     .join("\n");
   const composedOutput = `${prefix}${textOutput}${suffix}`;
-  const stats = textStats(composedOutput);
+  const truncation = truncateHead(composedOutput, { maxBytes, maxLines });
 
   let guardedContent: ContentBlock[] = addAffixes(normalizedContent, prefix, suffix);
   let outputGuard: McpOutputGuardDetails | undefined;
 
-  if (stats.bytes > maxBytes || stats.lines > maxLines) {
+  if (truncation.truncated) {
     const { path: fullOutputPath, error: writeError } = await saveArtifact("output", composedOutput);
-    const notice = formatTruncationNotice(stats, fullOutputPath, writeError);
-    const previewBudget = reserveBudget(maxBytes, maxLines, notice);
-    const preview = truncateHead(composedOutput, previewBudget.maxBytes, previewBudget.maxLines);
+    const initialNotice = formatTruncationNotice(truncation, fullOutputPath, writeError);
+    const previewBudget = reserveBudget(maxBytes, maxLines, initialNotice);
+    const preview = truncateHead(composedOutput, {
+      maxBytes: previewBudget.maxBytes,
+      maxLines: previewBudget.maxLines,
+    });
+    const notice = formatTruncationNotice(
+      { ...truncation, outputLines: preview.outputLines, outputBytes: preview.outputBytes },
+      fullOutputPath,
+      writeError,
+    );
     const finalText = `${preview.content}\n\n${notice}`;
     const finalStats = textStats(finalText);
 
     guardedContent = [{ type: "text" as const, text: finalText }, ...imageBlocks];
     outputGuard = {
       truncated: true,
-      originalBytes: stats.bytes,
+      originalBytes: truncation.totalBytes,
       returnedBytes: finalStats.bytes,
-      originalLines: stats.lines,
+      originalLines: truncation.totalLines,
       returnedLines: finalStats.lines,
+      truncatedBy: truncation.truncatedBy,
+      totalLines: truncation.totalLines,
+      totalBytes: truncation.totalBytes,
+      outputLines: preview.outputLines,
+      outputBytes: preview.outputBytes,
+      lastLinePartial: truncation.lastLinePartial,
+      firstLineExceedsLimit: truncation.firstLineExceedsLimit,
+      maxLines: truncation.maxLines,
+      maxBytes: truncation.maxBytes,
       ...(imageBlocks.length > 0 ? { imageBlocksPassedThrough: imageBlocks.length } : {}),
       ...(fullOutputPath !== undefined ? { fullOutputPath } : {}),
       ...(writeError !== undefined ? { writeError } : {}),
@@ -217,31 +251,6 @@ function reserveBudget(maxBytes: number, maxLines: number, notice: string): { ma
   };
 }
 
-function truncateHead(text: string, maxBytes: number, maxLines: number): { content: string; bytes: number; lines: number } {
-  const lines = text.split("\n");
-  const output: string[] = [];
-  let bytes = 0;
-
-  for (const line of lines) {
-    if (output.length >= maxLines) break;
-    const separatorBytes = output.length > 0 ? 1 : 0;
-    const lineBytes = byteLength(line);
-    if (bytes + separatorBytes + lineBytes > maxBytes) {
-      const remaining = maxBytes - bytes - separatorBytes;
-      if (remaining > 0) {
-        output.push(truncateStringToBytes(line, remaining));
-      }
-      break;
-    }
-    output.push(line);
-    bytes += separatorBytes + lineBytes;
-  }
-
-  const content = output.join("\n");
-  const stats = textStats(content);
-  return { content, bytes: stats.bytes, lines: stats.lines };
-}
-
 function truncateStringToBytes(value: string, maxBytes: number): string {
   if (byteLength(value) <= maxBytes) return value;
   const buffer = Buffer.from(value, "utf8");
@@ -251,11 +260,19 @@ function truncateStringToBytes(value: string, maxBytes: number): string {
 }
 
 function formatTruncationNotice(
-  stats: { bytes: number; lines: number },
+  truncation: TruncationResult,
   fullOutputPath: string | undefined,
   writeError: string | undefined,
 ): string {
-  const base = `[MCP text output truncated: original ${stats.lines.toLocaleString()} lines / ${formatSize(stats.bytes)}.`;
+  let reason: string;
+  if (truncation.firstLineExceedsLimit) {
+    reason = `First line exceeds ${formatSize(truncation.maxBytes)} limit`;
+  } else if (truncation.truncatedBy === "lines") {
+    reason = `Truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines (${truncation.maxLines} line limit)`;
+  } else {
+    reason = `Truncated: ${truncation.outputLines} lines shown (${formatSize(truncation.maxBytes)} limit)`;
+  }
+  const base = `[MCP text output truncated: original ${truncation.totalLines.toLocaleString()} lines / ${formatSize(truncation.totalBytes)}. ${reason}.`;
   if (fullOutputPath) {
     return `${base} Full text saved to: ${fullOutputPath} — use read with offset/limit or grep to inspect.]`;
   }
@@ -488,9 +505,3 @@ function envKillSwitch(name: string): boolean | undefined {
   if (["1", "true", "yes", "on"].includes(value)) return true;
   return undefined;
 }
-
-function formatSize(bytes: number): string {
-  if (bytes < 1024) return `${bytes} B`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KiB`;
-  return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
-}