feat: Enhance tool name normalization and file handling in execution

- Added normalization functions for Python and Bash tool names to ensure compatibility with SDK-generated code.
- Updated file handling in execution services to support new metadata fields, including `inherited`, `modified_from`, and `entity_id`.
- Introduced read-only file handling during uploads, allowing for better management of file permissions in sandbox environments.
- Enhanced unit tests to cover new features and ensure robust validation of file and tool name handling.

Author: usnavy13

docker-compose.yml

@@ -13,6 +13,7 @@ services:
     # nsjail requires these capabilities to create namespaces and cgroups
     cap_add:
       - SYS_ADMIN
+      - NET_ADMIN
     security_opt:
       - apparmor:unconfined
     ports:

docker/ptc_bash_server.py

@@ -58,11 +58,51 @@
 _real_stdin = sys.stdin
 _real_stdout = sys.stdout
 
-# Bash identifier rules: [A-Za-z_][A-Za-z0-9_]*. We refuse to wrap any tool
-# whose name doesn't match — both for shell safety and because the user
-# couldn't call it from bash anyway.
+# Bash identifier rules: [A-Za-z_][A-Za-z0-9_]*. Names that don't match
+# get normalized via `_normalize_bash_name` so the user can still call the
+# tool from bash — the SDK applies the same normalization client-side when
+# generating code.
 _VALID_BASH_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
 
+_BASH_RESERVED = frozenset(
+    {
+        "if",
+        "then",
+        "else",
+        "elif",
+        "fi",
+        "case",
+        "esac",
+        "for",
+        "while",
+        "until",
+        "do",
+        "done",
+        "in",
+        "function",
+        "select",
+        "time",
+        "coproc",
+        "declare",
+        "typeset",
+        "local",
+        "readonly",
+        "export",
+        "unset",
+    }
+)
+
+
+def _normalize_bash_name(name: str) -> str:
+    """Match SDK's normalizeToBashIdentifier so generated code can call functions."""
+    result = re.sub(r"[-\s.]", "_", name)
+    result = re.sub(r"[^a-zA-Z0-9_]", "", result)
+    if result and result[0].isdigit():
+        result = "_" + result
+    if result in _BASH_RESERVED:
+        result = result + "_tool"
+    return result or "_unnamed"
+
 
 def _write_message(msg: dict) -> None:
     _real_stdout.write(json.dumps(msg) + DELIMITER)
@@ -91,24 +131,25 @@ def _generate_rcfile(tools: list) -> str:
     ]
     for tool in tools:
         name = tool.get("name", "")
-        if not _VALID_BASH_NAME.match(name):
+        func_name = _normalize_bash_name(name)
+        if not func_name or func_name == "_unnamed":
             continue
         lines.append(
-            f"{name}() {{\n"
+            f"{func_name}() {{\n"
             # Use an explicit conditional rather than ${1:-{}} — the brace-default
             # form parses as ${1:-{} followed by a literal }, which appends a
             # stray brace whenever $1 is set.
             f'    local input_json="$1"\n'
             f'    if [ -z "$input_json" ]; then input_json="{{}}"; fi\n'
             f"    local payload\n"
             f"    payload=$(jq -c -n --arg name {shlex.quote(name)} "
-            f'--argjson input "$input_json" \'{{name:$name,input:$input}}\' 2>/dev/null) || \\\n'
+            f"--argjson input \"$input_json\" '{{name:$name,input:$input}}' 2>/dev/null) || \\\n"
             f"    payload=$(jq -c -n --arg name {shlex.quote(name)} "
-            f'--arg input "$input_json" \'{{name:$name,input:$input}}\')\n'
+            f"--arg input \"$input_json\" '{{name:$name,input:$input}}')\n"
             f'    printf \'%s\\n\' "$payload" > "$PTC_CALL_FIFO"\n'
             f"    local result\n"
             f'    IFS= read -r result < "$PTC_RESULT_FIFO"\n'
-            f'    printf \'%s\\n\' "$result"\n'
+            f"    printf '%s\\n' \"$result\"\n"
             f"}}\n"
         )
     return "\n".join(lines)
@@ -216,9 +257,7 @@ def on_call_readable() -> None:
                     break
 
                 results = response.get("results", [])
-                target = next(
-                    (r for r in results if r.get("call_id") == call_id), None
-                )
+                target = next((r for r in results if r.get("call_id") == call_id), None)
                 if target is None and results:
                     target = results[0]
 

docker/ptc_server.py

@@ -26,13 +26,66 @@
 import asyncio
 import json
 import os
+import re
 import sys
 import traceback
 import uuid
 from io import StringIO
 
 DELIMITER = "\n---PTC_END---\n"
 
+_PYTHON_KEYWORDS = frozenset(
+    {
+        "False",
+        "None",
+        "True",
+        "and",
+        "as",
+        "assert",
+        "async",
+        "await",
+        "break",
+        "class",
+        "continue",
+        "def",
+        "del",
+        "elif",
+        "else",
+        "except",
+        "finally",
+        "for",
+        "from",
+        "global",
+        "if",
+        "import",
+        "in",
+        "is",
+        "lambda",
+        "nonlocal",
+        "not",
+        "or",
+        "pass",
+        "raise",
+        "return",
+        "try",
+        "while",
+        "with",
+        "yield",
+    }
+)
+
+
+def _normalize_python_name(name: str) -> str:
+    """Match SDK's normalizeToPythonIdentifier so generated code can call stubs."""
+    result = re.sub(r"[-\s]", "_", name)
+    result = re.sub(r"[^a-zA-Z0-9_]", "", result)
+    if result and result[0].isdigit():
+        result = "_" + result
+    if result in _PYTHON_KEYWORDS:
+        result = result + "_tool"
+    return result or "_unnamed"
+
+
 # Keep references to the REAL stdin/stdout for protocol communication.
 # User code's print() will be redirected to a StringIO capture buffer.
 _real_stdin = sys.stdin
@@ -83,9 +136,7 @@ async def tool_stub(**kwargs):
 
         result_info = _tool_results_map.pop(call_id)
         if result_info.get("is_error"):
-            raise RuntimeError(
-                result_info.get("error_message", "Tool call failed")
-            )
+            raise RuntimeError(result_info.get("error_message", "Tool call failed"))
         return result_info.get("result")
 
     tool_stub.__name__ = tool_name
@@ -113,7 +164,8 @@ async def _execute_with_tools(
         pass
 
     for tool in tools:
-        namespace[tool["name"]] = _make_tool_stub(tool["name"])
+        normalized = _normalize_python_name(tool["name"])
+        namespace[normalized] = _make_tool_stub(tool["name"])
 
     # Wrap user code in async function
     indented_code = "\n".join("    " + line for line in code.split("\n"))
@@ -137,10 +189,12 @@ async def _execute_with_tools(
                 calls_to_send = list(_pending_calls)
                 _pending_calls.clear()
 
-                _write_message({
-                    "type": "tool_calls",
-                    "calls": calls_to_send,
-                })
+                _write_message(
+                    {
+                        "type": "tool_calls",
+                        "calls": calls_to_send,
+                    }
+                )
 
                 # Wait for results from host
                 response = _read_message()
@@ -179,10 +233,12 @@ def main():
     try:
         request = _read_message()
     except Exception as e:
-        _write_message({
-            "type": "error",
-            "error": f"Failed to read initial request: {e}",
-        })
+        _write_message(
+            {
+                "type": "error",
+                "error": f"Failed to read initial request: {e}",
+            }
+        )
         return
 
     code = request.get("code", "")
@@ -200,9 +256,7 @@ def main():
     sys.stderr = user_stderr
 
     try:
-        result = asyncio.run(
-            _execute_with_tools(code, tools, user_stdout, user_stderr)
-        )
+        result = asyncio.run(_execute_with_tools(code, tools, user_stdout, user_stderr))
     except Exception as e:
         result = {
             "type": "error",

src/api/exec.py

@@ -40,7 +40,11 @@
 _KEEPALIVE_INTERVAL = 3
 
 
-@router.post("/exec", responses={200: {"model": ExecResponse}})
+@router.post(
+    "/exec",
+    responses={200: {"model": ExecResponse}},
+    response_model_exclude_none=True,
+)
 async def execute_code(
     request: ExecRequest,
     http_request: Request,
@@ -175,7 +179,7 @@ async def _stream_response():
             request_id=request_id,
             session_id=response.session_id,
         )
-        yield response.model_dump_json().encode()
+        yield response.model_dump_json(exclude_none=True).encode()
 
     return StreamingResponse(
         _stream_response(),

src/api/files.py

@@ -250,6 +250,13 @@ async def upload_files_batch(
     )
     is_agent_file = entity_id is not None
 
+    read_only_raw = form.get("read_only")
+    is_read_only = isinstance(read_only_raw, str) and read_only_raw.lower() in (
+        "1",
+        "true",
+        "yes",
+    )
+
     metadata = {"entity_id": entity_id} if entity_id else {}
     session = await session_service.create_session(SessionCreate(metadata=metadata))
     session_id = session.session_id
@@ -287,6 +294,7 @@ async def upload_files_batch(
                 content=content,
                 content_type=upload.content_type,
                 is_agent_file=is_agent_file,
+                is_read_only=is_read_only,
             )
 
             results.append(

src/models/exec.py

@@ -2,7 +2,7 @@
 
 # Standard library imports
 from datetime import datetime
-from typing import List, Optional, Any
+from typing import Dict, List, Optional, Any
 
 # Third-party imports
 from pydantic import BaseModel, Field
@@ -15,6 +15,9 @@ class FileRef(BaseModel):
     name: str
     path: Optional[str] = None  # Make path optional
     session_id: Optional[str] = None  # Session ID for cross-message file persistence
+    inherited: Optional[bool] = None
+    entity_id: Optional[str] = None
+    modified_from: Optional[Dict[str, str]] = None
 
 
 class RequestFile(BaseModel):
@@ -23,6 +26,7 @@ class RequestFile(BaseModel):
     id: str
     session_id: str
     name: str
+    entity_id: Optional[str] = None
 
 
 class ExecRequest(BaseModel):
@@ -55,6 +59,12 @@ class ExecRequest(BaseModel):
         default_factory=list,
         description="Array of file references to be used during execution",
     )
+    timeout: Optional[int] = Field(
+        default=None,
+        ge=1000,
+        le=300000,
+        description="Execution timeout in milliseconds",
+    )
 
 
 class ExecResponse(BaseModel):

src/models/execution.py

@@ -3,7 +3,7 @@
 # Standard library imports
 from datetime import datetime
 from enum import Enum
-from typing import List, Optional
+from typing import Any, Dict, List, Optional
 
 # Third-party imports
 from pydantic import BaseModel, Field
@@ -42,6 +42,7 @@ class ExecutionOutput(BaseModel):
         default=None, description="Size in bytes for file outputs"
     )
     timestamp: datetime = Field(default_factory=datetime.utcnow)
+    metadata: Optional[Dict[str, Any]] = None
 
 
 class CodeExecution(BaseModel):