@modelprofile.com/flexharness 6.1.0 → 7.0.0

package/ts_tools/tool.filesystem.ts

@@ -0,0 +1,144 @@
+import * as plugins from './plugins.js';
+import {
+  formatToolOutput,
+  type IToolExecutionContext,
+} from './tool.context.js';
+
+export interface ICreateFilesystemToolsOptions {
+  /** Include delete_file. Default: true. */
+  includeDelete?: boolean;
+  /** Maximum output lines before truncating. */
+  maxLines?: number;
+  /** Maximum output bytes before truncating. */
+  maxBytes?: number;
+}
+
+export function createFilesystemTools(context: IToolExecutionContext, options: ICreateFilesystemToolsOptions = {}): plugins.ToolSet {
+  const truncate = (output: unknown) => plugins.truncateOutput(formatToolOutput(output), {
+    maxLines: options.maxLines,
+    maxBytes: options.maxBytes,
+  }).content;
+  const tools: plugins.ToolSet = {
+    read_file: plugins.tool({
+      description:
+        'Read a UTF-8 file in the active workspace. Paths may be absolute or relative to the workspace root.',
+      inputSchema: plugins.z.object({
+        path: plugins.z.string().describe('File path'),
+        startLine: plugins.z
+          .number()
+          .optional()
+          .describe('First line (1-indexed, inclusive)'),
+        endLine: plugins.z
+          .number()
+          .optional()
+          .describe('Last line (1-indexed, inclusive)'),
+      }),
+      execute: async (
+        {
+          path: filePath,
+          startLine,
+          endLine,
+        }: {
+          path: string;
+          startLine?: number;
+          endLine?: number;
+        },
+        invocationOptions?: plugins.ToolExecutionOptions<unknown>,
+      ) => {
+        if (!context.fs) {
+          throw new Error('Filesystem tools are not available in this execution context.');
+        }
+        return truncate(await context.fs.readFile(filePath, { startLine, endLine }, {
+          toolCallId: invocationOptions?.toolCallId,
+          abortSignal: invocationOptions?.abortSignal ?? context.abortSignal,
+        }));
+      },
+    }),
+
+    write_file: plugins.tool({
+      description:
+        'Write UTF-8 content to a file in the active workspace. Creates parent directories and overwrites existing content. Requires host permission when configured.',
+      inputSchema: plugins.z.object({
+        path: plugins.z.string().describe('File path'),
+        content: plugins.z.string().describe('Complete file content to write'),
+      }),
+      execute: async (
+        { path: filePath, content }: { path: string; content: string },
+        invocationOptions?: plugins.ToolExecutionOptions<unknown>,
+      ) => {
+        if (!context.fs) {
+          throw new Error('Filesystem tools are not available in this execution context.');
+        }
+        const abortSignal = invocationOptions?.abortSignal ?? context.abortSignal;
+        await context.requestPermission?.({
+          type: 'write',
+          title: 'Write file',
+          metadata: { path: filePath, bytes: Buffer.byteLength(content, 'utf8') },
+          toolCallId: invocationOptions?.toolCallId,
+          abortSignal,
+        });
+        const result = await context.fs.writeFile(filePath, content, {
+          toolCallId: invocationOptions?.toolCallId,
+          abortSignal,
+        });
+        return truncate(result ?? `Written ${Buffer.byteLength(content, 'utf8')} bytes to ${filePath}`);
+      },
+    }),
+
+    list_directory: plugins.tool({
+      description: 'List files and directories in the active workspace. Paths may be absolute or relative to the workspace root.',
+      inputSchema: plugins.z.object({
+        path: plugins.z.string().default('.').describe('Directory path to list'),
+        recursive: plugins.z
+          .boolean()
+          .optional()
+          .describe('List recursively. Default: false'),
+      }),
+      execute: async (
+        { path: directoryPath, recursive }: { path: string; recursive?: boolean },
+        invocationOptions?: plugins.ToolExecutionOptions<unknown>,
+      ) => {
+        if (!context.fs) {
+          throw new Error('Filesystem tools are not available in this execution context.');
+        }
+        const result = await context.fs.listDirectory(directoryPath, { recursive }, {
+          toolCallId: invocationOptions?.toolCallId,
+          abortSignal: invocationOptions?.abortSignal ?? context.abortSignal,
+        });
+        return truncate(Array.isArray(result) ? result.join('\n') : result);
+      },
+    }),
+  };
+
+  if (options.includeDelete !== false) {
+    tools.delete_file = plugins.tool({
+      description: 'Delete a file or empty directory in the active workspace. Requires host permission when configured.',
+      inputSchema: plugins.z.object({
+        path: plugins.z.string().describe('Path to delete'),
+      }),
+      execute: async (
+        { path: targetPath }: { path: string },
+        invocationOptions?: plugins.ToolExecutionOptions<unknown>,
+      ) => {
+        if (!context.fs?.deletePath) {
+          throw new Error('Deleting files is not available in this execution context.');
+        }
+        const abortSignal = invocationOptions?.abortSignal ?? context.abortSignal;
+        await context.requestPermission?.({
+          type: 'delete',
+          title: 'Delete file',
+          metadata: { path: targetPath },
+          toolCallId: invocationOptions?.toolCallId,
+          abortSignal,
+        });
+        const result = await context.fs.deletePath(targetPath, {
+          toolCallId: invocationOptions?.toolCallId,
+          abortSignal,
+        });
+        return truncate(result ?? `Deleted ${targetPath}`);
+      },
+    });
+  }
+
+  return tools;
+}

package/ts_tools/tool.http.ts

@@ -0,0 +1,78 @@
+import * as plugins from './plugins.js';
+
+export function httpTool(): plugins.ToolSet {
+  return {
+    http_get: plugins.tool({
+      description: 'Make an HTTP GET request and return the response.',
+      inputSchema: plugins.z.object({
+        url: plugins.z.string().describe('URL to request'),
+        headers: plugins.z
+          .record(plugins.z.string(), plugins.z.string())
+          .optional()
+          .describe('Request headers'),
+      }),
+      execute: async ({
+        url,
+        headers,
+      }: {
+        url: string;
+        headers?: Record<string, string>;
+      }) => {
+        let req = plugins.smartrequest.default.create().url(url);
+        if (headers) {
+          req = req.headers(headers);
+        }
+        const response = await req.get();
+        let body: string;
+        try {
+          const json = await response.json();
+          body = JSON.stringify(json, null, 2);
+        } catch {
+          body = await response.text();
+        }
+        return plugins.truncateOutput(`HTTP ${response.status}\n${body}`).content;
+      },
+    }),
+
+    http_post: plugins.tool({
+      description: 'Make an HTTP POST request with a JSON body.',
+      inputSchema: plugins.z.object({
+        url: plugins.z.string().describe('URL to request'),
+        body: plugins.z
+          .record(plugins.z.string(), plugins.z.unknown())
+          .optional()
+          .describe('JSON body to send'),
+        headers: plugins.z
+          .record(plugins.z.string(), plugins.z.string())
+          .optional()
+          .describe('Request headers'),
+      }),
+      execute: async ({
+        url,
+        body,
+        headers,
+      }: {
+        url: string;
+        body?: Record<string, unknown>;
+        headers?: Record<string, string>;
+      }) => {
+        let req = plugins.smartrequest.default.create().url(url);
+        if (headers) {
+          req = req.headers(headers);
+        }
+        if (body) {
+          req = req.json(body);
+        }
+        const response = await req.post();
+        let responseBody: string;
+        try {
+          const json = await response.json();
+          responseBody = JSON.stringify(json, null, 2);
+        } catch {
+          responseBody = await response.text();
+        }
+        return plugins.truncateOutput(`HTTP ${response.status}\n${responseBody}`).content;
+      },
+    }),
+  };
+}

package/ts_tools/tool.json.ts

@@ -0,0 +1,53 @@
+import * as plugins from './plugins.js';
+
+export function jsonTool(): plugins.ToolSet {
+  return {
+    json_validate: plugins.tool({
+      description:
+        'Validate a JSON string and optionally check for required fields.',
+      inputSchema: plugins.z.object({
+        jsonString: plugins.z.string().describe('JSON string to validate'),
+        requiredFields: plugins.z
+          .array(plugins.z.string())
+          .optional()
+          .describe('Fields that must exist at the top level'),
+      }),
+      execute: async ({
+        jsonString,
+        requiredFields,
+      }: {
+        jsonString: string;
+        requiredFields?: string[];
+      }) => {
+        try {
+          const parsed = JSON.parse(jsonString);
+          if (requiredFields?.length) {
+            const missing = requiredFields.filter((f) => !(f in parsed));
+            if (missing.length) {
+              return `Invalid: missing required fields: ${missing.join(', ')}`;
+            }
+          }
+          const type = Array.isArray(parsed) ? 'array' : typeof parsed;
+          return `Valid JSON (${type})`;
+        } catch (e) {
+          return `Invalid JSON: ${(e as Error).message}`;
+        }
+      },
+    }),
+
+    json_transform: plugins.tool({
+      description: 'Parse a JSON string and return it pretty-printed.',
+      inputSchema: plugins.z.object({
+        jsonString: plugins.z.string().describe('JSON string to format'),
+      }),
+      execute: async ({ jsonString }: { jsonString: string }) => {
+        try {
+          const parsed = JSON.parse(jsonString);
+          return JSON.stringify(parsed, null, 2);
+        } catch (e) {
+          return `Error parsing JSON: ${(e as Error).message}`;
+        }
+      },
+    }),
+  };
+}

package/ts_tools/tool.shell.ts

@@ -0,0 +1,418 @@
+import * as plugins from './plugins.js';
+import {
+  formatShellResult,
+  type IShellCommand,
+  type IShellStartedResult,
+  type IToolExecutionContext,
+  type IToolShellResult,
+} from './tool.context.js';
+
+const DEFAULT_FOREGROUND_PREVIEW_BYTES = 50 * 1024;
+const MAX_FOREGROUND_PRELIMINARY_CHUNKS = 64;
+const MAX_FOREGROUND_PRELIMINARY_BYTES = 256 * 1024;
+
+interface IForegroundShellStreamOptions {
+  abortSignal?: AbortSignal;
+  maxLines?: number;
+  maxBytes?: number;
+  start: (
+    abortSignal: AbortSignal,
+    onOutput: (stream: 'stdout' | 'stderr', chunk: string) => Promise<void>,
+  ) => Promise<IToolShellResult | string>;
+}
+
+interface IQueuedShellOutput {
+  kind: 'preliminary' | 'final';
+  content: string;
+  bytes: number;
+}
+
+interface IShellOutputWaiter {
+  resolve: (result: IteratorResult<string>) => void;
+  reject: (error: unknown) => void;
+}
+
+interface IShellCommandDeniedResult {
+  error: string;
+  allowedCommands: string[];
+}
+
+const singleShellOutput = async function* <TOutput>(output: TOutput): AsyncGenerator<TOutput> {
+  yield output;
+};
+
+const foregroundPreviewByteLimit = (configuredMaxBytes?: number): number => (
+  Number.isSafeInteger(configuredMaxBytes) && configuredMaxBytes! > 0
+    ? Math.min(configuredMaxBytes!, DEFAULT_FOREGROUND_PREVIEW_BYTES)
+    : DEFAULT_FOREGROUND_PREVIEW_BYTES
+);
+
+const formatForegroundShellPreview = (
+  stdout: string,
+  stderr: string,
+  captureTruncated: boolean,
+): string => {
+  const output = stderr
+    ? stdout
+      ? `stdout:\n${stdout}\nstderr:\n${stderr}`
+      : `stderr:\n${stderr}`
+    : stdout;
+  return captureTruncated
+    ? `${output}${output ? '\n' : ''}[Live output preview truncated; final output will follow.]`
+    : output;
+};
+
+class ForegroundShellResultStream implements AsyncIterableIterator<string> {
+  private readonly abortController = new AbortController();
+  private readonly abortSignal: AbortSignal;
+  private readonly previewByteLimit: number;
+  private readonly queue: IQueuedShellOutput[] = [];
+  private readonly waiters: IShellOutputWaiter[] = [];
+  private completion?: Promise<IToolShellResult | string>;
+  private stdout = '';
+  private stderr = '';
+  private previewBytes = 0;
+  private captureTruncated = false;
+  private lastPreview = '';
+  private preliminaryChunks = 0;
+  private preliminaryBytes = 0;
+  private previewsDisabled = false;
+  private settled = false;
+  private returned = false;
+  private terminalError: unknown;
+
+  constructor(private readonly options: IForegroundShellStreamOptions) {
+    this.abortSignal = options.abortSignal
+      ? AbortSignal.any([options.abortSignal, this.abortController.signal])
+      : this.abortController.signal;
+    this.previewByteLimit = foregroundPreviewByteLimit(options.maxBytes);
+  }
+
+  public [Symbol.asyncIterator](): AsyncIterableIterator<string> {
+    return this;
+  }
+
+  public next(): Promise<IteratorResult<string>> {
+    if (this.returned) return Promise.resolve({ done: true, value: undefined });
+    this.ensureStarted();
+    const queued = this.queue.shift();
+    if (queued) return Promise.resolve(this.deliver(queued));
+    if (this.settled) {
+      return this.terminalError === undefined
+        ? Promise.resolve({ done: true, value: undefined })
+        : Promise.reject(this.terminalError);
+    }
+    return new Promise<IteratorResult<string>>((resolve, reject) => {
+      this.waiters.push({ resolve, reject });
+    });
+  }
+
+  public async return(): Promise<IteratorResult<string>> {
+    if (!this.returned) {
+      this.returned = true;
+      this.abortController.abort(new DOMException('Foreground shell iteration stopped.', 'AbortError'));
+      this.queue.length = 0;
+      this.flushWaiters();
+    }
+    if (this.completion) {
+      try {
+        await this.completion;
+      } catch {
+        // Iterator cancellation owns the abort; the cancelled command result is not a tool failure.
+      }
+    }
+    return { done: true, value: undefined };
+  }
+
+  public async throw(error?: unknown): Promise<IteratorResult<string>> {
+    if (!this.returned) {
+      this.returned = true;
+      this.abortController.abort(error);
+      this.queue.length = 0;
+      while (this.waiters.length > 0) this.waiters.shift()!.reject(error);
+    }
+    if (this.completion) {
+      try {
+        await this.completion;
+      } catch {
+        // The caller-provided iterator error remains authoritative.
+      }
+    }
+    throw error;
+  }
+
+  private async handleOutput(stream: 'stdout' | 'stderr', chunk: string): Promise<void> {
+    if (this.returned || this.settled || this.previewsDisabled || !chunk) return;
+    let accepted = '';
+    let acceptedBytes = 0;
+    for (const character of chunk) {
+      const characterBytes = Buffer.byteLength(character);
+      if (this.previewBytes + acceptedBytes + characterBytes > this.previewByteLimit) break;
+      accepted += character;
+      acceptedBytes += characterBytes;
+    }
+    if (acceptedBytes < Buffer.byteLength(chunk)) this.captureTruncated = true;
+    if (accepted) {
+      if (stream === 'stdout') this.stdout += accepted;
+      else this.stderr += accepted;
+      this.previewBytes += acceptedBytes;
+    }
+    const preview = plugins.truncateOutput(
+      formatForegroundShellPreview(this.stdout, this.stderr, this.captureTruncated),
+      { maxLines: this.options.maxLines, maxBytes: this.options.maxBytes },
+    ).content;
+    if (!preview || preview === this.lastPreview) return;
+    const bytes = Buffer.byteLength(JSON.stringify(preview));
+    if (
+      this.preliminaryChunks + 1 > MAX_FOREGROUND_PRELIMINARY_CHUNKS
+      || this.preliminaryBytes + bytes > MAX_FOREGROUND_PRELIMINARY_BYTES
+    ) {
+      this.previewsDisabled = true;
+      return;
+    }
+    this.lastPreview = preview;
+    for (let index = this.queue.length - 1; index >= 0; index--) {
+      if (this.queue[index].kind === 'preliminary') this.queue.splice(index, 1);
+    }
+    this.queue.push({ kind: 'preliminary', content: preview, bytes });
+    if (this.captureTruncated) this.previewsDisabled = true;
+    this.flushWaiters();
+  }
+
+  private ensureStarted(): void {
+    if (this.completion) return;
+    const completion = Promise.resolve().then(() => this.options.start(
+      this.abortSignal,
+      async (stream, chunk) => this.handleOutput(stream, chunk),
+    ));
+    this.completion = completion;
+    void completion.then(
+      (result) => this.finish(result),
+      (error) => this.fail(error),
+    );
+  }
+
+  private finish(result: IToolShellResult | string): void {
+    this.settled = true;
+    if (this.returned) return;
+    const content = plugins.truncateOutput(formatShellResult(result), {
+      maxLines: this.options.maxLines,
+      maxBytes: this.options.maxBytes,
+    }).content;
+    this.queue.push({ kind: 'final', content, bytes: Buffer.byteLength(content) });
+    this.flushWaiters();
+  }
+
+  private fail(error: unknown): void {
+    this.settled = true;
+    this.terminalError = error;
+    this.flushWaiters();
+  }
+
+  private deliver(output: IQueuedShellOutput): IteratorResult<string> {
+    if (output.kind === 'preliminary') {
+      this.preliminaryChunks++;
+      this.preliminaryBytes += output.bytes;
+    }
+    return { done: false, value: output.content };
+  }
+
+  private flushWaiters(): void {
+    while (this.waiters.length > 0 && this.queue.length > 0) {
+      this.waiters.shift()!.resolve(this.deliver(this.queue.shift()!));
+    }
+    if (!this.settled && !this.returned) return;
+    while (this.waiters.length > 0) {
+      const waiter = this.waiters.shift()!;
+      if (!this.returned && this.terminalError !== undefined) waiter.reject(this.terminalError);
+      else waiter.resolve({ done: true, value: undefined });
+    }
+  }
+}
+
+export interface ICreateShellToolsOptions {
+  /**
+   * Exact executable allowlist for structured execution. Raw command filtering is advisory.
+   */
+  allowedCommands?: string[];
+  /** Maximum output lines before truncating. */
+  maxLines?: number;
+  /** Maximum output bytes before truncating. */
+  maxBytes?: number;
+  /** Expose start_shell when context.jobs exists. Default: true. */
+  includeBackground?: boolean;
+}
+
+export function createShellTools(context: IToolExecutionContext, options: ICreateShellToolsOptions = {}): plugins.ToolSet {
+  const tools: plugins.ToolSet = {
+    run_command: plugins.tool({
+      description:
+        'Execute a raw shell command through bash -lc. Shell composition is supported. Prefer run_shell when direct structured execution is sufficient.',
+      inputSchema: plugins.z.object({
+        command: plugins.z.string().describe('The shell command to execute'),
+        cwd: plugins.z
+          .string()
+          .optional()
+          .describe('Working directory for the command'),
+        timeout: plugins.z
+          .number()
+          .optional()
+          .describe('Timeout in milliseconds'),
+        timeoutMs: plugins.z
+          .number()
+          .optional()
+          .describe('Timeout in milliseconds'),
+      }),
+      execute: (
+        {
+          command,
+          cwd,
+          timeout,
+          timeoutMs,
+        }: {
+          command: string;
+          cwd?: string;
+          timeout?: number;
+          timeoutMs?: number;
+        },
+        invocationOptions?: plugins.ToolExecutionOptions<unknown>,
+      ): AsyncIterable<string> => {
+        const shell = context.shell;
+        if (!shell) {
+          throw new Error('Shell tool is not available in this execution context.');
+        }
+
+        if (options.allowedCommands?.length) {
+          const baseCommand = command.trim().split(/\s+/)[0];
+          if (!options.allowedCommands.includes(baseCommand)) {
+            return singleShellOutput(
+              `Raw command "${baseCommand}" is not in the advisory allowed commands list: ${options.allowedCommands.join(', ')}`,
+            );
+          }
+        }
+
+        const abortSignal = invocationOptions?.abortSignal ?? context.abortSignal;
+        return new ForegroundShellResultStream({
+          abortSignal,
+          maxLines: options.maxLines,
+          maxBytes: options.maxBytes,
+          start: async (executionSignal, onOutput) => {
+            await context.requestPermission?.({
+              type: 'shell',
+              title: 'Run shell command',
+              metadata: { command, cwd: cwd ?? context.cwd },
+              toolCallId: invocationOptions?.toolCallId,
+              abortSignal: executionSignal,
+            });
+            executionSignal.throwIfAborted();
+            return shell.run(command, {
+              cwd: cwd ?? context.cwd,
+              timeoutMs: timeoutMs ?? timeout,
+              toolCallId: invocationOptions?.toolCallId,
+              abortSignal: executionSignal,
+              onOutput,
+            });
+          },
+        });
+      },
+    }),
+  };
+
+  if (context.shell?.runStructured) {
+    tools.run_shell = plugins.tool({
+      description:
+        'Execute an executable directly with a literal argument array. No shell parsing or shell composition is performed.',
+      inputSchema: plugins.z.object({
+        executable: plugins.z.string().describe('Exact executable name or path'),
+        args: plugins.z.array(plugins.z.string()).default([]).describe('Literal argument array'),
+        cwd: plugins.z.string().optional().describe('Working directory for the command'),
+        timeoutMs: plugins.z.number().optional().describe('Timeout in milliseconds'),
+      }),
+      execute: (
+        input: IShellCommand & { cwd?: string; timeoutMs?: number },
+        invocationOptions?: plugins.ToolExecutionOptions<unknown>,
+      ): AsyncIterable<string | IShellCommandDeniedResult> => {
+        const runStructured = context.shell?.runStructured;
+        if (!runStructured) {
+          throw new Error('Structured shell execution is not available in this execution context.');
+        }
+        if (options.allowedCommands?.length && !options.allowedCommands.includes(input.executable)) {
+          return singleShellOutput({
+            error: `Executable "${input.executable}" is not in the allowed commands list.`,
+            allowedCommands: options.allowedCommands,
+          });
+        }
+        const abortSignal = invocationOptions?.abortSignal ?? context.abortSignal;
+        return new ForegroundShellResultStream({
+          abortSignal,
+          maxLines: options.maxLines,
+          maxBytes: options.maxBytes,
+          start: async (executionSignal, onOutput) => {
+            await context.requestPermission?.({
+              type: 'shell',
+              title: 'Run structured command',
+              metadata: { executable: input.executable, args: input.args, cwd: input.cwd ?? context.cwd },
+              toolCallId: invocationOptions?.toolCallId,
+              abortSignal: executionSignal,
+            });
+            executionSignal.throwIfAborted();
+            return runStructured(
+              { executable: input.executable, args: input.args },
+              {
+                cwd: input.cwd ?? context.cwd,
+                timeoutMs: input.timeoutMs,
+                toolCallId: invocationOptions?.toolCallId,
+                abortSignal: executionSignal,
+                onOutput,
+              },
+            );
+          },
+        });
+      },
+    });
+  }
+
+  if (context.jobs && options.includeBackground !== false) {
+    tools.start_shell = plugins.tool({
+      description:
+        'Start a structured shell command as an independent background execution and return its execution ID immediately.',
+      inputSchema: plugins.z.object({
+        executable: plugins.z.string().describe('Exact executable name or path'),
+        args: plugins.z.array(plugins.z.string()).default([]).describe('Literal argument array'),
+        cwd: plugins.z.string().optional().describe('Working directory for the command'),
+        timeoutMs: plugins.z.number().optional().describe('Background execution timeout in milliseconds'),
+      }),
+      execute: async (
+        input: IShellCommand & { cwd?: string; timeoutMs?: number },
+        invocationOptions?: plugins.ToolExecutionOptions<unknown>,
+      ): Promise<IShellStartedResult> => {
+        if (!context.jobs) throw new Error('Background jobs are not available in this execution context.');
+        if (options.allowedCommands?.length && !options.allowedCommands.includes(input.executable)) {
+          throw new Error(`Executable "${input.executable}" is not in the allowed commands list.`);
+        }
+        const admissionSignal = invocationOptions?.abortSignal ?? context.abortSignal;
+        await context.requestPermission?.({
+          type: 'shell-background',
+          title: 'Start background shell command',
+          metadata: { executable: input.executable, args: input.args, cwd: input.cwd ?? context.cwd },
+          toolCallId: invocationOptions?.toolCallId,
+          abortSignal: admissionSignal,
+        });
+        admissionSignal?.throwIfAborted();
+        const handle = await context.jobs.start({
+          type: 'shell',
+          command: { executable: input.executable, args: input.args },
+          cwd: input.cwd ?? context.cwd,
+          timeoutMs: input.timeoutMs,
+          metadata: { toolCallId: invocationOptions?.toolCallId },
+        }, {
+          toolCallId: invocationOptions?.toolCallId,
+          abortSignal: admissionSignal,
+        });
+        return { executionId: handle.executionId, state: 'running' };
+      },
+    });
+  }
+
+  return tools;
+}