@modelprofile.com/flexharness 6.1.0 → 7.0.0

package/ts_kvm/tools.ts

@@ -0,0 +1,58 @@
+import { KvmTerminal } from './classes.kvmterminal.js';
+import type { IKvmTerminalCommandResult } from './interfaces.js';
+
+export interface IKvmTool<TInput = unknown, TOutput = unknown> {
+  name: string;
+  description: string;
+  parameters: unknown;
+  execute: (input: TInput) => Promise<TOutput>;
+}
+
+export interface IKvmToolOptions {
+  terminal: KvmTerminal;
+}
+
+export interface IKvmTerminalRunCommandInput {
+  command: string;
+}
+
+export type TKvmTerminalObserveInput = Record<string, never>;
+
+export const createKvmTools = (options: IKvmToolOptions): IKvmTool[] => {
+  return [
+    {
+      name: 'kvm_terminal_run_command',
+      description: 'Run a command through the visual KVM terminal transport and return OCR-parsed output.',
+      parameters: {
+        type: 'object',
+        properties: {
+          command: {
+            type: 'string',
+            description: 'The terminal command to run.',
+          },
+        },
+        required: ['command'],
+        additionalProperties: false,
+      },
+      execute: async (input: unknown): Promise<IKvmTerminalCommandResult> => {
+        const typedInput = input as Partial<IKvmTerminalRunCommandInput>;
+        if (!typedInput || typeof typedInput.command !== 'string') {
+          throw new Error('kvm_terminal_run_command requires a string command.');
+        }
+        return options.terminal.runCommand(typedInput.command);
+      },
+    },
+    {
+      name: 'kvm_terminal_observe',
+      description: 'Observe the current visual KVM terminal text through the configured OCR engine.',
+      parameters: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+      },
+      execute: async (): Promise<string> => {
+        return options.terminal.observeText();
+      },
+    },
+  ];
+};

package/ts_mcp/index.ts

@@ -0,0 +1,470 @@
+import { Client, type ClientOptions } from '@modelcontextprotocol/sdk/client/index.js';
+import {
+  StdioClientTransport,
+  type StdioServerParameters,
+} from '@modelcontextprotocol/sdk/client/stdio.js';
+import {
+  StreamableHTTPClientTransport,
+  type StreamableHTTPClientTransportOptions,
+} from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import type { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { jsonSchema, tool } from 'ai';
+import type { ToolSet } from 'ai';
+import type { ToolExecutionOptions } from 'ai';
+import {
+  connectMcpClientWithRequestOptions,
+  withMcpRequestOptions,
+} from './requestcontext.js';
+
+const DEFAULT_MAX_LIST_TOOLS_PAGES = 100;
+
+export type TMcpListToolsResult = Awaited<ReturnType<Client['listTools']>>;
+export type TMcpToolMetadata = TMcpListToolsResult['tools'][number];
+export type TMcpCallToolResult = Awaited<ReturnType<Client['callTool']>>;
+
+export interface IMcpClientLike {
+  listTools(params?: { cursor?: string }, options?: RequestOptions): Promise<TMcpListToolsResult>;
+  callTool(
+    params: { name: string; arguments?: Record<string, unknown> },
+    resultSchema?: unknown,
+    options?: RequestOptions,
+  ): Promise<TMcpCallToolResult>;
+  close?(): Promise<void>;
+}
+
+export interface IMcpServerClientOptions {
+  clientName?: string;
+  clientVersion?: string;
+  clientOptions?: ClientOptions;
+  requestOptions?: RequestOptions;
+}
+
+export interface IMcpStdioServerConfig extends StdioServerParameters, IMcpServerClientOptions {
+  type: 'stdio';
+}
+
+export interface IMcpStreamableHttpServerConfig extends IMcpServerClientOptions {
+  type: 'streamableHttp' | 'http';
+  url: string | URL;
+  transportOptions?: StreamableHTTPClientTransportOptions;
+}
+
+export interface IMcpTransportServerConfig extends IMcpServerClientOptions {
+  type: 'transport';
+  transport: Transport;
+}
+
+export interface IMcpClientServerConfig {
+  type: 'client';
+  client: IMcpClientLike;
+}
+
+export type TMcpServerConfig =
+  | IMcpStdioServerConfig
+  | IMcpStreamableHttpServerConfig
+  | IMcpTransportServerConfig
+  | IMcpClientServerConfig;
+
+export interface IMcpToolFormatContext {
+  serverName: string;
+  toolName: string;
+  exposedToolName: string;
+}
+
+export interface IMcpAuthorizeToolCallContext extends IMcpToolFormatContext {
+  arguments: Record<string, unknown>;
+  tool: TMcpToolMetadata;
+  toolCallId: string;
+  abortSignal?: AbortSignal;
+}
+
+export interface ICreateMcpToolsOptions {
+  servers: Record<string, TMcpServerConfig>;
+  clientName?: string;
+  clientVersion?: string;
+  clientOptions?: ClientOptions;
+  requestOptions?: RequestOptions;
+  listToolsRequestOptions?: RequestOptions;
+  callToolRequestOptions?: RequestOptions;
+  /** Maximum MCP listTools pages per server. Default: 100. */
+  maxListToolsPages?: number;
+  prefixToolNames?: boolean;
+  formatResult?: (result: TMcpCallToolResult, context: IMcpToolFormatContext) => unknown;
+  /** Resolve to allow the MCP tool call, or throw to deny it. Omission allows all calls. */
+  authorizeToolCall?: (context: IMcpAuthorizeToolCallContext) => PromiseLike<void> | void;
+}
+
+export interface IMcpConnectedServer {
+  name: string;
+  client: IMcpClientLike;
+  tools: TMcpToolMetadata[];
+}
+
+export interface IMcpToolNameMapping {
+  serverName: string;
+  toolName: string;
+}
+
+export interface ICreateMcpToolsResult {
+  tools: ToolSet;
+  servers: IMcpConnectedServer[];
+  toolNameMap: Record<string, IMcpToolNameMapping>;
+  close: () => Promise<void>;
+}
+
+export const createMcpTools = async (
+  options: ICreateMcpToolsOptions,
+): Promise<ICreateMcpToolsResult> => {
+  const serverEntries = Object.entries(options.servers);
+  if (serverEntries.length === 0) {
+    throw new Error('createMcpTools requires at least one MCP server.');
+  }
+  const maxListToolsPages = normalizeMaxListToolsPages(options.maxListToolsPages);
+
+  const connectedServers: IMcpConnectedServer[] = [];
+  try {
+    for (const [serverName, config] of serverEntries) {
+      const client = await connectMcpServer(serverName, config, options);
+      const connectedServer: IMcpConnectedServer = { name: serverName, client, tools: [] };
+      connectedServers.push(connectedServer);
+      connectedServer.tools = await listAllMcpTools(
+        client,
+        options.listToolsRequestOptions ?? getServerRequestOptions(config) ?? options.requestOptions,
+        maxListToolsPages,
+      );
+    }
+
+    const exposedTools: ToolSet = {};
+    const toolNameMap: Record<string, IMcpToolNameMapping> = {};
+    const usedToolNames = new Set<string>(['invalid']);
+    const formatResult = options.formatResult ?? formatMcpToolResult;
+    const shouldPrefixToolNames = options.prefixToolNames ?? connectedServers.length > 1;
+
+    for (const server of connectedServers) {
+      for (const mcpTool of server.tools) {
+        const baseToolName = createExposedToolName(server.name, mcpTool.name, shouldPrefixToolNames);
+        const exposedToolName = createUniqueToolName(baseToolName, usedToolNames);
+        usedToolNames.add(exposedToolName);
+        toolNameMap[exposedToolName] = {
+          serverName: server.name,
+          toolName: mcpTool.name,
+        };
+
+        exposedTools[exposedToolName] = tool({
+          description: mcpTool.description ?? `MCP tool ${mcpTool.name} from ${server.name}`,
+          inputSchema: jsonSchema(mcpTool.inputSchema as never),
+          execute: async (input: unknown, invocationOptions?: ToolExecutionOptions<unknown>) => {
+            const normalizedArguments = normalizeMcpArguments(input);
+            await options.authorizeToolCall?.({
+              serverName: server.name,
+              toolName: mcpTool.name,
+              exposedToolName,
+              arguments: normalizedArguments,
+              tool: mcpTool,
+              toolCallId: invocationOptions?.toolCallId ?? '',
+              abortSignal: invocationOptions?.abortSignal,
+            });
+            const configuredCallToolOptions: RequestOptions = {
+              ...options.requestOptions,
+              ...options.callToolRequestOptions,
+            };
+            const result = await withMcpRequestOptions(
+              configuredCallToolOptions,
+              invocationOptions?.abortSignal,
+              (requestOptions) => server.client.callTool(
+                {
+                  name: mcpTool.name,
+                  arguments: normalizedArguments,
+                },
+                undefined,
+                requestOptions,
+              ),
+            );
+            const formattedResult = formatResult(result, {
+              serverName: server.name,
+              toolName: mcpTool.name,
+              exposedToolName,
+            });
+            if ((result as Record<string, unknown>).isError === true) {
+              throw new Error(formatMcpError(formattedResult));
+            }
+            return formattedResult;
+          },
+        });
+      }
+    }
+
+    return {
+      tools: exposedTools,
+      servers: connectedServers,
+      toolNameMap,
+      close: async () => closeMcpClients(connectedServers),
+    };
+  } catch (error) {
+    return rethrowAfterCleanup(
+      error,
+      () => closeMcpClients(connectedServers),
+      'Failed to create MCP tools and clean up connected clients.',
+    );
+  }
+};
+
+export const sanitizeMcpToolName = (name: string, fallback = 'mcp_tool'): string => {
+  const sanitized = name
+    .trim()
+    .replace(/[^a-zA-Z0-9_-]+/g, '_')
+    .replace(/^_+|_+$/g, '');
+  const safeName = sanitized || fallback;
+  return /^[a-zA-Z_]/.test(safeName) ? safeName : `_${safeName}`;
+};
+
+export const formatMcpToolResult = (result: TMcpCallToolResult): unknown => {
+  const resultRecord = result as Record<string, unknown>;
+  if (Object.prototype.hasOwnProperty.call(resultRecord, 'toolResult')) {
+    return resultRecord.toolResult;
+  }
+
+  const content = Array.isArray(resultRecord.content)
+    ? resultRecord.content.map(formatMcpContentPart).filter(Boolean).join('\n\n')
+    : '';
+  const formattedContent = resultRecord.isError && content
+    ? `MCP tool returned an error:\n${content}`
+    : content;
+  const structuredContent = resultRecord.structuredContent;
+
+  if (structuredContent !== undefined && formattedContent) {
+    return `${formattedContent}\n\nStructured content:\n${stringifyJson(structuredContent)}`;
+  }
+  if (structuredContent !== undefined) {
+    return structuredContent;
+  }
+  if (formattedContent) {
+    return formattedContent;
+  }
+  return stringifyJson(result);
+};
+
+const connectMcpServer = async (
+  serverName: string,
+  config: TMcpServerConfig,
+  options: ICreateMcpToolsOptions,
+): Promise<IMcpClientLike> => {
+  if (config.type === 'client') {
+    return config.client;
+  }
+
+  const client = new Client(
+    {
+      name: config.clientName ?? options.clientName ?? 'smartagent-mcp',
+      version: config.clientVersion ?? options.clientVersion ?? '1.0.0',
+    },
+    config.clientOptions ?? options.clientOptions ?? { capabilities: {} },
+  );
+  const transport = createMcpTransport(config);
+  try {
+    await connectMcpClientWithRequestOptions(
+      client,
+      transport,
+      config.requestOptions ?? options.requestOptions,
+    );
+  } catch (error) {
+    await rethrowAfterCleanup(
+      error,
+      async () => {
+        try {
+          await client.close();
+        } catch (clientCloseError) {
+          try {
+            await transport.close();
+          } catch (transportCloseError) {
+            throw new AggregateError(
+              [clientCloseError, transportCloseError],
+              `Failed to close MCP client and transport for "${serverName}".`,
+            );
+          }
+          throw clientCloseError;
+        }
+      },
+      `Failed to connect MCP server "${serverName}" and clean up its client.`,
+    );
+  }
+  return client;
+};
+
+const createMcpTransport = (
+  config: Exclude<TMcpServerConfig, IMcpClientServerConfig>,
+): Transport => {
+  if (config.type === 'stdio') {
+    const { type, clientName, clientVersion, clientOptions, requestOptions, ...serverParameters } = config;
+    return new StdioClientTransport(serverParameters);
+  }
+
+  if (config.type === 'streamableHttp' || config.type === 'http') {
+    return new StreamableHTTPClientTransport(new URL(config.url), config.transportOptions);
+  }
+
+  if (config.type === 'transport') {
+    return config.transport;
+  }
+
+  throw new Error('Unsupported MCP server transport.');
+};
+
+const getServerRequestOptions = (config: TMcpServerConfig): RequestOptions | undefined => {
+  return config.type === 'client' ? undefined : config.requestOptions;
+};
+
+const listAllMcpTools = async (
+  client: IMcpClientLike,
+  requestOptions?: RequestOptions,
+  maxPages = DEFAULT_MAX_LIST_TOOLS_PAGES,
+): Promise<TMcpToolMetadata[]> => {
+  const tools: TMcpToolMetadata[] = [];
+  const seenCursors = new Set<string>();
+  let cursor: string | undefined;
+  for (let page = 1; page <= maxPages; page++) {
+    const result = await withMcpRequestOptions(
+      requestOptions,
+      undefined,
+      (isolatedRequestOptions) => client.listTools(
+        cursor ? { cursor } : undefined,
+        isolatedRequestOptions,
+      ),
+    );
+    tools.push(...result.tools);
+    const nextCursor = result.nextCursor;
+    if (!nextCursor) {
+      return tools;
+    }
+    if (seenCursors.has(nextCursor)) {
+      throw new Error(`MCP listTools returned repeated cursor "${nextCursor}".`);
+    }
+    seenCursors.add(nextCursor);
+    cursor = nextCursor;
+  }
+  throw new Error(`MCP listTools exceeded the maximum of ${maxPages} pages.`);
+};
+
+const normalizeMaxListToolsPages = (maxPages = DEFAULT_MAX_LIST_TOOLS_PAGES): number => {
+  if (!Number.isSafeInteger(maxPages) || maxPages <= 0) {
+    throw new Error('maxListToolsPages must be a positive integer.');
+  }
+  return maxPages;
+};
+
+const createExposedToolName = (
+  serverName: string,
+  toolName: string,
+  prefixToolName: boolean,
+): string => {
+  const safeToolName = sanitizeMcpToolName(toolName);
+  if (!prefixToolName) {
+    return safeToolName;
+  }
+  return `${sanitizeMcpToolName(serverName, 'mcp')}__${safeToolName}`;
+};
+
+const createUniqueToolName = (baseToolName: string, usedToolNames: Set<string>): string => {
+  if (!usedToolNames.has(baseToolName)) {
+    return baseToolName;
+  }
+  let suffix = 2;
+  while (usedToolNames.has(`${baseToolName}_${suffix}`)) {
+    suffix++;
+  }
+  return `${baseToolName}_${suffix}`;
+};
+
+const normalizeMcpArguments = (input: unknown): Record<string, unknown> => {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    return {};
+  }
+  return input as Record<string, unknown>;
+};
+
+const formatMcpError = (formattedResult: unknown): string => {
+  if (typeof formattedResult === 'string' && formattedResult) {
+    return formattedResult;
+  }
+  const formatted = stringifyJson(formattedResult);
+  return formatted || 'MCP tool returned an error.';
+};
+
+const formatMcpContentPart = (part: unknown): string => {
+  if (!part || typeof part !== 'object') {
+    return stringifyJson(part);
+  }
+  const partRecord = part as Record<string, unknown>;
+  const type = partRecord.type;
+  if (type === 'text') {
+    return typeof partRecord.text === 'string' ? partRecord.text : '';
+  }
+  if (type === 'image' || type === 'audio') {
+    const data = typeof partRecord.data === 'string' ? partRecord.data : '';
+    const mimeType = typeof partRecord.mimeType === 'string' ? partRecord.mimeType : 'application/octet-stream';
+    return `[${type}: ${mimeType}; base64 length ${data.length}]`;
+  }
+  if (type === 'resource') {
+    return formatMcpResourcePart(partRecord.resource);
+  }
+  if (type === 'resource_link') {
+    const name = typeof partRecord.name === 'string' ? partRecord.name : 'resource';
+    const uri = typeof partRecord.uri === 'string' ? partRecord.uri : '';
+    return `Resource link ${name}${uri ? `: ${uri}` : ''}`;
+  }
+  return stringifyJson(part);
+};
+
+const formatMcpResourcePart = (resource: unknown): string => {
+  if (!resource || typeof resource !== 'object') {
+    return stringifyJson(resource);
+  }
+  const resourceRecord = resource as Record<string, unknown>;
+  const uri = typeof resourceRecord.uri === 'string' ? resourceRecord.uri : 'resource';
+  if (typeof resourceRecord.text === 'string') {
+    return `Resource ${uri}:\n${resourceRecord.text}`;
+  }
+  if (typeof resourceRecord.blob === 'string') {
+    const mimeType = typeof resourceRecord.mimeType === 'string' ? resourceRecord.mimeType : 'application/octet-stream';
+    return `[resource ${uri}: ${mimeType}; base64 length ${resourceRecord.blob.length}]`;
+  }
+  return stringifyJson(resource);
+};
+
+const stringifyJson = (value: unknown): string => {
+  if (typeof value === 'string') {
+    return value;
+  }
+  try {
+    return JSON.stringify(value, undefined, 2);
+  } catch {
+    return String(value);
+  }
+};
+
+const closeMcpClients = async (servers: IMcpConnectedServer[]): Promise<void> => {
+  const results = await Promise.allSettled(servers.map((server) => server.client.close?.()));
+  const errors = results
+    .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
+    .map((result) => result.reason);
+  if (errors.length > 0) {
+    throw new AggregateError(errors, 'Failed to close one or more MCP clients.');
+  }
+};
+
+const rethrowAfterCleanup = async (
+  originalError: unknown,
+  cleanup: () => Promise<void>,
+  message: string,
+): Promise<never> => {
+  try {
+    await cleanup();
+  } catch (cleanupError) {
+    const cleanupErrors = cleanupError instanceof AggregateError
+      ? cleanupError.errors
+      : [cleanupError];
+    throw new AggregateError([originalError, ...cleanupErrors], message);
+  }
+  throw originalError;
+};

package/ts_mcp/readme.md

@@ -0,0 +1,37 @@
+MCP client connections and AI SDK tool conversion with request-scoped cancellation.
+
+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 @modelcontextprotocol/sdk
+```
+
+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_mcp/requestcontext.ts

@@ -0,0 +1,66 @@
+import type { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+
+export interface IMcpRequestContext {
+  requestOptions?: RequestOptions;
+  cleanup: () => void;
+}
+
+export const createMcpRequestContext = (
+  configuredOptions?: RequestOptions,
+  preferredAbortSignal?: AbortSignal,
+): IMcpRequestContext => {
+  const requestOptions: RequestOptions = { ...configuredOptions };
+  const sourceSignal = preferredAbortSignal ?? requestOptions.signal;
+  if (!sourceSignal) {
+    return {
+      requestOptions: Object.keys(requestOptions).length > 0 ? requestOptions : undefined,
+      cleanup: () => undefined,
+    };
+  }
+
+  const relayController = new AbortController();
+  const forwardAbort = () => relayController.abort(sourceSignal.reason);
+  let listenerWasAdded = false;
+  if (sourceSignal.aborted) {
+    forwardAbort();
+  } else {
+    sourceSignal.addEventListener('abort', forwardAbort, { once: true });
+    listenerWasAdded = true;
+  }
+
+  return {
+    requestOptions: {
+      ...requestOptions,
+      signal: relayController.signal,
+    },
+    cleanup: () => {
+      if (listenerWasAdded) {
+        sourceSignal.removeEventListener('abort', forwardAbort);
+      }
+    },
+  };
+};
+
+export const withMcpRequestOptions = async <T>(
+  configuredOptions: RequestOptions | undefined,
+  preferredAbortSignal: AbortSignal | undefined,
+  request: (requestOptions?: RequestOptions) => Promise<T>,
+): Promise<T> => {
+  const context = createMcpRequestContext(configuredOptions, preferredAbortSignal);
+  try {
+    return await request(context.requestOptions);
+  } finally {
+    context.cleanup();
+  }
+};
+
+export const connectMcpClientWithRequestOptions = async (
+  client: { connect: (transport: Transport, requestOptions?: RequestOptions) => Promise<void> },
+  transport: Transport,
+  configuredOptions?: RequestOptions,
+): Promise<void> => withMcpRequestOptions(
+  configuredOptions,
+  undefined,
+  (requestOptions) => client.connect(transport, requestOptions),
+);

package/ts_media/index.ts

@@ -0,0 +1,29 @@
+import * as plugins from './plugins.js';
+import type { TSmartAiLanguageModel } from '@modelprofile.com/flexharness-models';
+
+export interface IVisionOptions {
+  model: TSmartAiLanguageModel;
+  image: Buffer | Uint8Array;
+  prompt: string;
+  mediaType?: 'image/jpeg' | 'image/png' | 'image/webp' | 'image/gif';
+}
+
+export async function analyzeImage(options: IVisionOptions): Promise<string> {
+  const result = await plugins.generateText({
+    model: options.model,
+    messages: [
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: options.prompt },
+          {
+            type: 'file',
+            data: options.image,
+            mediaType: options.mediaType ?? 'image/jpeg',
+          },
+        ],
+      },
+    ],
+  });
+  return result.text;
+}

package/ts_media/plugins.ts

@@ -0,0 +1,2 @@
+import { generateText } from 'ai';
+export { generateText };