@semalt-ai/code 1.8.0 → 1.8.3

package/lib/tool_specs.js

@@ -0,0 +1,499 @@
+'use strict';
+
+// TOOL_SPECS — parameter source of truth for every 'tool'-type tag in
+// TAG_REGISTRY (see lib/constants.js). Each entry is an OpenAI-format
+// JSON Schema describing the tool's arguments. This file exists so that:
+//
+//   1. A native function-calling `tools` array can be generated verbatim.
+//   2. The non-native system prompt (lib/prompts.js) can render clean tag
+//      documentation from a single source.
+//   3. Tool call arguments can eventually be validated before execution.
+//
+// Parameter names, required flags, and types were reverse-engineered from
+// lib/tools.js — specifically the `agentExecFile` / `agentExecShell`
+// branches and the `mapInvokeToCall` name→positional-args mapping. If
+// those change, this file must change in lockstep.
+//
+// Wrappers (minimax:tool_call, qwen:tool_call, tool_call, function_call,
+// function) carry `wrapper: true`. They are not tools themselves — they
+// are XML envelopes the StreamParser recognises so raw tool-call markup
+// does not leak into the rendered transcript. They should NOT be emitted
+// as tools in a native function-calling request.
+
+const TOOL_SPECS = {
+  exec: {
+    description: 'Run a shell command and return its stdout, stderr, and exit code.',
+    parameters: {
+      type: 'object',
+      properties: {
+        command: {
+          type: 'string',
+          description: 'Shell command to execute; runs through the default system shell',
+        },
+      },
+      required: ['command'],
+    },
+  },
+
+  shell: {
+    description: 'Run a shell command and return its stdout, stderr, and exit code.',
+    parameters: {
+      type: 'object',
+      properties: {
+        command: {
+          type: 'string',
+          description: 'Shell command to execute; runs through the default system shell',
+        },
+      },
+      required: ['command'],
+    },
+  },
+
+  read_file: {
+    description: 'Read a UTF-8 text file and return its full contents.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute or relative path to the file to read',
+        },
+      },
+      required: ['path'],
+    },
+  },
+
+  write_file: {
+    description: 'Write a file, creating it and any missing parent directories; overwrites existing content.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute or relative path to the file to write',
+        },
+        content: {
+          type: 'string',
+          description: 'Full UTF-8 text to write as the new file contents',
+        },
+      },
+      required: ['path', 'content'],
+    },
+  },
+
+  create_file: {
+    description: 'Create a new file with the given contents; identical behavior to write_file (creates parents, overwrites if present).',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute or relative path where the file should be created',
+        },
+        content: {
+          type: 'string',
+          description: 'Full UTF-8 text to write as the initial file contents',
+        },
+      },
+      required: ['path', 'content'],
+    },
+  },
+
+  append_file: {
+    description: 'Append text to the end of a file, creating it and any missing parent directories if needed.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute or relative path to the file to append to',
+        },
+        content: {
+          type: 'string',
+          description: 'UTF-8 text to append to the end of the file',
+        },
+      },
+      required: ['path', 'content'],
+    },
+  },
+
+  delete_file: {
+    description: 'Delete a single file at the given path.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute or relative path to the file to delete',
+        },
+      },
+      required: ['path'],
+    },
+  },
+
+  list_dir: {
+    description: 'List the entries of a directory, tagging each as file, directory, or symlink.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute or relative path to the directory to list; defaults to the current working directory',
+          default: '.',
+        },
+      },
+      required: [],
+    },
+  },
+
+  make_dir: {
+    description: 'Create a directory, including any missing parent directories.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute or relative path of the directory to create',
+        },
+      },
+      required: ['path'],
+    },
+  },
+
+  remove_dir: {
+    description: 'Recursively remove a directory and all of its contents.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute or relative path of the directory to remove',
+        },
+      },
+      required: ['path'],
+    },
+  },
+
+  move_file: {
+    description: 'Move or rename a file or directory; falls back to copy-then-delete across filesystems.',
+    parameters: {
+      type: 'object',
+      properties: {
+        src: {
+          type: 'string',
+          description: 'Current absolute or relative path of the file or directory to move',
+        },
+        dst: {
+          type: 'string',
+          description: 'Destination absolute or relative path; parent directories are created if missing',
+        },
+      },
+      required: ['src', 'dst'],
+    },
+  },
+
+  copy_file: {
+    description: 'Copy a file or directory recursively to a new location.',
+    parameters: {
+      type: 'object',
+      properties: {
+        src: {
+          type: 'string',
+          description: 'Absolute or relative path of the source file or directory',
+        },
+        dst: {
+          type: 'string',
+          description: 'Destination absolute or relative path; parent directories are created if missing',
+        },
+      },
+      required: ['src', 'dst'],
+    },
+  },
+
+  file_stat: {
+    description: 'Return metadata for a path: size in KB, modification time, type (file/directory/symlink), and mode.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute or relative path of the file or directory to inspect',
+        },
+      },
+      required: ['path'],
+    },
+  },
+
+  edit_file: {
+    description: 'Replace the contents of a single line in a file, identified by 1-based line number.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute or relative path of the file to edit',
+        },
+        line: {
+          type: 'integer',
+          description: '1-based line number of the line to replace',
+          minimum: 1,
+        },
+        content: {
+          type: 'string',
+          description: 'New text for the target line; trailing newline is added automatically when the file is rejoined',
+        },
+      },
+      required: ['path', 'line', 'content'],
+    },
+  },
+
+  search_files: {
+    description: 'Recursively find files whose name or relative path matches a glob pattern.',
+    parameters: {
+      type: 'object',
+      properties: {
+        pattern: {
+          type: 'string',
+          description: 'Glob pattern such as "*.ts" or "src/**/*.js"; matches against the basename when the pattern contains no slash, otherwise against the relative path',
+        },
+        dir: {
+          type: 'string',
+          description: 'Root directory to search from; defaults to the current working directory',
+          default: '.',
+        },
+      },
+      required: ['pattern'],
+    },
+  },
+
+  search_in_file: {
+    description: 'Search for a regular-expression pattern inside a file and return each matching line with its 1-based line number.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute or relative path of the file to search',
+        },
+        pattern: {
+          type: 'string',
+          description: 'JavaScript-style regular expression to match against each line',
+        },
+      },
+      required: ['path', 'pattern'],
+    },
+  },
+
+  replace_in_file: {
+    description: 'Regex-replace occurrences of a pattern in a file; returns the number of replacements made.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute or relative path of the file to modify',
+        },
+        search: {
+          type: 'string',
+          description: 'JavaScript regular-expression pattern to search for',
+        },
+        replace: {
+          type: 'string',
+          description: 'Replacement string; supports the standard $1, $2, $& back-references',
+        },
+        flags: {
+          type: 'string',
+          description: 'Regex flags, any combination of g/i/m/s/u/y; the "g" flag is added automatically if omitted',
+          default: '',
+        },
+      },
+      required: ['path', 'search', 'replace'],
+    },
+  },
+
+  get_env: {
+    description: 'Read a single environment variable from the current process and return its value (or null if unset).',
+    parameters: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description: 'Name of the environment variable to read',
+        },
+      },
+      required: ['name'],
+    },
+  },
+
+  set_env: {
+    description: 'Set an environment variable for the current agent process; does not affect the parent shell.',
+    parameters: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description: 'Name of the environment variable to set',
+        },
+        value: {
+          type: 'string',
+          description: 'Value to assign to the environment variable; defaults to an empty string',
+          default: '',
+        },
+      },
+      required: ['name'],
+    },
+  },
+
+  download: {
+    description: 'Download a URL over HTTP(S) and save it to a file in the current working directory, following redirects.',
+    parameters: {
+      type: 'object',
+      properties: {
+        url: {
+          type: 'string',
+          description: 'HTTP or HTTPS URL to download',
+        },
+      },
+      required: ['url'],
+    },
+  },
+
+  upload: {
+    description: 'Write base64-encoded content to a local file, creating any missing parent directories.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute or relative path of the destination file',
+        },
+        content: {
+          type: 'string',
+          description: 'Base64-encoded payload to decode and write as the file contents',
+        },
+      },
+      required: ['path', 'content'],
+    },
+  },
+
+  http_get: {
+    description: 'Perform an HTTP GET and return the response status code and body, truncated to a configured byte cap.',
+    parameters: {
+      type: 'object',
+      properties: {
+        url: {
+          type: 'string',
+          description: 'HTTP or HTTPS URL to fetch',
+        },
+      },
+      required: ['url'],
+    },
+  },
+
+  ask_user: {
+    description: 'Prompt the interactive user for input and return their answer; auto-answers "y" in non-TTY mode.',
+    parameters: {
+      type: 'object',
+      properties: {
+        question: {
+          type: 'string',
+          description: 'Question text to show the user; if the text contains a numbered list, it renders as a selectable menu',
+        },
+      },
+      required: ['question'],
+    },
+  },
+
+  store_memory: {
+    description: 'Persist a key/value pair to the agent\'s local memory store at ~/.semalt-ai/memory.json.',
+    parameters: {
+      type: 'object',
+      properties: {
+        key: {
+          type: 'string',
+          description: 'Memory key under which to store the value',
+        },
+        value: {
+          type: 'string',
+          description: 'Value to associate with the key; defaults to an empty string',
+          default: '',
+        },
+      },
+      required: ['key'],
+    },
+  },
+
+  recall_memory: {
+    description: 'Read a previously stored value from the local memory store by key.',
+    parameters: {
+      type: 'object',
+      properties: {
+        key: {
+          type: 'string',
+          description: 'Memory key to look up',
+        },
+      },
+      required: ['key'],
+    },
+  },
+
+  list_memories: {
+    description: 'List all keys currently present in the local memory store.',
+    parameters: {
+      type: 'object',
+      properties: {},
+      required: [],
+    },
+  },
+
+  system_info: {
+    description: 'Return information about the host: platform, arch, hostname, total/free memory, Node version, and current working directory.',
+    parameters: {
+      type: 'object',
+      properties: {},
+      required: [],
+    },
+  },
+
+  // ──────────────────────────────────────────────────────────────────
+  // Parser-wrapper tags. These are XML envelopes that carry other tool
+  // calls; they are not invocable tools themselves. Entries exist only
+  // so the TAG_REGISTRY ↔ TOOL_SPECS parity assertion in constants.js
+  // passes. Generators producing a native `tools` array MUST filter on
+  // `wrapper === true` and skip these.
+  // ──────────────────────────────────────────────────────────────────
+
+  'minimax:tool_call': {
+    wrapper: true,
+    description: 'Parser envelope for MiniMax-M2 native tool calls; contains one or more <invoke name="…"> children. Not a callable tool.',
+    parameters: { type: 'object', properties: {}, required: [] },
+  },
+
+  'qwen:tool_call': {
+    wrapper: true,
+    description: 'Parser envelope for Qwen-family native tool calls; contains an <invoke> child or a JSON {name, arguments} body. Not a callable tool.',
+    parameters: { type: 'object', properties: {}, required: [] },
+  },
+
+  tool_call: {
+    wrapper: true,
+    description: 'Parser envelope for Hermes/Qwen JSON tool calls of the form {"name":"…","arguments":{…}}. Not a callable tool.',
+    parameters: { type: 'object', properties: {}, required: [] },
+  },
+
+  function_call: {
+    wrapper: true,
+    description: 'Alternate spelling of <tool_call> used by some Qwen finetunes; same JSON body shape. Not a callable tool.',
+    parameters: { type: 'object', properties: {}, required: [] },
+  },
+
+  function: {
+    wrapper: true,
+    description: 'Parser envelope for the Qwen3-Coder XML tool-call format <function=tool_name>…</function>. The tool name travels as an =suffix on the opening tag. Not a callable tool.',
+    parameters: { type: 'object', properties: {}, required: [] },
+  },
+};
+
+module.exports = {
+  TOOL_SPECS,
+};