📐 feat: Add @librechat/dev-tools Package for Coding Tool Definitions

.github/workflows/ci.yml

@@ -194,6 +194,27 @@ jobs:
       - name: Tests
         run: npm test
 
+  dev-tools-package-tests:
+    name: Dev Tools Package Tests
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/dev-tools
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+        with:
+          node-version: 22.21.0
+          cache: npm
+          cache-dependency-path: packages/dev-tools/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Tests
+        run: npm test
+
   macos-storage-tests:
     name: macOS Storage ACL Tests
     runs-on: macos-14

README.md

@@ -17,6 +17,10 @@ Code Interpreter (internally `codeapi`, the prefix used by its env vars, images,
   development
 - **Remote Code Bridge** - Lets an operator-owned VM connect outbound and serve
   as a fenced, stateful sandbox through the `@librechat/code` worker
+- **Coding Tool Definitions** - The `@librechat/dev-tools` npm package: the
+  LLM-visible surface (canonical names, schemas, descriptions) of the
+  harness-native coding tools, shared by `@librechat/agents` and LibreChat
+  provisioning
 
 ## Architecture
 

packages/dev-tools/README.md

@@ -0,0 +1,81 @@
+# `@librechat/dev-tools`
+
+The LLM-visible surface of the harness-native coding tools: the canonical
+tool names, JSON schemas, and descriptions the model sees — `execute_code`,
+`bash_tool`, `run_tools_with_code`, `run_tools_with_bash`, `read_file`, and
+the local-engine file/edit/search tools (`read_file`, `write_file`,
+`edit_file`, `grep_search`, `glob_search`, `list_directory`,
+`compile_check`).
+
+This package is the single versioned source of truth for that surface. The
+schemas describe the execution environments this service provides, so they
+live next to the Code API rather than inside the agent harness:
+`@librechat/agents` and LibreChat (BYOM provisioning) both depend on the
+definitions without the harness owning them.
+
+## What is here
+
+| Module | Contents |
+| --- | --- |
+| `constants` | Canonical `ToolNames`, `CONTENT_AND_ARTIFACT`, and the `CODE_EXECUTION_TOOLS` / `LOCAL_CODING_TOOL_NAMES` / `LOCAL_CODING_BUNDLE_NAMES` sets |
+| `types` | `JsonSchemaType`, `ToolDefinition` (mirrors the agents SDK's `LCTool`), `AllowedCaller`, `OutcomePatch` |
+| `intent` | The intent-label contract embedded in every schema: `INTENT_PROPERTY`, `withIntent`/`withoutIntent`, arg readers/strippers, and outcome resolution |
+| `guidance` | Shared `/mnt/data` and bash guidance embedded across schemas and descriptions |
+| `timeout` | The programmatic-run `timeout` schema with environment-resolved defaults and clamping |
+| `execute-code`, `bash-tool`, `read-file` | Remote (Code API) engine tool surfaces, including the stateful and attached-workspace description/schema builders |
+| `run-tools-with-code`, `run-tools-with-bash` | Remote programmatic tool calling surfaces, including attached-workspace builders |
+| `local` | Local-engine surfaces: file/edit/search tools, `compile_check`, the local execution descriptions, and the local programmatic tool calling schemas |
+
+Zero runtime dependencies: everything is plain data and pure functions, so
+harness, host, and worker consumers pay nothing to read the schemas.
+
+## What is deliberately not here
+
+Execution. The Code API client, `ToolNode` event dispatch, the local
+execution engine, tool-result replay, and output shaping (artifact-delivery
+warnings, code-session file summaries) remain harness-native in
+`@librechat/agents`. This package answers one question: what does the LLM
+see? The sibling `@librechat/code` package answers the other side of
+provisioning — the worker that turns an operator-owned VM into a stateful,
+fenced execution environment.
+
+## Provenance
+
+Ported from `@librechat/agents` (`src/tools/`) with export-name parity so
+the harness swap is mechanical. Intentional differences:
+
+- `Constants` tool-name members became `ToolNames` (the agents enum mixes
+  orchestration constants; only the coding-tool members moved).
+- Schemas that were module-private in the harness (`CompileCheckSchema`, the
+  local programmatic tool calling schema builders) are exported here — the
+  package's purpose is sharing them.
+- Local-engine descriptions that lived inline inside tool factories are
+  first-class `Local*ToolDescription` constants.
+- `JsonSchemaType` is widened with the JSON-Schema keywords these schemas
+  use (`minLength`, `minimum`, `maximum`, `default`, `uniqueItems`) so every
+  schema type-checks as written.
+
+Every ported string was verified byte-for-byte against the harness source at
+port time; descriptions are prompt surface, so drift is behavior change.
+
+## Usage
+
+```ts
+import {
+  CodeExecutionToolDefinition,
+  LocalCodingBundleNames,
+  buildBashExecutionToolDescription,
+} from '@librechat/dev-tools';
+```
+
+Subpath exports mirror the module list above (`@librechat/dev-tools/local`,
+`@librechat/dev-tools/intent`, and so on). Tests pin the canonical names,
+required properties, intent-first property ordering, and the
+stateful/attached description builders.
+
+## Development
+
+```bash
+npm install
+npm test
+```

packages/dev-tools/package.json

@@ -0,0 +1,75 @@
+{
+    "name": "@librechat/dev-tools",
+    "version": "0.1.0",
+    "description": "LLM-visible definitions (names, schemas, descriptions) of the harness-native coding tools for LibreChat Code API",
+    "license": "Apache-2.0",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./constants": {
+            "types": "./dist/constants.d.ts",
+            "import": "./dist/constants.js"
+        },
+        "./types": {
+            "types": "./dist/types.d.ts",
+            "import": "./dist/types.js"
+        },
+        "./intent": {
+            "types": "./dist/intent.d.ts",
+            "import": "./dist/intent.js"
+        },
+        "./guidance": {
+            "types": "./dist/guidance.d.ts",
+            "import": "./dist/guidance.js"
+        },
+        "./timeout": {
+            "types": "./dist/timeout.d.ts",
+            "import": "./dist/timeout.js"
+        },
+        "./execute-code": {
+            "types": "./dist/execute-code.d.ts",
+            "import": "./dist/execute-code.js"
+        },
+        "./bash-tool": {
+            "types": "./dist/bash-tool.d.ts",
+            "import": "./dist/bash-tool.js"
+        },
+        "./read-file": {
+            "types": "./dist/read-file.d.ts",
+            "import": "./dist/read-file.js"
+        },
+        "./run-tools-with-code": {
+            "types": "./dist/run-tools-with-code.d.ts",
+            "import": "./dist/run-tools-with-code.js"
+        },
+        "./run-tools-with-bash": {
+            "types": "./dist/run-tools-with-bash.d.ts",
+            "import": "./dist/run-tools-with-bash.js"
+        },
+        "./local": {
+            "types": "./dist/local/index.d.ts",
+            "import": "./dist/local/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "!dist/*.test.*"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.json",
+        "test": "npm run build && node --test dist/*.test.js",
+        "prepack": "npm run build"
+    },
+    "devDependencies": {
+        "@types/node": "^22.5.5",
+        "typescript": "^5.5.4"
+    },
+    "engines": {
+        "node": ">=20.11"
+    }
+}