From 3b37a98675de5daa2c35d4cf05d30327796f48e4 Mon Sep 17 00:00:00 2001 From: yana_asadchaya Date: Wed, 30 Sep 2026 15:25:33 +0300 Subject: [PATCH 1/4] docs(config): document the workspace script tool-call bridge --- .../codemie/api-configuration.md | 1 + .../codemie/code-executor-configuration.md | 89 +++++++++++++++++++ .../codemie/customer-feature-configuration.md | 25 +++++- .../codemie/dynamic-customer-configuration.md | 13 +-- ...stomer-configuration-without-a-redeploy.md | 2 +- 5 files changed, 122 insertions(+), 8 deletions(-) diff --git a/docs/admin/configuration/codemie/api-configuration.md b/docs/admin/configuration/codemie/api-configuration.md index 502df054..6d89f8f3 100644 --- a/docs/admin/configuration/codemie/api-configuration.md +++ b/docs/admin/configuration/codemie/api-configuration.md @@ -1161,6 +1161,7 @@ Configure secure Python code execution in isolated Kubernetes pods for running u | `CODE_EXECUTOR_VERBOSE` | boolean | `false` | Enable verbose logging for executor debugging | | `CODE_EXECUTOR_KEEP_TEMPLATE` | boolean | `true` | Persist pod template after execution for performance optimization | | `CODE_EXECUTOR_SKIP_ENVIRONMENT_SETUP` | boolean | `false` | Skip environment initialization in sandbox (faster startup but may break dependencies) | +| `FEATURE_WORKSPACE_SCRIPT_BRIDGE` | boolean | unset | Overrides `enabled` of the `features:workspaceScriptBridge` customer configuration component at load time, where the component exists in the loaded `customer-config.yaml`. When `true`, workspace scripts can call the backend through `codemie_runtime_sdk` (`sandbox-jobs` mode only). Changing it requires a restart. See [Code Executor Configuration](./code-executor-configuration.md#workspace-script-tool-call-bridge). | :::warning Security Considerations **Sandbox Isolation:** `CODE_EXECUTOR_EXECUTION_MODE=sandbox` runs user-supplied code in a dedicated Kubernetes pod, isolated from the CodeMie API. This is the execution model for running untrusted code safely in production. diff --git a/docs/admin/configuration/codemie/code-executor-configuration.md b/docs/admin/configuration/codemie/code-executor-configuration.md index 5b975575..b5896ad1 100644 --- a/docs/admin/configuration/codemie/code-executor-configuration.md +++ b/docs/admin/configuration/codemie/code-executor-configuration.md @@ -102,6 +102,95 @@ extraEnv: value: "" ``` +## Workspace Script Tool-Call Bridge + +The workspace script tool-call bridge lets a script run by the execute workspace script tool send requests to the CodeMie backend while it runs. Such a script can import the `codemie_runtime_sdk` module, and its `call` function sends a named operation to the backend and returns the result. + +:::info Current limitations + +- The backend answers a single operation, `echo`, which returns the request payload unchanged. Any other operation name fails with the `unknown_op` error code. Calling CodeMie tools from scripts is not available yet. +- The bridge works in `sandbox-jobs` mode only. In `sandbox-shared` mode, and whenever the bridge is disabled, every call fails with the `unavailable` error code. + ::: + +### Enabling the Bridge + +The bridge is controlled by the `features:workspaceScriptBridge` [customer configuration](./customer-feature-configuration.md) component. It is disabled by default. + +| Setting | Default | Description | +| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `enabled` | `false` | Enables the bridge for workspace script runs. | +| `timeoutSeconds` | `120` | Time limit in seconds for a script run with the bridge. Values above `3600` are reduced to `3600`. A missing, non-numeric, or non-positive value falls back to `120`. | + +```yaml +components: + - id: "features:workspaceScriptBridge" + settings: + enabled: true + timeoutSeconds: 120 + name: "Workspace Script Bridge" + description: "Allow scripts run in the workspace sandbox to call the backend during their run" +``` + +Ways to change the settings: + +- **Administration page.** Both settings can be edited at runtime in **Settings → Administration → Customer Configuration**, under **Workspace script bridge** (switch **Enable workspace script bridge** and field **Script run limit (seconds)**). See [Dynamic Customer Configuration](./dynamic-customer-configuration.md). +- **`customer-config.yaml`.** The YAML value is the deployment default when nothing is saved on the page. A customer ConfigMap that replaces the default file needs its own copy of the component for the YAML value and for `FEATURE_WORKSPACE_SCRIPT_BRIDGE` to apply; a value saved on the administration page works without it. +- **`FEATURE_WORKSPACE_SCRIPT_BRIDGE`.** Set to `true` or `false` to override `enabled` from the YAML at load time. The override applies only where the component exists in the loaded file, and changing it requires a restart of CodeMie API. + +A saved change applies to script runs that start afterwards. The backend reads the setting on every run, and other CodeMie API instances pick up the change within `CUSTOMER_CONFIG_CACHE_TTL_SECONDS` (default: `60` seconds). + +### Run Time Limit and Capacity + +While the bridge is enabled, the deadline of the sandbox Job for every workspace script run is: + +```text +max(CODE_EXECUTOR_EXECUTION_TIMEOUT, timeoutSeconds) + 60 seconds +``` + +With the defaults (`30` and `120`), a run can last up to 180 seconds. A `timeoutSeconds` value below `CODE_EXECUTOR_EXECUTION_TIMEOUT` does not shorten a run. Without the bridge, the deadline is `CODE_EXECUTOR_EXECUTION_TIMEOUT` plus 60 seconds. + +:::warning Capacity +A run holds one executor slot until it finishes. The number of slots is set by `CODE_EXECUTOR_MAX_POD_POOL_SIZE` (default: `5`), and a request made when all slots are taken fails with a capacity error. Long runs with a high `timeoutSeconds` can exhaust the slots sooner, so the limit should stay as low as the scripts allow. +::: + +### Calling the Backend from a Script + +```python +import codemie_runtime_sdk as sdk + +reply = sdk.call("echo", {"msg": "ping"}) +print(reply) +``` + +`sdk.call(op, payload, timeout=None)` takes an operation name and a JSON-serializable dictionary, and returns the result from the backend. Calls are made one at a time from a single thread. The SDK uses the Python standard library only. + +Failures raise `ToolCallError`, whose `code` attribute identifies the reason: + +| Code | Reason | +| ------------------- | -------------------------------------------------------------------------------------------------------------- | +| `unavailable` | The bridge is disabled, the sandbox mode is `sandbox-shared`, or the backend stopped answering during the run. | +| `payload_too_large` | The request is larger than 256 KiB. | +| `timeout` | No answer arrived within `timeout` seconds (default: `100`). | +| `unknown_op` | The backend has no handler for the operation. | + +While a run is active, requests and responses are exchanged as files in a `.codemie_bridge` folder inside the script working directory. The folder is removed when the script finishes and is excluded from exported and changed files. + +```mermaid +sequenceDiagram + participant S as Workspace script + participant P as Sandbox Job pod + participant B as CodeMie API + + S->>P: Write request file + B->>P: Poll for requests + B->>P: Write response file + S->>P: Read response file + Note over S,B: Repeats while the script runs + S->>P: Script finishes + B->>P: Stop polling and remove the folder + B->>P: Download exports and changed files +``` + ## Applying CodeMie API Settings ```bash diff --git a/docs/admin/configuration/codemie/customer-feature-configuration.md b/docs/admin/configuration/codemie/customer-feature-configuration.md index a6ec0bf0..a31fc3ba 100644 --- a/docs/admin/configuration/codemie/customer-feature-configuration.md +++ b/docs/admin/configuration/codemie/customer-feature-configuration.md @@ -12,7 +12,7 @@ pagination_prev: admin/configuration/index Control which features, UI elements, and integrations are available to users in your CodeMie deployment through the `customer-config.yaml` configuration file. :::tip Runtime changes -Some components — `banner`, `chatDisclaimer`, `features:webSearch`, and `releaseNotesRecentCount` — can also be changed at runtime from **Settings → Administration → Customer Configuration** without a redeploy. The values in `customer-config.yaml` serve as their deployment defaults. See [Dynamic Customer Configuration](./dynamic-customer-configuration.md). +Some components — `banner`, `chatDisclaimer`, `features:webSearch`, `features:workspaceScriptBridge`, and `releaseNotesRecentCount` — can also be changed at runtime from **Settings → Administration → Customer Configuration** without a redeploy. The values in `customer-config.yaml` serve as their deployment defaults. See [Dynamic Customer Configuration](./dynamic-customer-configuration.md). ::: ## Component Overview @@ -39,6 +39,7 @@ Use this table to quickly find where each component appears in the UI. | **DYNAMIC TOOLS (Chat Interface)** | | | | | | `features:webSearch` | Chat → Dynamic tools settings (gear icon) | "Web Search" toggle | Web search option | If both disabled, entire section hidden. Editable at runtime | | `features:dynamicCodeInterpreter` | Chat → Dynamic tools settings (gear icon) | "Code Interpreter" toggle | Code interpreter option | If both disabled, entire section hidden | +| `features:workspaceScriptBridge` | No UI element; Settings → Administration → Customer Configuration | Workspace scripts can call the backend with `codemie_runtime_sdk` | SDK calls fail with the `unavailable` error code | Disabled by default; `sandbox-jobs` only. Editable at runtime | | **BANNER, DISCLAIMER AND RELEASE NOTES** | | | | | | `banner` | All pages (top banner) | Banner message with an optional link | No banner shown | Default: disabled. Editable at runtime | | `chatDisclaimer` | Chat → below the message input | Non-dismissible disclaimer text with clickable links | No disclaimer shown | Default: disabled. Editable at runtime | @@ -400,6 +401,21 @@ components: name: "Code Interpreter" description: "Enable Python code execution and data analysis capabilities" + # WHERE: No UI element. Settings → Administration → Customer Configuration → Workspace script bridge + # ENABLED: Scripts run by the execute workspace script tool can call the backend with codemie_runtime_sdk + # DISABLED: SDK calls fail with the `unavailable` error code + # NOTE: Disabled by default. Works in `sandbox-jobs` mode only. `timeoutSeconds` is the time limit for a script + # run with the bridge (default 120, capped at 3600); the Job deadline becomes + # max(CODE_EXECUTOR_EXECUTION_TIMEOUT, timeoutSeconds) + 60 seconds. + # Can also be toggled with FEATURE_WORKSPACE_SCRIPT_BRIDGE=true, which overrides `enabled`. + # Editable at runtime. See Code Executor Configuration. + - id: "features:workspaceScriptBridge" + settings: + enabled: false + timeoutSeconds: 120 + name: "Workspace Script Bridge" + description: "Allow scripts run in the workspace sandbox to call the backend during their run" + # WHERE: Assistants list, Skills list, Workflows list # ENABLED: Shows favorite/unfavorite action buttons on items # DISABLED: Hides favorite actions @@ -1309,6 +1325,13 @@ extraObjects: name: "Code Interpreter" description: "Enable Python code execution and data analysis capabilities" + - id: "features:workspaceScriptBridge" + settings: + enabled: false + timeoutSeconds: 120 + name: "Workspace Script Bridge" + description: "Allow scripts run in the workspace sandbox to call the backend during their run" + - id: "features:favorites" settings: enabled: true diff --git a/docs/admin/configuration/codemie/dynamic-customer-configuration.md b/docs/admin/configuration/codemie/dynamic-customer-configuration.md index 5faaac46..d84761e5 100644 --- a/docs/admin/configuration/codemie/dynamic-customer-configuration.md +++ b/docs/admin/configuration/codemie/dynamic-customer-configuration.md @@ -59,12 +59,13 @@ The deployment default is never copied into the database, so resetting never lea ## Available Dynamic Settings -| Component ID | Setting on the page | What it is | -| ------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------- | -| `chatDisclaimer` | Chat disclaimer | Short notice below the chat message input for every user | -| `banner` | Banner | Dismissible announcement across the top of the application, with an optional link | -| `features:webSearch` | Web search | Web search tools for assistants in chat (Google Search, Tavily Search, Web Scraper) | -| `releaseNotesRecentCount` | Release Notes: Recent releases count | Number of latest releases listed on the Release Notes page before older ones are grouped | +| Component ID | Setting on the page | What it is | +| -------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------- | +| `chatDisclaimer` | Chat disclaimer | Short notice below the chat message input for every user | +| `banner` | Banner | Dismissible announcement across the top of the application, with an optional link | +| `features:webSearch` | Web search | Web search tools for assistants in chat (Google Search, Tavily Search, Web Scraper) | +| `features:workspaceScriptBridge` | Workspace script bridge | Lets workspace scripts call the backend during their run, with a run time limit | +| `releaseNotesRecentCount` | Release Notes: Recent releases count | Number of latest releases listed on the Release Notes page before older ones are grouped | Deployment defaults for these components are set in `customer-config.yaml` — see the full example in [Customer Feature Configuration](./customer-feature-configuration.md#full-configuration-example). diff --git a/faq/how-do-i-change-customer-configuration-without-a-redeploy.md b/faq/how-do-i-change-customer-configuration-without-a-redeploy.md index 5160bc23..eb7974ef 100644 --- a/faq/how-do-i-change-customer-configuration-without-a-redeploy.md +++ b/faq/how-do-i-change-customer-configuration-without-a-redeploy.md @@ -2,7 +2,7 @@ Some customer configuration components can be overridden at runtime from **Settings → Administration → Customer Configuration**. The page is available to platform administrators and maintainers; project administrators do not have access. -The page lists only the components declared as dynamic: the chat disclaimer (`chatDisclaimer`), the top banner (`banner`), web search (`features:webSearch`), and the number of recent releases on the Release Notes page (`releaseNotesRecentCount`). All other components are still configured only through `customer-config.yaml`. +The page lists only the components declared as dynamic: the chat disclaimer (`chatDisclaimer`), the top banner (`banner`), web search (`features:webSearch`), the workspace script bridge (`features:workspaceScriptBridge`), and the number of recent releases on the Release Notes page (`releaseNotesRecentCount`). All other components are still configured only through `customer-config.yaml`. Each setting shows whether it is **Overridden** or **Default from config**. **Save** stores an override that takes precedence over `customer-config.yaml`; **Reset to default** removes it, so the value follows the deployment configuration again. A change applies to backend and frontend behavior within the cache interval (60 seconds by default) with no restart or redeploy. From 5444947a15162201397995f2f247fb875c1d2558 Mon Sep 17 00:00:00 2001 From: yana_asadchaya Date: Tue, 6 Oct 2026 11:50:21 +0300 Subject: [PATCH 2/4] docs(config): describe script tool calls and run limits of the bridge Generated with AI Co-Authored-By: codemie-ai --- .../codemie/api-configuration.md | 2 +- .../codemie/code-executor-configuration.md | 81 ++++++++++++++----- .../codemie/customer-feature-configuration.md | 11 ++- .../codemie/dynamic-customer-configuration.md | 2 +- 4 files changed, 69 insertions(+), 27 deletions(-) diff --git a/docs/admin/configuration/codemie/api-configuration.md b/docs/admin/configuration/codemie/api-configuration.md index 6d89f8f3..4f4fa8fe 100644 --- a/docs/admin/configuration/codemie/api-configuration.md +++ b/docs/admin/configuration/codemie/api-configuration.md @@ -1161,7 +1161,7 @@ Configure secure Python code execution in isolated Kubernetes pods for running u | `CODE_EXECUTOR_VERBOSE` | boolean | `false` | Enable verbose logging for executor debugging | | `CODE_EXECUTOR_KEEP_TEMPLATE` | boolean | `true` | Persist pod template after execution for performance optimization | | `CODE_EXECUTOR_SKIP_ENVIRONMENT_SETUP` | boolean | `false` | Skip environment initialization in sandbox (faster startup but may break dependencies) | -| `FEATURE_WORKSPACE_SCRIPT_BRIDGE` | boolean | unset | Overrides `enabled` of the `features:workspaceScriptBridge` customer configuration component at load time, where the component exists in the loaded `customer-config.yaml`. When `true`, workspace scripts can call the backend through `codemie_runtime_sdk` (`sandbox-jobs` mode only). Changing it requires a restart. See [Code Executor Configuration](./code-executor-configuration.md#workspace-script-tool-call-bridge). | +| `FEATURE_WORKSPACE_SCRIPT_BRIDGE` | boolean | unset | Overrides `enabled` of the `features:workspaceScriptBridge` customer configuration component at load time, where the component exists in the loaded `customer-config.yaml`. When `true`, workspace scripts can call CodeMie tools through `codemie_runtime_sdk` (`sandbox-jobs` mode only). Changing it requires a restart. See [Code Executor Configuration](./code-executor-configuration.md#workspace-script-tool-call-bridge). | :::warning Security Considerations **Sandbox Isolation:** `CODE_EXECUTOR_EXECUTION_MODE=sandbox` runs user-supplied code in a dedicated Kubernetes pod, isolated from the CodeMie API. This is the execution model for running untrusted code safely in production. diff --git a/docs/admin/configuration/codemie/code-executor-configuration.md b/docs/admin/configuration/codemie/code-executor-configuration.md index b5896ad1..54568ad6 100644 --- a/docs/admin/configuration/codemie/code-executor-configuration.md +++ b/docs/admin/configuration/codemie/code-executor-configuration.md @@ -104,22 +104,24 @@ extraEnv: ## Workspace Script Tool-Call Bridge -The workspace script tool-call bridge lets a script run by the execute workspace script tool send requests to the CodeMie backend while it runs. Such a script can import the `codemie_runtime_sdk` module, and its `call` function sends a named operation to the backend and returns the result. +A script run by the execute workspace script tool can call CodeMie tools while it runs. The script imports `codemie_runtime_sdk` and calls a tool by name. The CodeMie API runs the tool and returns its result to the script, so a script can, for example, read a Jira issue or a Confluence page as part of its work. :::info Current limitations -- The backend answers a single operation, `echo`, which returns the request payload unchanged. Any other operation name fails with the `unknown_op` error code. Calling CodeMie tools from scripts is not available yet. -- The bridge works in `sandbox-jobs` mode only. In `sandbox-shared` mode, and whenever the bridge is disabled, every call fails with the `unavailable` error code. +- The bridge works in `sandbox-jobs` mode only. In `sandbox-shared` mode, and whenever the bridge is disabled, scripts cannot make tool calls. +- Only tools that are opted in can be called from a script. Integration tools such as Jira, Confluence, GitHub, and GitLab are included. Platform, file system, workspace, IDE, and MCP tools are not. +- A request is limited to 256 KiB, and so is a result. A larger one fails with the `payload_too_large` error code. ::: ### Enabling the Bridge The bridge is controlled by the `features:workspaceScriptBridge` [customer configuration](./customer-feature-configuration.md) component. It is disabled by default. -| Setting | Default | Description | -| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `enabled` | `false` | Enables the bridge for workspace script runs. | -| `timeoutSeconds` | `120` | Time limit in seconds for a script run with the bridge. Values above `3600` are reduced to `3600`. A missing, non-numeric, or non-positive value falls back to `120`. | +| Setting | Default | Description | +| ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `enabled` | `false` | Enables the bridge for workspace script runs. | +| `timeoutSeconds` | `120` | Time limit in seconds for a script run with the bridge, counted from the start of the script. Values above `480` are lowered to `480`. A missing, non-numeric, or non-positive value falls back to `120`. | +| `maxParallelCalls` | `5` | Most tool calls of one run that are served at the same time. `1` serves them one after another. Values above the process-wide limit (`10` by default) are lowered to it. A missing or invalid value falls back to `5`. | ```yaml components: @@ -127,13 +129,14 @@ components: settings: enabled: true timeoutSeconds: 120 + maxParallelCalls: 5 name: "Workspace Script Bridge" - description: "Allow scripts run in the workspace sandbox to call the backend during their run" + description: "Allow scripts run in the workspace sandbox to call tools during their run" ``` Ways to change the settings: -- **Administration page.** Both settings can be edited at runtime in **Settings → Administration → Customer Configuration**, under **Workspace script bridge** (switch **Enable workspace script bridge** and field **Script run limit (seconds)**). See [Dynamic Customer Configuration](./dynamic-customer-configuration.md). +- **Administration page.** All three settings can be edited at runtime in **Settings → Administration → Customer Configuration**, under **Workspace script bridge** (switch **Enable workspace script bridge**, fields **Script run limit (seconds)** and **Parallel tool calls per run**). See [Dynamic Customer Configuration](./dynamic-customer-configuration.md). - **`customer-config.yaml`.** The YAML value is the deployment default when nothing is saved on the page. A customer ConfigMap that replaces the default file needs its own copy of the component for the YAML value and for `FEATURE_WORKSPACE_SCRIPT_BRIDGE` to apply; a value saved on the administration page works without it. - **`FEATURE_WORKSPACE_SCRIPT_BRIDGE`.** Set to `true` or `false` to override `enabled` from the YAML at load time. The override applies only where the component exists in the loaded file, and changing it requires a restart of CodeMie API. @@ -147,31 +150,67 @@ While the bridge is enabled, the deadline of the sandbox Job for every workspace max(CODE_EXECUTOR_EXECUTION_TIMEOUT, timeoutSeconds) + 60 seconds ``` -With the defaults (`30` and `120`), a run can last up to 180 seconds. A `timeoutSeconds` value below `CODE_EXECUTOR_EXECUTION_TIMEOUT` does not shorten a run. Without the bridge, the deadline is `CODE_EXECUTOR_EXECUTION_TIMEOUT` plus 60 seconds. +With the defaults (`30` and `120`), a run can last up to 180 seconds. With `timeoutSeconds` at its maximum of `480`, a run can last up to 540 seconds. A `timeoutSeconds` value below `CODE_EXECUTOR_EXECUTION_TIMEOUT` does not shorten a run. Without the bridge, the deadline is `CODE_EXECUTOR_EXECUTION_TIMEOUT` plus 60 seconds. + +Gateways between the browser and CodeMie API must keep the run's stream open for the whole run, so they must allow at least as long as the run limit (540 seconds at the maximum). :::warning Capacity A run holds one executor slot until it finishes. The number of slots is set by `CODE_EXECUTOR_MAX_POD_POOL_SIZE` (default: `5`), and a request made when all slots are taken fails with a capacity error. Long runs with a high `timeoutSeconds` can exhaust the slots sooner, so the limit should stay as low as the scripts allow. ::: -### Calling the Backend from a Script +### Calling Tools from a Script + +Use a tool from the tool list of the run. The name and arguments are the ones the tool defines. ```python import codemie_runtime_sdk as sdk -reply = sdk.call("echo", {"msg": "ping"}) -print(reply) +envelope = sdk.call_tool("", {"": ""}) +print(envelope["result"]) ``` -`sdk.call(op, payload, timeout=None)` takes an operation name and a JSON-serializable dictionary, and returns the result from the backend. Calls are made one at a time from a single thread. The SDK uses the Python standard library only. +`call_tool(name, args=None, *, timeout=None)` returns the envelope of the call: `result` holds the tool's output, and `http` (with `status` and `reason`) is present for tools that make HTTP requests. `timeout` is in seconds and defaults to `100`. -Failures raise `ToolCallError`, whose `code` attribute identifies the reason: +To run several calls together, use `call_tools`. It takes a list of dictionaries with `name` and optionally `args`, and returns a list in the same order. A call that fails is returned as a `ToolCallError` item instead of being raised, so one failure does not hide the other results. A batch holds at most 32 calls. + +```python +import codemie_runtime_sdk as sdk + +results = sdk.call_tools( + [ + {"name": "", "args": {"": ""}}, + {"name": "", "args": {"": ""}}, + ] +) +for result in results: + if isinstance(result, sdk.ToolCallError): + print(result.code, result.message) + else: + print(result["result"]) +``` -| Code | Reason | -| ------------------- | -------------------------------------------------------------------------------------------------------------- | -| `unavailable` | The bridge is disabled, the sandbox mode is `sandbox-shared`, or the backend stopped answering during the run. | -| `payload_too_large` | The request is larger than 256 KiB. | -| `timeout` | No answer arrived within `timeout` seconds (default: `100`). | -| `unknown_op` | The backend has no handler for the operation. | +A failed call raises `ToolCallError` (or, in a batch, is returned as one). Its attributes are: + +- `code`: the reason, listed below. +- `message`: a short description of the failure. +- `retryable`: `True` when repeating the call can succeed. +- `may_have_run`: `True` when the tool may already have run. A call that changes data, such as a create, update, or send, must not be repeated when this is `True` until its result has been checked. + +| Code | Meaning | Retryable | +| ----------------------------------------- | ------------------------------------------------------------------------------------------------- | --------- | +| `tool_failed` | The tool ran and raised an error. | Yes | +| `tool_blocked` | The tool is not allowed in this run. | No | +| `tool_unavailable` | The tool is not in the run's tool list, is not opted in for scripts, or has no argument schema. | No | +| `bad_arguments` | The arguments do not match the tool's schema, or the call contains an unknown field. | No | +| `payload_too_large` | The request or the result is larger than 256 KiB. | No | +| `timeout` | No answer arrived within `timeout` seconds. | Yes | +| `unavailable` | The backend stopped answering during the run, or the bridge is not available to this run. | Depends | +| `deadline_exceeded` | The run has too little time left to start the call, so the call was not started. | No | +| `internal_error` | The backend failed in an unexpected way. | Yes | +| `error` | A generic failure. | Yes | +| `bad_request`, `unknown_op`, `no_context` | The SDK call or the run's setup is wrong. These point to a deployment problem, not to the script. | No | + +Check `retryable` and `may_have_run` rather than the code alone, because `unavailable` covers both cases. While a run is active, requests and responses are exchanged as files in a `.codemie_bridge` folder inside the script working directory. The folder is removed when the script finishes and is excluded from exported and changed files. diff --git a/docs/admin/configuration/codemie/customer-feature-configuration.md b/docs/admin/configuration/codemie/customer-feature-configuration.md index a31fc3ba..3863a831 100644 --- a/docs/admin/configuration/codemie/customer-feature-configuration.md +++ b/docs/admin/configuration/codemie/customer-feature-configuration.md @@ -39,7 +39,7 @@ Use this table to quickly find where each component appears in the UI. | **DYNAMIC TOOLS (Chat Interface)** | | | | | | `features:webSearch` | Chat → Dynamic tools settings (gear icon) | "Web Search" toggle | Web search option | If both disabled, entire section hidden. Editable at runtime | | `features:dynamicCodeInterpreter` | Chat → Dynamic tools settings (gear icon) | "Code Interpreter" toggle | Code interpreter option | If both disabled, entire section hidden | -| `features:workspaceScriptBridge` | No UI element; Settings → Administration → Customer Configuration | Workspace scripts can call the backend with `codemie_runtime_sdk` | SDK calls fail with the `unavailable` error code | Disabled by default; `sandbox-jobs` only. Editable at runtime | +| `features:workspaceScriptBridge` | No UI element; Settings → Administration → Customer Configuration | Workspace scripts can call CodeMie tools with `codemie_runtime_sdk` | Tool calls from scripts are not available | Disabled by default; `sandbox-jobs` only. Editable at runtime | | **BANNER, DISCLAIMER AND RELEASE NOTES** | | | | | | `banner` | All pages (top banner) | Banner message with an optional link | No banner shown | Default: disabled. Editable at runtime | | `chatDisclaimer` | Chat → below the message input | Non-dismissible disclaimer text with clickable links | No disclaimer shown | Default: disabled. Editable at runtime | @@ -402,17 +402,19 @@ components: description: "Enable Python code execution and data analysis capabilities" # WHERE: No UI element. Settings → Administration → Customer Configuration → Workspace script bridge - # ENABLED: Scripts run by the execute workspace script tool can call the backend with codemie_runtime_sdk - # DISABLED: SDK calls fail with the `unavailable` error code + # ENABLED: Scripts run by the execute workspace script tool can call CodeMie tools with codemie_runtime_sdk + # DISABLED: Scripts cannot make tool calls # NOTE: Disabled by default. Works in `sandbox-jobs` mode only. `timeoutSeconds` is the time limit for a script - # run with the bridge (default 120, capped at 3600); the Job deadline becomes + # run with the bridge (default 120, capped at 480); the Job deadline becomes # max(CODE_EXECUTOR_EXECUTION_TIMEOUT, timeoutSeconds) + 60 seconds. + # `maxParallelCalls` is how many tool calls of one run are served at once (default 5). # Can also be toggled with FEATURE_WORKSPACE_SCRIPT_BRIDGE=true, which overrides `enabled`. # Editable at runtime. See Code Executor Configuration. - id: "features:workspaceScriptBridge" settings: enabled: false timeoutSeconds: 120 + maxParallelCalls: 5 name: "Workspace Script Bridge" description: "Allow scripts run in the workspace sandbox to call the backend during their run" @@ -1329,6 +1331,7 @@ extraObjects: settings: enabled: false timeoutSeconds: 120 + maxParallelCalls: 5 name: "Workspace Script Bridge" description: "Allow scripts run in the workspace sandbox to call the backend during their run" diff --git a/docs/admin/configuration/codemie/dynamic-customer-configuration.md b/docs/admin/configuration/codemie/dynamic-customer-configuration.md index d84761e5..ae1ed233 100644 --- a/docs/admin/configuration/codemie/dynamic-customer-configuration.md +++ b/docs/admin/configuration/codemie/dynamic-customer-configuration.md @@ -64,7 +64,7 @@ The deployment default is never copied into the database, so resetting never lea | `chatDisclaimer` | Chat disclaimer | Short notice below the chat message input for every user | | `banner` | Banner | Dismissible announcement across the top of the application, with an optional link | | `features:webSearch` | Web search | Web search tools for assistants in chat (Google Search, Tavily Search, Web Scraper) | -| `features:workspaceScriptBridge` | Workspace script bridge | Lets workspace scripts call the backend during their run, with a run time limit | +| `features:workspaceScriptBridge` | Workspace script bridge | Lets workspace scripts call CodeMie tools during their run, with a run time limit | | `releaseNotesRecentCount` | Release Notes: Recent releases count | Number of latest releases listed on the Release Notes page before older ones are grouped | Deployment defaults for these components are set in `customer-config.yaml` — see the full example in [Customer Feature Configuration](./customer-feature-configuration.md#full-configuration-example). From f67f4d04ef11c08dcd4d31e8413c46d7a054f976 Mon Sep 17 00:00:00 2001 From: yana_asadchaya Date: Tue, 6 Oct 2026 11:53:50 +0300 Subject: [PATCH 3/4] docs(user-guide): add workspace script sdk page Generated with AI Co-Authored-By: codemie-ai --- cspell.config.yaml | 1 + .../tools_integrations/tools/overview.md | 1 + .../tools/workspace-script-sdk.md | 112 ++++++++++++++++++ sidebars.ts | 1 + 4 files changed, 115 insertions(+) create mode 100644 docs/user-guide/tools_integrations/tools/workspace-script-sdk.md diff --git a/cspell.config.yaml b/cspell.config.yaml index 9d6f95dd..61b23794 100644 --- a/cspell.config.yaml +++ b/cspell.config.yaml @@ -24,6 +24,7 @@ ignorePaths: words: # Project/Brand names - HMAC + - retryable - codemie - passwordless - SAMEORIGIN diff --git a/docs/user-guide/tools_integrations/tools/overview.md b/docs/user-guide/tools_integrations/tools/overview.md index dd1d0810..159ea555 100644 --- a/docs/user-guide/tools_integrations/tools/overview.md +++ b/docs/user-guide/tools_integrations/tools/overview.md @@ -41,6 +41,7 @@ Assistant's tools are powerful enhancements that bring completely new capabiliti | **[Scheduler](./scheduler.md)** | Task scheduling and automation (Admin role only) | | **[Plugin](./plugin.md)** | Custom plugin integrations for extending assistant capabilities (e.g., file system) | | **[FileSystem](./filesystem.md)** | Code execution and file processing tools including Code Interpreter, Code Executor, and Generate Image | +| **[Workspace Script SDK](./workspace-script-sdk.md)** | Call CodeMie tools from scripts that run in a workspace, with `codemie_runtime_sdk` | | **[Git](./git-overview.md)** | Version control system integration for GitHub, GitLab, Bitbucket, and Azure DevOps repositories | | **[Azure DevOps](./azure-devops/index.md)** | Work Items, Wiki, and Test Plans management via Azure DevOps integration | | **[MS Teams Bot](./ms-teams-bot.md)** | Chat with CodeMie assistants directly from Microsoft Teams personal chats, group chats, and channels | diff --git a/docs/user-guide/tools_integrations/tools/workspace-script-sdk.md b/docs/user-guide/tools_integrations/tools/workspace-script-sdk.md new file mode 100644 index 00000000..f4a8558c --- /dev/null +++ b/docs/user-guide/tools_integrations/tools/workspace-script-sdk.md @@ -0,0 +1,112 @@ +--- +id: workspace-script-sdk +title: Workspace Script SDK +sidebar_label: Workspace Script SDK +sidebar_position: 21 +pagination_prev: null +pagination_next: null +--- + +# Workspace Script SDK + +A script that runs in a workspace can call CodeMie tools while it runs. The script imports the `codemie_runtime_sdk` module and calls a tool by name. CodeMie runs the tool and returns the result to the script, so a script can read a Jira issue or a Confluence page as part of a larger task, without the model reading every response. + +This page is for people who write scripts by hand, and for the administrator who enables the feature. The model that writes scripts gets a short reference in the script tool's description. + +:::info Availability +The feature is off by default. An administrator turns it on in **Settings → Administration → Customer Configuration → Workspace script bridge**. It works only when the code executor runs in jobs mode, which is the default. +::: + +```python +from codemie_runtime_sdk import call_tool, ToolCallError + +envelope = call_tool("generic_jira_tool", {"method": "GET", "relative_url": "/rest/api/2/myself"}) +print(envelope["http"]["status"], envelope["result"]) +``` + +--- + +## Which Tools a Script Can Call + +A script can call only the tools that are available to it in its run. Which tools those are depends on where the script runs: + +| Where the script runs | Tools the script can call | Credentials used | +| ----------------------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------- | +| A chat, or a workflow step that uses an assistant | The tools in that assistant's tool list, including attached skills | The assistant's own settings and credentials | +| A workflow tool step | Tools from the catalog, by name | The running user's integrations in the project | +| A workspace run without an assistant or workflow (through the REST API) | None. Every call fails with `no_context` | Not applicable | + +Not every tool can be called from a script. Some tools, such as the workspace script tool itself, are never callable. Tools that depend on the live chat session are not callable either. Use plain Python for file operations rather than tool calls. + +If a script asks for a tool that is not available to its run, the call fails with `tool_unavailable`. Asking for the script tool itself fails with `tool_blocked`. + +--- + +## Calling a Tool + +`call_tool(name, args=None, *, timeout=None)` calls one tool and returns its envelope: + +- `envelope["result"]` holds the tool's result. A tool that returns an object, a list, or JSON text gives the parsed value. Any other text stays a string. +- `envelope["http"]` is present only for the Jira, Confluence, GitLab, and xWiki tools. It holds `status` (the HTTP status code) and `reason`. The `result` is then the body of the third party's response. A non-2xx status is returned as data, not raised as an error, so check `status` yourself. + +The arguments are the ones the tool defines. Call the tool with the names shown in the tool list of the run. An unknown argument is refused with `bad_arguments`, not ignored, so a misspelled filter cannot silently run the tool with its defaults. + +--- + +## Several Calls at Once + +Use `call_tools` to run several independent calls together: + +```python +from codemie_runtime_sdk import call_tools, ToolCallError + +keys = ["PROJ-1", "PROJ-2", "PROJ-3"] +calls = [ + {"name": "generic_jira_tool", "args": {"method": "GET", "relative_url": f"/rest/api/2/issue/{key}"}} + for key in keys +] +for key, item in zip(keys, call_tools(calls)): + if isinstance(item, ToolCallError): + print(key, "failed:", item.code) + else: + print(key, item["result"]["fields"]["summary"]) +``` + +`call_tools(calls, *, timeout=None)` takes a list of dictionaries, each with a `name` and optionally `args`. It returns a list in the same order. A call that fails is returned as a `ToolCallError` item, not raised, so one failure does not hide the other results. + +- Up to `maxParallelCalls` calls (default `5`) run at the same time. The rest wait their turn. +- The `timeout` applies to the whole batch and never goes beyond the run's time limit. A call that is not answered in time returns a `ToolCallError` with the code `timeout`. +- A batch holds at most 32 calls. A problem with the batch itself, such as too many calls or an item without a `name`, raises `ToolCallError`. + +Put only independent calls that read data into one batch. Calls that create, update, delete, or send something, and calls that need the result of another call, should be made one at a time with `call_tool`. The calls of a batch are not ordered. + +--- + +## Errors + +A failed call raises `ToolCallError`, or returns it as an item of a batch. The error has these attributes: + +- `code`: the reason. The main codes are `tool_unavailable` (the tool is not available to this run), `bad_arguments` (the arguments do not match the tool), `tool_failed` (the tool ran and raised an error), `payload_too_large` (the request or result is over 256 KiB), `timeout` (no answer in time), and `deadline_exceeded` (too little of the run's time was left to start the call). +- `message`: a short description of the failure. +- `retryable`: `True` when repeating the same call can succeed. +- `may_have_run`: `True` when the tool may already have run before the error. A call that changes data must not be repeated while this is `True` until its result has been checked. + +Check `retryable` and `may_have_run` rather than the code alone. The code `unavailable` covers two cases: the bridge is not available to the run, in which case nothing ran, and the backend stopped answering during the run, in which case the tool may have run. + +--- + +## Limits + +| Limit | Value | +| ----------------------------- | ----------------------------------------------------------------------- | +| Wait for one call | `100` seconds by default. The `timeout` argument changes it. | +| Run time limit | `timeoutSeconds` setting: `120` seconds by default, at most `480`. | +| Calls served at the same time | `maxParallelCalls` setting: `5` by default. `1` serves them one by one. | +| Calls in one batch | At most `32`. | +| Request or result size | At most `256` KiB each. | + +Calls also share a limit across all runs of the CodeMie API, so a call may wait for a free place, and that wait counts against its time. A run's time limit applies to the whole run, including the time spent waiting for a place. + +:::tip Keep results small +Print or save what you need as you go, and print only what the user needs. Do not write raw tool results into the workspace unless the user asks for them. +::: diff --git a/sidebars.ts b/sidebars.ts index 280b15f5..012205f1 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -187,6 +187,7 @@ const sidebars: SidebarsConfig = { 'user-guide/tools_integrations/tools/xray', 'user-guide/tools_integrations/tools/plugin', 'user-guide/tools_integrations/tools/filesystem', + 'user-guide/tools_integrations/tools/workspace-script-sdk', 'user-guide/tools_integrations/tools/ms-teams-bot', { type: 'category', From 2b430c655e5a6c111ca06bdfba882e2688c194d5 Mon Sep 17 00:00:00 2001 From: yana_asadchaya Date: Tue, 6 Oct 2026 18:22:31 +0300 Subject: [PATCH 4/4] docs(user-guide): describe running a script from a workflow step Generated with AI Co-Authored-By: codemie-ai --- .../configuration/codemie/api-configuration.md | 13 +++++++------ .../tools/workspace-script-sdk.md | 10 ++++++++++ docs/user-guide/workflows/workflows-overview.md | 4 ++++ 3 files changed, 21 insertions(+), 6 deletions(-) diff --git a/docs/admin/configuration/codemie/api-configuration.md b/docs/admin/configuration/codemie/api-configuration.md index 4f4fa8fe..0a2b85c7 100644 --- a/docs/admin/configuration/codemie/api-configuration.md +++ b/docs/admin/configuration/codemie/api-configuration.md @@ -1050,12 +1050,13 @@ Automatically compress long conversation histories when token usage exceeds a th ### Workflow Configuration -| Parameter | Type | Default | Description | -| ------------------------------ | ------- | ------- | ------------------------------------------------------------------------------------- | -| `WORKFLOW_MAX_CONCURRENCY` | integer | `5` | Max simultaneous workflow executions to control resource usage | -| `WORKFLOW_DEFAULT_CONCURRENCY` | integer | `2` | Default concurrency when not specified by workflow | -| `WORKFLOW_GENERATION_ENABLED` | boolean | `false` | Enable AI-assisted workflow generation feature | -| `WORKFLOW_GENERATOR_LLM_MODEL` | string | `""` | LLM model used for workflow generation; falls back to global default model when empty | +| Parameter | Type | Default | Description | +| ------------------------------ | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `WORKFLOW_MAX_CONCURRENCY` | integer | `5` | Max simultaneous workflow executions to control resource usage | +| `WORKFLOW_DEFAULT_CONCURRENCY` | integer | `2` | Default concurrency when not specified by workflow | +| `WORKFLOW_GENERATION_ENABLED` | boolean | `false` | Enable AI-assisted workflow generation feature | +| `WORKFLOW_GENERATOR_LLM_MODEL` | string | `""` | LLM model used for workflow generation; falls back to global default model when empty | +| `WORKFLOW_RUN_FILES_MAX_COUNT` | integer | `20` | Max number of files a workflow run can start with; a request with more files is rejected with `400`. The execution request accepts at most 20 files, so a higher value has no effect | ### Sub-workflows diff --git a/docs/user-guide/tools_integrations/tools/workspace-script-sdk.md b/docs/user-guide/tools_integrations/tools/workspace-script-sdk.md index f4a8558c..665c85ce 100644 --- a/docs/user-guide/tools_integrations/tools/workspace-script-sdk.md +++ b/docs/user-guide/tools_integrations/tools/workspace-script-sdk.md @@ -26,6 +26,16 @@ print(envelope["http"]["status"], envelope["result"]) --- +## Running a Script from a Workflow Step + +A workflow can run a script as one of its steps. Add a Tool node that uses the workspace script tool (`execute_workspace_script`), set the path of the script, and attach the script file when you start the workflow. + +The execution results show what the script printed and the files it created. The output of the step can be used by the next steps like the output of any other Tool node, and the files stay available to them. If the script is not found or fails, the step is marked as failed and shows the reason or the script's output. + +A script in a Tool node can call tools by name with your integrations, see [Which Tools a Script Can Call](#which-tools-a-script-can-call). + +--- + ## Which Tools a Script Can Call A script can call only the tools that are available to it in its run. Which tools those are depends on where the script runs: diff --git a/docs/user-guide/workflows/workflows-overview.md b/docs/user-guide/workflows/workflows-overview.md index a44c5eed..fc09f9b6 100644 --- a/docs/user-guide/workflows/workflows-overview.md +++ b/docs/user-guide/workflows/workflows-overview.md @@ -163,6 +163,10 @@ File attached: filename.ext The full list of file names is also accessible via the `{{file_names}}` context variable in YAML task templates or tool arguments. +Files you attach are also placed in the workspace of the run. A Tool node that runs the workspace script tool can run an attached script, and the next steps see the files the script writes. See [Running a Script from a Workflow Step](../tools_integrations/tools/workspace-script-sdk.md#running-a-script-from-a-workflow-step). + +You can attach only files you have access to. If a file belongs to another user or no longer exists, the run does not start and an error message is shown. + :::tip Referencing a specific file Mention a file by name (e.g., `@report.pdf`) to direct a step to focus on that specific file rather than processing all attached files. :::