ummaya 0.2.3 → 0.2.5

package/tui/src/tools/BashTool/resultLoader.ts

@@ -0,0 +1,29 @@
+import { createRequire } from 'node:module'
+import type { ToolResultBlockParam } from '@anthropic-ai/sdk/resources/index.mjs'
+import type { Out } from './schemas.js'
+
+type BashResultRuntime = {
+  readonly mapBashToolResultToBlock: (
+    output: Out,
+    toolUseID: string,
+  ) => ToolResultBlockParam
+}
+
+const requireModule = createRequire(import.meta.url)
+let cachedRuntime: BashResultRuntime | undefined
+
+function isBashResultRuntime(value: unknown): value is BashResultRuntime {
+  if (typeof value !== 'object' || value === null) return false
+  const module = value as Partial<Record<keyof BashResultRuntime, unknown>>
+  return typeof module.mapBashToolResultToBlock === 'function'
+}
+
+export function loadBashResultRuntime(): BashResultRuntime {
+  if (cachedRuntime !== undefined) return cachedRuntime
+  const loaded: unknown = requireModule('./resultMapping.js')
+  if (!isBashResultRuntime(loaded)) {
+    throw new Error('Bash result module did not expose expected mapper')
+  }
+  cachedRuntime = loaded
+  return loaded
+}

package/tui/src/tools/BashTool/resultMapping.ts

@@ -0,0 +1,83 @@
+import type { ToolResultBlockParam } from '@anthropic-ai/sdk/resources/index.mjs';
+import { getTaskOutputPath } from '../../utils/task/diskOutput.js';
+import { buildLargeToolResultMessage, generatePreview, PREVIEW_SIZE_BYTES } from '../../utils/toolResultStorage.js';
+import { buildImageToolResult } from './shellOutputUtils.js';
+import type { Out } from './schemas.js';
+
+const EOL = '\n';
+const ASSISTANT_BLOCKING_BUDGET_MS = 15_000;
+
+export function mapBashToolResultToBlock({
+  interrupted,
+  stdout,
+  stderr,
+  isImage,
+  backgroundTaskId,
+  backgroundedByUser,
+  assistantAutoBackgrounded,
+  structuredContent,
+  persistedOutputPath,
+  persistedOutputSize
+}: Out, toolUseID: string): ToolResultBlockParam {
+  if (structuredContent && structuredContent.length > 0) {
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content: structuredContent
+    };
+  }
+  if (isImage) {
+    const block = buildImageToolResult(stdout, toolUseID);
+    if (block) return block;
+  }
+  let processedStdout = stdout;
+  if (stdout) {
+    processedStdout = stdout.replace(/^(\s*\n)+/, '').trimEnd();
+  }
+  if (persistedOutputPath) {
+    const preview = generatePreview(processedStdout, PREVIEW_SIZE_BYTES);
+    processedStdout = buildLargeToolResultMessage({
+      filepath: persistedOutputPath,
+      originalSize: persistedOutputSize ?? 0,
+      isJson: false,
+      preview: preview.preview,
+      hasMore: preview.hasMore
+    });
+  }
+  let errorMessage = stderr.trim();
+  if (interrupted) {
+    if (stderr) errorMessage += EOL;
+    errorMessage += '<error>Command was aborted before completion</error>';
+  }
+  const backgroundInfo = formatBackgroundInfo({
+    backgroundTaskId,
+    backgroundedByUser,
+    assistantAutoBackgrounded
+  });
+  return {
+    tool_use_id: toolUseID,
+    type: 'tool_result',
+    content: [processedStdout, errorMessage, backgroundInfo].filter(Boolean).join('\n'),
+    is_error: interrupted
+  };
+}
+
+type BackgroundInfoInput = Pick<Out, 'backgroundTaskId' | 'backgroundedByUser' | 'assistantAutoBackgrounded'>;
+
+function formatBackgroundInfo({
+  backgroundTaskId,
+  backgroundedByUser,
+  assistantAutoBackgrounded
+}: BackgroundInfoInput): string {
+  if (!backgroundTaskId) {
+    return '';
+  }
+  const outputPath = getTaskOutputPath(backgroundTaskId);
+  if (assistantAutoBackgrounded) {
+    return `Command exceeded the assistant-mode blocking budget (${ASSISTANT_BLOCKING_BUDGET_MS / 1000}s) and was moved to the background with ID: ${backgroundTaskId}. It is still running — you will be notified when it completes. Output is being written to: ${outputPath}. In assistant mode, delegate long-running work to a subagent or use run_in_background to keep this conversation responsive.`;
+  }
+  if (backgroundedByUser) {
+    return `Command was manually backgrounded by user with ID: ${backgroundTaskId}. Output is being written to: ${outputPath}`;
+  }
+  return `Command running in background with ID: ${backgroundTaskId}. Output is being written to: ${outputPath}`;
+}

package/tui/src/tools/BashTool/sandboxPolicy.ts

@@ -0,0 +1,79 @@
+import { createRequire } from 'node:module'
+
+type SandboxInput = {
+  readonly command?: string
+  readonly dangerouslyDisableSandbox?: boolean
+}
+
+type ShouldUseSandbox = (input: SandboxInput) => boolean
+type ShellSandboxManager = {
+  readonly annotateStderrWithSandboxFailures: (
+    command: string,
+    stderr: string,
+  ) => string
+  readonly isSandboxEnabledInSettings: () => boolean
+  readonly areUnsandboxedCommandsAllowed: () => boolean
+}
+
+const requireModule = createRequire(import.meta.url)
+let cachedShouldUseSandbox: ShouldUseSandbox | undefined
+let cachedSandboxManager: ShellSandboxManager | undefined
+
+function isSandboxModule(
+  value: unknown,
+): value is { readonly shouldUseSandbox: ShouldUseSandbox } {
+  if (typeof value !== 'object' || value === null) return false
+  const module = value as { readonly shouldUseSandbox?: unknown }
+  return typeof module.shouldUseSandbox === 'function'
+}
+
+export function shouldUseSandboxForShell(input: SandboxInput): boolean {
+  if (cachedShouldUseSandbox !== undefined) return cachedShouldUseSandbox(input)
+  const loaded: unknown = requireModule('./shouldUseSandbox.js')
+  if (!isSandboxModule(loaded)) {
+    throw new Error('Bash sandbox policy module did not expose shouldUseSandbox')
+  }
+  cachedShouldUseSandbox = loaded.shouldUseSandbox
+  return loaded.shouldUseSandbox(input)
+}
+
+function isSandboxAdapterModule(
+  value: unknown,
+): value is { readonly SandboxManager: ShellSandboxManager } {
+  if (typeof value !== 'object' || value === null) return false
+  const module = value as { readonly SandboxManager?: unknown }
+  if (typeof module.SandboxManager !== 'object' || module.SandboxManager === null) {
+    return false
+  }
+  const manager = module.SandboxManager as Partial<ShellSandboxManager>
+  return (
+    typeof manager.annotateStderrWithSandboxFailures === 'function' &&
+    typeof manager.isSandboxEnabledInSettings === 'function' &&
+    typeof manager.areUnsandboxedCommandsAllowed === 'function'
+  )
+}
+
+function loadSandboxManager(): ShellSandboxManager {
+  if (cachedSandboxManager !== undefined) return cachedSandboxManager
+  const loaded: unknown = requireModule('../../utils/sandbox/sandbox-adapter.js')
+  if (!isSandboxAdapterModule(loaded)) {
+    throw new Error('Sandbox adapter module did not expose SandboxManager')
+  }
+  cachedSandboxManager = loaded.SandboxManager
+  return loaded.SandboxManager
+}
+
+export function annotateShellStderrWithSandboxFailures(
+  command: string,
+  stderr: string,
+): string {
+  return loadSandboxManager().annotateStderrWithSandboxFailures(command, stderr)
+}
+
+export function isShellSandboxEnabledInSettings(): boolean {
+  return loadSandboxManager().isSandboxEnabledInSettings()
+}
+
+export function areUnsandboxedShellCommandsAllowed(): boolean {
+  return loadSandboxManager().areUnsandboxedCommandsAllowed()
+}

package/tui/src/tools/BashTool/schemas.ts

@@ -0,0 +1,65 @@
+import type { ToolResultBlockParam } from '@anthropic-ai/sdk/resources/index.mjs';
+import { z } from 'zod/v4';
+import { isEnvTruthy } from '../../utils/envUtils.js';
+import { lazySchema } from '../../utils/lazySchema.js';
+import { semanticBoolean } from '../../utils/semanticBoolean.js';
+import { semanticNumber } from '../../utils/semanticNumber.js';
+import { getMaxBashTimeoutMs } from '../../utils/timeouts.js';
+
+export const isBackgroundTasksDisabled =
+  // eslint-disable-next-line custom-rules/no-process-env-top-level -- Intentional: schema must be defined at module load
+  isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_BACKGROUND_TASKS);
+
+export const fullInputSchema = lazySchema(() => z.strictObject({
+  command: z.string().describe('The command to execute'),
+  timeout: semanticNumber(z.number().optional()).describe(`Optional timeout in milliseconds (max ${getMaxBashTimeoutMs()})`),
+  description: z.string().optional().describe(`Clear, concise description of what this command does in active voice. Never use words like "complex" or "risk" in the description - just describe what it does.
+
+For simple commands (git, npm, standard CLI tools), keep it brief (5-10 words):
+- ls -> "List files in current directory"
+- git status -> "Show working tree status"
+- npm install -> "Install package dependencies"
+
+For commands that are harder to parse at a glance (piped commands, obscure flags, etc.), add enough context to clarify what it does:
+- find . -name "*.tmp" -exec rm {} \\; -> "Find and delete all .tmp files recursively"
+- git reset --hard origin/main -> "Discard all local changes and match remote main"
+- curl -s url | jq '.data[]' -> "Fetch JSON from URL and extract data array elements"`),
+  run_in_background: semanticBoolean(z.boolean().optional()).describe(`Set to true to run this command in the background. Use Read to read the output later.`),
+  dangerouslyDisableSandbox: semanticBoolean(z.boolean().optional()).describe('Set this to true to dangerously override sandbox mode and run commands without sandboxing.'),
+  _simulatedSedEdit: z.object({
+    filePath: z.string(),
+    newContent: z.string()
+  }).optional().describe('Internal: pre-computed sed edit result from preview')
+}));
+
+export const inputSchema = lazySchema(() => isBackgroundTasksDisabled ? fullInputSchema().omit({
+  run_in_background: true,
+  _simulatedSedEdit: true
+}) : fullInputSchema().omit({
+  _simulatedSedEdit: true
+}));
+
+type StructuredContent = Exclude<ToolResultBlockParam['content'], string>;
+const structuredContentSchema = z.custom<StructuredContent>((value): value is StructuredContent => Array.isArray(value));
+
+export const outputSchema = lazySchema(() => z.object({
+  stdout: z.string().describe('The standard output of the command'),
+  stderr: z.string().describe('The standard error output of the command'),
+  rawOutputPath: z.string().optional().describe('Path to raw output file for large MCP tool outputs'),
+  interrupted: z.boolean().describe('Whether the command was interrupted'),
+  isImage: z.boolean().optional().describe('Flag to indicate if stdout contains image data'),
+  backgroundTaskId: z.string().optional().describe('ID of the background task if command is running in background'),
+  backgroundedByUser: z.boolean().optional().describe('True if the user manually backgrounded the command with Ctrl+B'),
+  assistantAutoBackgrounded: z.boolean().optional().describe('True if assistant-mode auto-backgrounded a long-running blocking command'),
+  dangerouslyDisableSandbox: z.boolean().optional().describe('Flag to indicate if sandbox mode was overridden'),
+  returnCodeInterpretation: z.string().optional().describe('Semantic interpretation for non-error exit codes with special meaning'),
+  noOutputExpected: z.boolean().optional().describe('Whether the command is expected to produce no output on success'),
+  structuredContent: structuredContentSchema.optional().describe('Structured content blocks'),
+  persistedOutputPath: z.string().optional().describe('Path to the persisted full output in tool-results dir (set when output is too large for inline)'),
+  persistedOutputSize: z.number().optional().describe('Total size of the output in bytes (set when output is too large for inline)')
+}));
+
+export type InputSchema = ReturnType<typeof inputSchema>;
+export type BashToolInput = z.infer<ReturnType<typeof fullInputSchema>>;
+export type OutputSchema = ReturnType<typeof outputSchema>;
+export type Out = z.infer<OutputSchema>;

package/tui/src/tools/BashTool/sedEditExecution.ts

@@ -0,0 +1,59 @@
+import { notifyVscodeFileUpdated } from '../../services/mcp/vscodeSdkMcp.js';
+import type { ToolUseContext } from '../../Tool.js';
+import type { AssistantMessage } from '../../types/message.js';
+import { isENOENT } from '../../utils/errors.js';
+import { detectFileEncoding, detectLineEndings, getFileModificationTime, writeTextContent } from '../../utils/file.js';
+import { fileHistoryEnabled, fileHistoryTrackEdit } from '../../utils/fileHistory.js';
+import { getFsImplementation } from '../../utils/fsOperations.js';
+import { expandPath } from '../../utils/path.js';
+import type { Out } from './schemas.js';
+
+type SimulatedSedEditResult = {
+  readonly data: Out;
+};
+
+type SimulatedSedEditContext = Pick<ToolUseContext, 'readFileState' | 'updateFileHistoryState'>;
+
+export async function applySedEdit(simulatedEdit: {
+  readonly filePath: string;
+  readonly newContent: string;
+}, toolUseContext: SimulatedSedEditContext, parentMessage?: AssistantMessage): Promise<SimulatedSedEditResult> {
+  const { filePath, newContent } = simulatedEdit;
+  const absoluteFilePath = expandPath(filePath);
+  const fs = getFsImplementation();
+  const encoding = detectFileEncoding(absoluteFilePath);
+  let originalContent: string;
+  try {
+    originalContent = await fs.readFile(absoluteFilePath, { encoding });
+  } catch (error) {
+    if (isENOENT(error)) {
+      return {
+        data: {
+          stdout: '',
+          stderr: `sed: ${filePath}: No such file or directory\nExit code 1`,
+          interrupted: false
+        }
+      };
+    }
+    throw error;
+  }
+  if (fileHistoryEnabled() && parentMessage) {
+    await fileHistoryTrackEdit(toolUseContext.updateFileHistoryState, absoluteFilePath, parentMessage.uuid);
+  }
+  const endings = detectLineEndings(absoluteFilePath);
+  writeTextContent(absoluteFilePath, newContent, encoding, endings);
+  notifyVscodeFileUpdated(absoluteFilePath, originalContent, newContent);
+  toolUseContext.readFileState.set(absoluteFilePath, {
+    content: newContent,
+    timestamp: getFileModificationTime(absoluteFilePath),
+    offset: undefined,
+    limit: undefined
+  });
+  return {
+    data: {
+      stdout: '',
+      stderr: '',
+      interrupted: false
+    }
+  };
+}

package/tui/src/tools/BashTool/shellExecution.tsx

@@ -0,0 +1,245 @@
+import { feature } from 'bun:bundle';
+import * as React from 'react';
+import type { SetToolJSXFn } from '../../Tool.js';
+import { backgroundExistingForegroundTask, markTaskNotified, registerForeground, spawnShellTask, unregisterForeground } from '../../tasks/LocalShellTask/LocalShellTask.js';
+import type { AgentId } from '../../types/ids.js';
+import type { AppState } from '../../state/AppState.js';
+import { getKairosActive } from '../../bootstrap/state.js';
+import { logEvent } from '../../services/analytics/index.js';
+import { exec } from '../../utils/Shell.js';
+import type { ExecResult } from '../../utils/ShellCommand.js';
+import { TaskOutput } from '../../utils/task/TaskOutput.js';
+import { getDefaultTimeoutMs } from './prompt.js';
+import { shouldUseSandboxForShell } from './sandboxPolicy.js';
+import type { BashToolInput } from './schemas.js';
+import { isBackgroundTasksDisabled } from './schemas.js';
+import { getCommandTypeForLogging, isAutobackgroundingAllowed } from './commandClassification.js';
+import { loadBashUI } from './uiLoader.js';
+
+const PROGRESS_THRESHOLD_MS = 2000;
+const ASSISTANT_BLOCKING_BUDGET_MS = 15_000;
+
+export type BashExecutionProgress = {
+  readonly type: 'progress'; readonly output: string; readonly fullOutput: string;
+  readonly elapsedTimeSeconds: number; readonly totalLines: number;
+  readonly totalBytes?: number; readonly taskId?: string; readonly timeoutMs?: number;
+};
+
+type RunShellCommandInput = {
+  readonly input: BashToolInput; readonly abortController: AbortController;
+  readonly setAppState: (f: (prev: AppState) => AppState) => void;
+  readonly setToolJSX?: SetToolJSXFn; readonly preventCwdChanges?: boolean;
+  readonly isMainThread?: boolean; readonly toolUseId?: string; readonly agentId?: AgentId;
+};
+
+export async function* runShellCommand({
+  input,
+  abortController,
+  setAppState,
+  setToolJSX,
+  preventCwdChanges,
+  isMainThread,
+  toolUseId,
+  agentId
+}: RunShellCommandInput): AsyncGenerator<BashExecutionProgress, ExecResult, void> {
+  const { command, description, timeout, run_in_background } = input;
+  const timeoutMs = timeout || getDefaultTimeoutMs();
+  let fullOutput = '';
+  let lastProgressOutput = '';
+  let lastTotalLines = 0;
+  let lastTotalBytes = 0;
+  let backgroundShellId: string | undefined = undefined;
+  let assistantAutoBackgrounded = false;
+  let resolveProgress: (() => void) | null = null;
+  function createProgressSignal(): Promise<null> {
+    return new Promise<null>(resolve => {
+      resolveProgress = () => resolve(null);
+    });
+  }
+  const shouldAutoBackground = !isBackgroundTasksDisabled && isAutobackgroundingAllowed(command);
+  const shellCommand = await exec(command, abortController.signal, 'bash', {
+    timeout: timeoutMs,
+    onProgress(lastLines, allLines, totalLines, totalBytes, isIncomplete) {
+      lastProgressOutput = lastLines;
+      fullOutput = allLines;
+      lastTotalLines = totalLines;
+      lastTotalBytes = isIncomplete ? totalBytes : 0;
+      const resolve = resolveProgress;
+      if (resolve) {
+        resolveProgress = null;
+        resolve();
+      }
+    },
+    preventCwdChanges,
+    shouldUseSandbox: shouldUseSandboxForShell(input),
+    shouldAutoBackground
+  });
+  const resultPromise = shellCommand.result;
+  async function spawnBackgroundTask(): Promise<string> {
+    const handle = await spawnShellTask({
+      command,
+      description: description || command,
+      shellCommand,
+      toolUseId,
+      agentId
+    }, {
+      abortController,
+      getAppState: () => {
+        throw new Error('getAppState not available in runShellCommand context');
+      },
+      setAppState
+    });
+    return handle.taskId;
+  }
+  function startBackgrounding(eventName: string, backgroundFn?: (shellId: string) => void): void {
+    if (foregroundTaskId) {
+      if (!backgroundExistingForegroundTask(foregroundTaskId, shellCommand, description || command, setAppState, toolUseId)) {
+        return;
+      }
+      backgroundShellId = foregroundTaskId;
+      logEvent(eventName, {
+        command_type: getCommandTypeForLogging(command)
+      });
+      backgroundFn?.(foregroundTaskId);
+      return;
+    }
+    void spawnBackgroundTask().then(shellId => {
+      backgroundShellId = shellId;
+      const resolve = resolveProgress;
+      if (resolve) {
+        resolveProgress = null;
+        resolve();
+      }
+      logEvent(eventName, {
+        command_type: getCommandTypeForLogging(command)
+      });
+      if (backgroundFn) {
+        backgroundFn(shellId);
+      }
+    });
+  }
+  if (shellCommand.onTimeout && shouldAutoBackground) {
+    shellCommand.onTimeout(backgroundFn => {
+      startBackgrounding('tengu_bash_command_timeout_backgrounded', backgroundFn);
+    });
+  }
+  if (feature('KAIROS') && getKairosActive() && isMainThread && !isBackgroundTasksDisabled && run_in_background !== true) {
+    setTimeout(() => {
+      if (shellCommand.status === 'running' && backgroundShellId === undefined) {
+        assistantAutoBackgrounded = true;
+        startBackgrounding('tengu_bash_command_assistant_auto_backgrounded');
+      }
+    }, ASSISTANT_BLOCKING_BUDGET_MS).unref();
+  }
+  if (run_in_background === true && !isBackgroundTasksDisabled) {
+    const shellId = await spawnBackgroundTask();
+    logEvent('tengu_bash_command_explicitly_backgrounded', {
+      command_type: getCommandTypeForLogging(command)
+    });
+    return {
+      stdout: '',
+      stderr: '',
+      code: 0,
+      interrupted: false,
+      backgroundTaskId: shellId
+    };
+  }
+  const startTime = Date.now();
+  let foregroundTaskId: string | undefined = undefined;
+  {
+    const initialResult = await Promise.race([resultPromise, new Promise<null>(resolve => {
+      const timer = setTimeout((done: (value: null) => void) => done(null), PROGRESS_THRESHOLD_MS, resolve);
+      timer.unref();
+    })]);
+    if (initialResult !== null) {
+      shellCommand.cleanup();
+      return initialResult;
+    }
+    if (backgroundShellId) {
+      return {
+        stdout: '',
+        stderr: '',
+        code: 0,
+        interrupted: false,
+        backgroundTaskId: backgroundShellId,
+        assistantAutoBackgrounded
+      };
+    }
+  }
+  TaskOutput.startPolling(shellCommand.taskOutput.taskId);
+  try {
+    while (true) {
+      const progressSignal = createProgressSignal();
+      const result = await Promise.race([resultPromise, progressSignal]);
+      if (result !== null) {
+        if (result.backgroundTaskId !== undefined) {
+          markTaskNotified(result.backgroundTaskId, setAppState);
+          const fixedResult: ExecResult = { ...result, backgroundTaskId: undefined };
+          const { taskOutput } = shellCommand;
+          if (taskOutput.stdoutToFile && !taskOutput.outputFileRedundant) {
+            fixedResult.outputFilePath = taskOutput.path;
+            fixedResult.outputFileSize = taskOutput.outputFileSize;
+            fixedResult.outputTaskId = taskOutput.taskId;
+          }
+          shellCommand.cleanup();
+          return fixedResult;
+        }
+        if (foregroundTaskId) {
+          unregisterForeground(foregroundTaskId, setAppState);
+        }
+        shellCommand.cleanup();
+        return result;
+      }
+      if (backgroundShellId) {
+        return {
+          stdout: '',
+          stderr: '',
+          code: 0,
+          interrupted: false,
+          backgroundTaskId: backgroundShellId,
+          assistantAutoBackgrounded
+        };
+      }
+      if (foregroundTaskId && shellCommand.status === 'backgrounded') {
+        return {
+          stdout: '',
+          stderr: '',
+          code: 0,
+          interrupted: false,
+          backgroundTaskId: foregroundTaskId,
+          backgroundedByUser: true
+        };
+      }
+      const elapsedSeconds = Math.floor((Date.now() - startTime) / 1000);
+      if (!isBackgroundTasksDisabled && backgroundShellId === undefined && elapsedSeconds >= PROGRESS_THRESHOLD_MS / 1000 && setToolJSX) {
+        if (!foregroundTaskId) {
+          foregroundTaskId = registerForeground({
+            command,
+            description: description || command,
+            shellCommand,
+            agentId
+          }, setAppState, toolUseId);
+        }
+        const { BackgroundHint } = loadBashUI();
+        setToolJSX({
+          jsx: <BackgroundHint />,
+          shouldHidePromptInput: false,
+          shouldContinueAnimation: true,
+          showSpinner: true
+        });
+      }
+      yield {
+        type: 'progress',
+        fullOutput,
+        output: lastProgressOutput,
+        elapsedTimeSeconds: elapsedSeconds,
+        totalLines: lastTotalLines,
+        totalBytes: lastTotalBytes,
+        taskId: shellCommand.taskOutput.taskId,
+        ...(timeout ? { timeoutMs } : undefined)
+      };
+    }
+  } finally {
+    TaskOutput.stopPolling(shellCommand.taskOutput.taskId);
+  }
+}

package/tui/src/tools/BashTool/shellOutputUtils.ts

@@ -0,0 +1,85 @@
+import type {
+  Base64ImageSource,
+  ToolResultBlockParam,
+} from '@anthropic-ai/sdk/resources/index.mjs'
+import { readFile, stat } from 'fs/promises'
+import { getOriginalCwd } from '../../bootstrap/state.js'
+import { maybeResizeAndDownsampleImageBuffer } from '../../utils/imageResizer.js'
+
+export function stripEmptyLines(content: string): string {
+  const lines = content.split('\n')
+  let startIndex = 0
+  while (startIndex < lines.length && lines[startIndex]?.trim() === '') {
+    startIndex++
+  }
+  let endIndex = lines.length - 1
+  while (endIndex >= 0 && lines[endIndex]?.trim() === '') {
+    endIndex--
+  }
+  if (startIndex > endIndex) return ''
+  return lines.slice(startIndex, endIndex + 1).join('\n')
+}
+
+export function isImageOutput(content: string): boolean {
+  return /^data:image\/[a-z0-9.+_-]+;base64,/i.test(content)
+}
+
+const DATA_URI_RE = /^data:([^;]+);base64,(.+)$/
+
+function parseDataUri(
+  value: string,
+): { readonly mediaType: string; readonly data: string } | null {
+  const match = value.trim().match(DATA_URI_RE)
+  if (!match || !match[1] || !match[2]) return null
+  return { mediaType: match[1], data: match[2] }
+}
+
+export function buildImageToolResult(
+  stdout: string,
+  toolUseID: string,
+): ToolResultBlockParam | null {
+  const parsed = parseDataUri(stdout)
+  if (!parsed) return null
+  return {
+    tool_use_id: toolUseID,
+    type: 'tool_result',
+    content: [
+      {
+        type: 'image',
+        source: {
+          type: 'base64',
+          media_type: parsed.mediaType as Base64ImageSource['media_type'],
+          data: parsed.data,
+        },
+      },
+    ],
+  }
+}
+
+const MAX_IMAGE_FILE_SIZE = 20 * 1024 * 1024
+
+export async function resizeShellImageOutput(
+  stdout: string,
+  outputFilePath: string | undefined,
+  outputFileSize: number | undefined,
+): Promise<string | null> {
+  let source = stdout
+  if (outputFilePath) {
+    const size = outputFileSize ?? (await stat(outputFilePath)).size
+    if (size > MAX_IMAGE_FILE_SIZE) return null
+    source = await readFile(outputFilePath, 'utf8')
+  }
+  const parsed = parseDataUri(source)
+  if (!parsed) return null
+  const buffer = Buffer.from(parsed.data, 'base64')
+  const extension = parsed.mediaType.split('/')[1] || 'png'
+  const resized = await maybeResizeAndDownsampleImageBuffer(
+    buffer,
+    buffer.length,
+    extension,
+  )
+  return `data:image/${resized.mediaType};base64,${resized.buffer.toString('base64')}`
+}
+
+export const stdErrAppendShellResetMessage = (stderr: string): string =>
+  `${stderr.trim()}\nShell cwd was reset to ${getOriginalCwd()}`