@modelprofile.com/flexharness 6.0.0 → 7.0.0

package/ts_media/readme.md

@@ -0,0 +1,37 @@
+Vision recipes for a caller-supplied language model.
+
+Part of the [FlexHarness toolbox](https://code.foss.global/modelprofile.com/flexharness).
+Install the components your project uses. Provider adapters are registered explicitly;
+the agent and harness do not install or register vendor SDKs.
+
+```sh
+pnpm add @modelprofile.com/flexharness
+```
+
+See the [toolbox usage and migration guide](https://code.foss.global/modelprofile.com/flexharness#readme)
+for composition examples and the SmartAI/SmartAgent migration map.
+
+## Issue Reporting and Security
+
+Report issues and security concerns through [community.foss.global](https://community.foss.global).
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts_ocr/classes.imageocr.ts

@@ -0,0 +1,53 @@
+import {
+  createMistralOcrEngine,
+  type ISmartAiMistralOcrOptions,
+  type ISmartAiMistralOcrRecognizeOptions,
+  type ISmartAiOcrEngine,
+  type ISmartAiOcrImageInput,
+  type ISmartAiOcrResult,
+  type TSmartAiOcrImageMimeType,
+} from './ocr.mistral.js';
+
+export interface IImageOcrOptions {
+  engine?: ISmartAiOcrEngine;
+  mistralOptions?: ISmartAiMistralOcrOptions;
+}
+
+export interface IImageOcrRecognitionOptions extends IImageOcrOptions {
+  recognizeOptions?: ISmartAiMistralOcrRecognizeOptions;
+}
+
+export interface IImageOcrBytesOptions extends IImageOcrRecognitionOptions {
+  mimeType: TSmartAiOcrImageMimeType;
+}
+
+/** Image recognition without a local OCR executable or PDF dependency. */
+export class ImageOcr {
+  constructor(private readonly options: IImageOcrOptions = {}) {}
+
+  public async recognizeImage(
+    input: ISmartAiOcrImageInput,
+    options: IImageOcrRecognitionOptions = {},
+  ): Promise<ISmartAiOcrResult> {
+    const engine = options.engine ?? this.options.engine ?? createMistralOcrEngine({
+      ...this.options.mistralOptions,
+      ...options.mistralOptions,
+    });
+    return engine.recognizeImage(input, options.recognizeOptions);
+  }
+
+  /** Accepts Uint8Array, including Node Buffer, without importing Node builtins. */
+  public async recognizeImageBytes(
+    bytes: Uint8Array,
+    options: IImageOcrBytesOptions,
+  ): Promise<ISmartAiOcrResult> {
+    const chunks: string[] = [];
+    for (let offset = 0; offset < bytes.length; offset += 8192) {
+      chunks.push(String.fromCharCode(...bytes.subarray(offset, offset + 8192)));
+    }
+    return this.recognizeImage({
+      dataBase64: btoa(chunks.join('')),
+      mimeType: options.mimeType,
+    }, options);
+  }
+}

package/ts_ocr/index.ts

@@ -0,0 +1,2 @@
+export * from './ocr.mistral.js';
+export * from './classes.imageocr.js';

package/ts_ocr/ocr.mistral.ts

@@ -0,0 +1,192 @@
+export type TSmartAiOcrImageMimeType =
+  | 'image/png'
+  | 'image/jpeg'
+  | 'image/webp'
+  | 'image/gif'
+  | string;
+
+export type TSmartAiMistralOcrTableFormat = 'markdown' | 'html';
+
+export type TSmartAiMistralOcrConfidenceScoresGranularity = 'page' | 'word';
+
+export interface ISmartAiOcrImageInput {
+  dataBase64: string;
+  mimeType: TSmartAiOcrImageMimeType;
+}
+
+export interface ISmartAiOcrPageResult {
+  index: number;
+  text: string;
+  confidence?: number;
+}
+
+export interface ISmartAiOcrResult<TRaw = unknown> {
+  text: string;
+  confidence?: number;
+  pages: ISmartAiOcrPageResult[];
+  raw: TRaw;
+}
+
+export interface ISmartAiOcrEngine {
+  recognizeImage: (
+    input: ISmartAiOcrImageInput,
+    options?: ISmartAiMistralOcrRecognizeOptions
+  ) => Promise<ISmartAiOcrResult<IMistralOcrResponse>>;
+}
+
+export interface IMistralOcrPageConfidenceScores {
+  average_page_confidence_score?: number;
+  averagePageConfidenceScore?: number;
+  minimum_page_confidence_score?: number;
+  minimumPageConfidenceScore?: number;
+}
+
+export interface IMistralOcrPageResponse {
+  index: number;
+  markdown: string;
+  confidence_scores?: IMistralOcrPageConfidenceScores | null;
+  confidenceScores?: IMistralOcrPageConfidenceScores | null;
+}
+
+export interface IMistralOcrResponse {
+  pages: IMistralOcrPageResponse[];
+  model: string;
+  document_annotation?: unknown;
+  documentAnnotation?: unknown;
+  usage_info?: unknown;
+  usageInfo?: unknown;
+}
+
+export interface IMistralOcrRequest {
+  model: string;
+  document: {
+    type: 'image_url';
+    image_url: string;
+  };
+  include_image_base64?: boolean;
+  table_format?: TSmartAiMistralOcrTableFormat;
+  extract_header?: boolean;
+  extract_footer?: boolean;
+  confidence_scores_granularity?: TSmartAiMistralOcrConfidenceScoresGranularity;
+}
+
+export interface ISmartAiMistralOcrTransport {
+  process: (request: IMistralOcrRequest) => Promise<IMistralOcrResponse>;
+}
+
+export interface ISmartAiMistralOcrOptions {
+  apiKey?: string;
+  model?: string;
+  endpointUrl?: string;
+  transport?: ISmartAiMistralOcrTransport;
+  includeImageBase64?: boolean;
+  tableFormat?: TSmartAiMistralOcrTableFormat;
+  extractHeader?: boolean;
+  extractFooter?: boolean;
+  confidenceScoresGranularity?: TSmartAiMistralOcrConfidenceScoresGranularity;
+}
+
+export interface ISmartAiMistralOcrRecognizeOptions {
+  includeImageBase64?: boolean;
+  tableFormat?: TSmartAiMistralOcrTableFormat;
+  extractHeader?: boolean;
+  extractFooter?: boolean;
+  confidenceScoresGranularity?: TSmartAiMistralOcrConfidenceScoresGranularity;
+}
+
+const defaultMistralOcrModel = 'mistral-ocr-latest';
+const defaultMistralOcrEndpointUrl = 'https://api.mistral.ai/v1/ocr';
+
+const createMistralOcrHttpTransport = (options: {
+  apiKey?: string;
+  endpointUrl?: string;
+}): ISmartAiMistralOcrTransport => {
+  return {
+    process: async (request) => {
+      if (!options.apiKey) {
+        throw new Error('Mistral OCR requires an apiKey when no custom transport is provided.');
+      }
+
+      const response = await fetch(options.endpointUrl ?? defaultMistralOcrEndpointUrl, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${options.apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(request),
+      });
+
+      if (!response.ok) {
+        const errorBody = await response.text();
+        throw new Error(`Mistral OCR request failed with status ${response.status}: ${errorBody}`);
+      }
+
+      return (await response.json()) as IMistralOcrResponse;
+    },
+  };
+};
+
+const getPageConfidence = (page: IMistralOcrPageResponse): number | undefined => {
+  const confidenceScores = page.confidence_scores ?? page.confidenceScores;
+  return (
+    confidenceScores?.average_page_confidence_score ??
+    confidenceScores?.averagePageConfidenceScore
+  );
+};
+
+export const createMistralOcrEngine = (
+  options: ISmartAiMistralOcrOptions = {}
+): ISmartAiOcrEngine => {
+  const transport =
+    options.transport ??
+    createMistralOcrHttpTransport({
+      apiKey: options.apiKey,
+      endpointUrl: options.endpointUrl,
+    });
+  const model = options.model ?? defaultMistralOcrModel;
+
+  return {
+    recognizeImage: async (input, recognizeOptions = {}) => {
+      if (!input.dataBase64) {
+        throw new Error('Mistral OCR image input requires dataBase64.');
+      }
+      if (!input.mimeType) {
+        throw new Error('Mistral OCR image input requires mimeType.');
+      }
+
+      const response = await transport.process({
+        model,
+        document: {
+          type: 'image_url',
+          image_url: `data:${input.mimeType};base64,${input.dataBase64}`,
+        },
+        include_image_base64:
+          recognizeOptions.includeImageBase64 ?? options.includeImageBase64 ?? false,
+        table_format: recognizeOptions.tableFormat ?? options.tableFormat,
+        extract_header: recognizeOptions.extractHeader ?? options.extractHeader,
+        extract_footer: recognizeOptions.extractFooter ?? options.extractFooter,
+        confidence_scores_granularity:
+          recognizeOptions.confidenceScoresGranularity ?? options.confidenceScoresGranularity,
+      });
+
+      const pages = response.pages.map((page) => ({
+        index: page.index,
+        text: page.markdown,
+        confidence: getPageConfidence(page),
+      }));
+      const pageConfidences = pages
+        .map((page) => page.confidence)
+        .filter((confidence): confidence is number => typeof confidence === 'number');
+      const confidence = pageConfidences.length
+        ? pageConfidences.reduce((sum, value) => sum + value, 0) / pageConfidences.length
+        : undefined;
+
+      return {
+        text: pages.map((page) => page.text).join('\n\n').trim(),
+        confidence,
+        pages,
+        raw: response,
+      };
+    },
+  };
+};

package/ts_ocr/readme.md

@@ -0,0 +1,48 @@
+Image OCR with Mistral or an injected recognition engine. This subpath imports no runtime dependencies and works with Node buffers and browser byte arrays.
+
+Part of the [FlexHarness toolbox](https://code.foss.global/modelprofile.com/flexharness).
+Install the components your project uses. Provider adapters are registered explicitly;
+the agent and harness do not install or register vendor SDKs.
+
+```sh
+pnpm add @modelprofile.com/flexharness
+```
+
+```typescript
+import { ImageOcr } from '@modelprofile.com/flexharness/ocr';
+
+const ocr = new ImageOcr({ mistralOptions: { apiKey: process.env.MISTRAL_API_KEY } });
+const result = await ocr.recognizeImageBytes(imageBytes, { mimeType: 'image/png' });
+console.log(result.text);
+```
+
+`ImageOcr` replaces SmartOCR's `recognizeImageBufferWithSmartAi`. Pass credentials explicitly; environment lookup belongs to the caller. Browser applications should supply an authenticated server transport instead of embedding a private API key.
+
+Constructor and call options accept `engine` or `mistralOptions`. A per-call engine takes precedence over the constructor engine. Otherwise Mistral settings merge, with per-call settings taking precedence. `recognizeOptions` controls each request. `recognizeImage` accepts an existing `{ dataBase64, mimeType }` image; `createMistralOcrEngine` remains available for lower-level integrations.
+
+Model-based PDF text extraction lives in `@modelprofile.com/flexharness/documents`. Native `ocrmypdf` processing remains in `@push.rocks/smartocr`.
+
+## Issue Reporting and Security
+
+Report issues and security concerns through [community.foss.global](https://community.foss.global).
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts_tools/index.ts

@@ -0,0 +1,49 @@
+export { createBrowserTools } from './tool.browser.js';
+export {
+  acquireToolExecutionContext,
+  ToolExecutionAdapterCleanupError,
+} from '@modelprofile.com/flexharness-agent';
+export type {
+  IToolExecutionAdapter,
+  IToolExecutionAdapterRequest,
+  IToolExecutionContextLease,
+} from '@modelprofile.com/flexharness-agent';
+export type { ICreateBrowserToolsOptions } from './tool.browser.js';
+export { createFilesystemTools } from './tool.filesystem.js';
+export type { ICreateFilesystemToolsOptions } from './tool.filesystem.js';
+export { createShellTools } from './tool.shell.js';
+export type { ICreateShellToolsOptions } from './tool.shell.js';
+export type { ToolSet } from 'ai';
+export { formatShellResult, formatToolOutput } from './tool.context.js';
+export type {
+  IBrowserToolInput,
+  IShellCommand,
+  IShellFinishedResult,
+  IShellStartedResult,
+  IToolBrowserContext,
+  IToolBrowserRunOptions,
+  IToolExecutionContext,
+  IToolFilesystemContext,
+  IToolFilesystemListOptions,
+  IToolFilesystemReadOptions,
+  IToolInvocationOptions,
+  IToolJobContext,
+  IToolJobEvent,
+  IToolJobOutputEvent,
+  IToolJobHandle,
+  IToolJobRequest,
+  IToolJobState,
+  IToolPermissionRequest,
+  IToolRunOptions,
+  IToolShellContext,
+  IToolShellResult,
+  TBrowserToolAction,
+  TToolJobEvent,
+  TToolJobEventListener,
+} from './tool.context.js';
+export { InMemoryToolJobStore, ToolJobStoreConflictError } from '@modelprofile.com/flexharness-agent';
+export type { IToolJobSnapshot, IToolJobStore } from '@modelprofile.com/flexharness-agent';
+export { httpTool } from './tool.http.js';
+export { jsonTool } from './tool.json.js';
+export { truncateOutput } from './plugins.js';
+export type { ITruncateResult } from './plugins.js';

package/ts_tools/plugins.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+import { tool } from 'ai';
+import * as smartrequest from '@push.rocks/smartrequest';
+import { truncateOutput } from './utils.truncation.js';
+export { z, tool, smartrequest, truncateOutput };
+export type { ToolExecutionOptions, ToolSet } from 'ai';
+export type { ITruncateResult } from './utils.truncation.js';

package/ts_tools/readme.md

@@ -0,0 +1,37 @@
+Tool factories for host-supplied filesystem, shell and browser contexts, HTTP and JSON.
+
+Part of the [FlexHarness toolbox](https://code.foss.global/modelprofile.com/flexharness).
+Install the components your project uses. Provider adapters are registered explicitly;
+the agent and harness do not install or register vendor SDKs.
+
+```sh
+pnpm add @modelprofile.com/flexharness
+```
+
+See the [toolbox usage and migration guide](https://code.foss.global/modelprofile.com/flexharness#readme)
+for composition examples and the SmartAI/SmartAgent migration map.
+
+## Issue Reporting and Security
+
+Report issues and security concerns through [community.foss.global](https://community.foss.global).
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts_tools/tool.browser.ts

@@ -0,0 +1,159 @@
+import * as plugins from './plugins.js';
+import {
+  formatToolOutput,
+  type IBrowserToolInput,
+  type IToolExecutionContext,
+  type IToolInvocationOptions,
+  type TBrowserToolAction,
+} from './tool.context.js';
+
+export interface ICreateBrowserToolsOptions {
+  /** Maximum output lines before truncating. */
+  maxLines?: number;
+  /** Maximum output bytes before truncating. */
+  maxBytes?: number;
+  /** Browser actions exposed by the tool. Defaults to every supported action. */
+  allowedActions?: readonly TBrowserToolAction[];
+}
+
+const browserActions = [
+  'navigate',
+  'snapshot',
+  'screenshot',
+  'click',
+  'fill',
+  'press',
+  'evaluate',
+  'close',
+] as const satisfies readonly TBrowserToolAction[];
+
+export function createBrowserTools(context: IToolExecutionContext, options: ICreateBrowserToolsOptions = {}): plugins.ToolSet {
+  const allowedActions = normalizeAllowedBrowserActions(options.allowedActions);
+  const allowedActionList = [...allowedActions].join(', ');
+  const defaultAction = allowedActions.has('snapshot')
+    ? 'snapshot'
+    : allowedActions.values().next().value!;
+  const description = [
+    'Control a browser supplied by the host execution context for web UI inspection and interaction.',
+    `Actions: ${allowedActionList}.`,
+    ...(allowedActions.has('snapshot')
+      ? ['Use snapshot after navigation or interaction to inspect page text and interactive selectors before choosing the next action.']
+      : []),
+    ...(hasBrowserSideEffectAction(allowedActions)
+      ? ['Actions that navigate or modify page state require host permission when configured.']
+      : []),
+  ].join(' ');
+  const inputSchema = plugins.z.object({
+    action: plugins.z.string().default(defaultAction).describe(`Action: ${allowedActionList}`),
+    url: plugins.z.string().optional().describe('Optional target URL'),
+    selector: plugins.z.string().optional().describe('Optional element selector'),
+    text: plugins.z.string().optional().describe('Optional text, key, or mode hint'),
+    script: plugins.z.string().optional().describe('Optional host-defined script input'),
+    timeoutMs: plugins.z.number().optional().describe('Optional action timeout in milliseconds'),
+  });
+  return {
+    browser: plugins.tool({
+      description,
+      inputSchema,
+      execute: async (
+        input: IBrowserToolInput,
+        invocationOptions?: plugins.ToolExecutionOptions<unknown>,
+      ) => {
+        if (!context.browser) {
+          throw new Error('Browser tool is not available in this execution context.');
+        }
+        const action = normalizeBrowserAction(input.action, allowedActions, defaultAction);
+        const abortSignal = invocationOptions?.abortSignal ?? context.abortSignal;
+        await requestBrowserPermission(context, { ...input, action }, {
+          toolCallId: invocationOptions?.toolCallId,
+          abortSignal,
+        });
+        const result = await context.browser.execute({ ...input, action }, {
+          timeoutMs: input.timeoutMs,
+          toolCallId: invocationOptions?.toolCallId,
+          abortSignal,
+        });
+        return plugins.truncateOutput(formatToolOutput(result), {
+          maxLines: options.maxLines,
+          maxBytes: options.maxBytes,
+        }).content;
+      },
+    }),
+  };
+}
+
+const normalizeAllowedBrowserActions = (
+  actionsArg: readonly TBrowserToolAction[] | undefined,
+): ReadonlySet<TBrowserToolAction> => {
+  const actions = actionsArg ?? browserActions;
+  if (!Array.isArray(actions) || actions.length === 0) {
+    throw new Error('allowedActions must contain at least one supported browser action.');
+  }
+  const allowedActions = new Set<TBrowserToolAction>();
+  for (const action of actions) {
+    if (!browserActions.includes(action)) {
+      throw new Error(`Unsupported allowed browser action: ${String(action)}.`);
+    }
+    allowedActions.add(action);
+  }
+  return allowedActions;
+};
+
+const hasBrowserSideEffectAction = (actionsArg: ReadonlySet<TBrowserToolAction>): boolean => {
+  for (const action of ['navigate', 'click', 'fill', 'press', 'evaluate', 'close'] as const) {
+    if (actionsArg.has(action)) return true;
+  }
+  return false;
+};
+
+const normalizeBrowserAction = (
+  input: unknown,
+  allowedActions: ReadonlySet<TBrowserToolAction>,
+  defaultAction: TBrowserToolAction,
+): TBrowserToolAction => {
+  const action = typeof input === 'string' && input.trim()
+    ? input.trim().toLowerCase()
+    : defaultAction;
+  if (allowedActions.has(action as TBrowserToolAction)) {
+    return action as TBrowserToolAction;
+  }
+  throw new Error(`Unsupported browser action: ${String(input)}. Use one of: ${[...allowedActions].join(', ')}.`);
+};
+
+const requestBrowserPermission = async (
+  context: IToolExecutionContext,
+  input: IBrowserToolInput & { action: TBrowserToolAction },
+  invocationOptions: IToolInvocationOptions,
+): Promise<void> => {
+  if (!context.requestPermission) return;
+  if (input.action === 'snapshot' || input.action === 'screenshot') return;
+  const titleByAction: Record<TBrowserToolAction, string> = {
+    navigate: 'Navigate browser',
+    snapshot: 'Inspect browser',
+    screenshot: 'Capture browser screenshot',
+    click: 'Click browser element',
+    fill: 'Fill browser element',
+    press: 'Press browser key',
+    evaluate: 'Evaluate browser JavaScript',
+    close: 'Close browser session',
+  };
+  await context.requestPermission({
+    type: 'browser',
+    title: titleByAction[input.action],
+    toolCallId: invocationOptions.toolCallId,
+    abortSignal: invocationOptions.abortSignal,
+    metadata: {
+      action: input.action,
+      url: input.url,
+      selector: input.selector,
+      key: input.action === 'press' ? input.text : undefined,
+      textLength: input.action === 'fill' ? input.text?.length ?? 0 : undefined,
+      scriptPreview: input.action === 'evaluate' && input.script ? compactMetadataText(input.script) : undefined,
+    },
+  });
+};
+
+const compactMetadataText = (text: string): string => {
+  const compacted = text.replace(/\s+/g, ' ').trim();
+  return compacted.length > 160 ? `${compacted.slice(0, 157)}...` : compacted;
+};

package/ts_tools/tool.context.ts

@@ -0,0 +1,23 @@
+import type { IToolShellResult } from '@modelprofile.com/flexharness-agent';
+export type * from '@modelprofile.com/flexharness-agent';
+
+export const formatShellResult = (result: IToolShellResult | string): string => {
+  if (typeof result === 'string') return result;
+  if (result.exitCode === 0) return result.stdout;
+  return [
+    `Exit code: ${result.exitCode}`,
+    result.signal ? `Signal: ${result.signal}` : '',
+    `stdout:\n${result.stdout}`,
+    `stderr:\n${result.stderr ?? ''}`,
+  ].filter(Boolean).join('\n');
+};
+
+export const formatToolOutput = (output: unknown): string => {
+  if (typeof output === 'string') return output;
+  try {
+    return JSON.stringify(output, undefined, 2);
+  } catch {
+    return String(output);
+  }
+};
+