freesolo-flash-dev 1.4.18__tar.gz → 1.4.20__tar.gz

{freesolo_flash_dev-1.4.18 → freesolo_flash_dev-1.4.20}/.github/workflows/deploy-modal-dev.yml

@@ -11,9 +11,8 @@ jobs:
     name: Deploy development serving Modal app
     if: github.ref == 'refs/heads/dev'
     runs-on: ubuntu-latest
-    # same bound as the production deploy: its own readiness polls plus the remote image build fit
-    # well inside this, and a wedged job releases the runner instead of holding it for 6 hours.
-    timeout-minutes: 30
+    # Allow active GPU pools to warm before router readiness, plus image builds.
+    timeout-minutes: 90
     # github can replace a pending run even though a running deploy is preserved. compare against the
     # sha reported by the deployed app so the replacement repeats every change not actually deployed.
     concurrency:
@@ -233,7 +232,7 @@ jobs:
 
       - name: Deploy development serving
         if: steps.gate.outputs.deploy == 'true'
-        run: modal deploy --env dev flash/serving/app/modal_app.py
+        run: modal deploy --strategy rolling --env dev flash/serving/app/modal_app.py
 
       - name: Verify development serving URL
         if: steps.gate.outputs.deploy == 'true'
@@ -272,12 +271,13 @@ jobs:
           expected_deployment_id="${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
           response_file="$(mktemp)"
           trap 'rm -f "$response_file"' EXIT
-          deadline=$((SECONDS + 300))
+          # Match router startup: its full engine budget plus 60 seconds of headroom.
+          deadline=$((SECONDS + 3660))
 
           while true; do
             remaining=$((deadline - SECONDS))
             if (( remaining <= 0 )); then
-              echo "::error::Development serving custom domain did not become DNS-, TLS-, and health-ready within 300 seconds."
+              echo "::error::Development serving custom domain did not become DNS-, TLS-, and health-ready within 3660 seconds."
               exit 1
             fi
 

{freesolo_flash_dev-1.4.18 → freesolo_flash_dev-1.4.20}/.github/workflows/deploy-modal.yml

@@ -44,7 +44,7 @@ jobs:
     # accounting settlement, image builds, and a rollback with its own readiness
     # poll. The workflow contract test sums these budgets so rollback is never
     # cut off by the job timeout.
-    timeout-minutes: 180
+    timeout-minutes: 300
     # serialize serving deploys across runs because each deploy mutates the live app. github can still
     # replace a pending run, so the gate compares against the sha reported by the deployed app rather
     # than assuming every push predecessor was deployed.
@@ -325,7 +325,7 @@ jobs:
         env:
           FREESOLO_DEPLOYMENT_SHA: ${{ github.sha }}
           FREESOLO_DEPLOYMENT_ID: ${{ github.run_id }}-${{ github.run_attempt }}
-        run: modal deploy flash/serving/app/modal_app.py
+        run: modal deploy --strategy rolling flash/serving/app/modal_app.py
 
       - name: Wait for production serving readiness
         if: steps.gate.outputs.deploy == 'true'
@@ -335,12 +335,13 @@ jobs:
           expected_deployment_id="${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
           response_file="$(mktemp)"
           trap 'rm -f "$response_file"' EXIT
-          deadline=$((SECONDS + 300))
+          # Match router startup: its full engine budget plus 60 seconds of headroom.
+          deadline=$((SECONDS + 3660))
 
           while true; do
             remaining=$((deadline - SECONDS))
             if (( remaining <= 0 )); then
-              echo "::error::Production serving health check did not become ready within 300 seconds."
+              echo "::error::Production serving health check did not become ready within 3660 seconds."
               exit 1
             fi
 
@@ -462,6 +463,7 @@ jobs:
           ROLLBACK_DEPLOYMENT_ID: ${{ github.run_id }}-${{ github.run_attempt }}-rollback
           HEALTH_URL: https://serve.freesolo.co/healthz
         run: |
+          set -euo pipefail
           if [ -z "$PREVIOUS_SHA" ]; then
             echo "::error::Promotion failed and NO previous release was recorded, so the broken release is still live. Restore production manually."
             exit 1
@@ -473,6 +475,15 @@ jobs:
             exit 1
           fi
 
+          # Capture the forward dispatch contract before checkout removes its code.
+          # A bare predecessor deploy deletes new engine handles held by live routers.
+          rollback_bundle="$(mktemp -d)"
+          trap 'rm -rf "$rollback_bundle"' EXIT
+          if ! python -m flash.serving.app.rollback snapshot \
+            --source-sha "$CURRENT_SHA" --directory "$rollback_bundle"; then
+            echo "::error::Cannot preserve forward engine identities; refusing unsafe rollback."
+            exit 1
+          fi
           echo "Promotion failed; restoring ${PREVIOUS_SHA}."
           git checkout --quiet --force "$PREVIOUS_SHA"
 
@@ -504,14 +515,25 @@ jobs:
             exit 1
           fi
 
-          # the restored app must report the RESTORED sha, deployed from the restored tree.
+          # Build a compatibility artifact from the predecessor: retain forward handles,
+          # restore the predecessor's engine implementation, and gate router startup on
+          # active restored pools. Failure occurs before Modal mutates the deployment.
+          if ! python "$rollback_bundle/rollback.py" prepare \
+            --manifest "$rollback_bundle/manifest.json" --entrypoint "$rollback_app"; then
+            echo "::error::Previous release cannot retain active engine handles; refusing unsafe rollback."
+            exit 1
+          fi
+
+          # The source behavior is the predecessor; the distinct attempt identifies
+          # this rollback artifact and its forward-handle compatibility overlay.
           FREESOLO_DEPLOYMENT_SHA="$PREVIOUS_SHA" \
           FREESOLO_DEPLOYMENT_ID="$ROLLBACK_DEPLOYMENT_ID" \
-            modal deploy "$rollback_app"
+            modal deploy --strategy rolling "$rollback_app"
 
           response_file="$(mktemp)"
-          trap 'rm -f "$response_file"' EXIT
-          deadline=$((SECONDS + 300))
+          trap 'rm -f "$response_file"; rm -rf "$rollback_bundle"' EXIT
+          # Match router startup: its full engine budget plus 60 seconds of headroom.
+          deadline=$((SECONDS + 3660))
           restored=false
           while (( SECONDS < deadline )); do
             if curl --silent --show-error --output "$response_file" --fail \

{freesolo_flash_dev-1.4.18 → freesolo_flash_dev-1.4.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: freesolo-flash-dev
-Version: 1.4.18
+Version: 1.4.20
 Summary: Flash — managed LoRA post-training (SFT/GRPO) for Freesolo environments, driven by the `flash` CLI
 Project-URL: Homepage, https://github.com/freesolo-co/flash
 Project-URL: Repository, https://github.com/freesolo-co/flash

{freesolo_flash_dev-1.4.18 → freesolo_flash_dev-1.4.20}/flash/cli/scaffold/TRAINING.md

@@ -138,6 +138,62 @@ def load_environment(**kwargs) -> MyEnv:
 For tool use, dialogue, or games, subclass `EnvironmentMultiTurn` instead and drive the
 conversation across turns. The reward is the same `RewardResult` contract either way.
 
+**Native tool calling (multi-turn GRPO).** Declare the tools the model may call as
+`tool_schemas` on the environment — a list of OpenAI function declarations (the `tools` array of
+a chat request), as a class attribute or a zero-argument method. Do not render them into the system
+prompt yourself and do not parse `<tool_call>` text yourself:
+
+```python
+class RetailEnv(EnvironmentMultiTurn):
+    tool_schemas = [
+        {
+            "type": "function",
+            "function": {
+                "name": "get_order_details",
+                "description": "Look up one order by id.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"order_id": {"type": "string"}},
+                    "required": ["order_id"],
+                    "additionalProperties": False,
+                },
+            },
+        }
+    ]
+
+    def step_episode(self, example, messages, assistant_response):
+        turn = messages[-1]  # {"role": "assistant", "content": ..., "tool_calls": [...]}
+        replies = [
+            {
+                "role": "tool",
+                "tool_call_id": call["id"],
+                "name": call["function"]["name"],
+                "content": run_tool(
+                    call["function"]["name"], json.loads(call["function"]["arguments"])
+                ),
+            }
+            for call in turn.get("tool_calls", [])
+        ]
+        return EnvironmentStepResult(done=not replies, messages=tuple(replies))
+```
+
+- Declarations are validated exactly as a serving chat request's `tools` are (closed object schemas
+  with `"additionalProperties": false`, no `strict`); a malformed one fails at load.
+- Flash renders them with the chat template's own `tools=` into the first prompt, every
+  generation prefix, and the glue for every environment reply, so the policy trains on exactly the
+  prompt serving renders for the same conversation (and that SFT renders for a row's `tools`).
+- After each turn Flash parses the text with the serving tool-call parser. `messages[-1]` is the
+  OpenAI assistant message: `content` is the text before the call (`""` when none) and
+  `tool_calls[].function.arguments` is a JSON string. `assistant_response` stays the raw text, so
+  for a call it no longer equals `messages[-1]["content"]`. Text that is not a well-formed call of a
+  declared tool stays plain `content` with no `tool_calls`, as serving would return it.
+- Reply with `{"role": "tool", "tool_call_id": ..., "name": ..., "content": ...}` messages (and/or
+  `user` messages); the template renders them in its native tool-response format. Only environment
+  replies carry these fields — the initial prompt stays role/content.
+- Supported on text-only multi-turn GRPO. Single-turn and image-bearing runs with `tool_schemas`
+  are refused at startup, as are `[train].stop_sequences` that overlap the tool-call grammar. A
+  dataset row may also carry `tools` (as SFT rows do), but it must equal `tool_schemas`.
+
 If the environment class can return image-bearing user observations from `step_episode`, declare
 `image_observations = True` on that class. This is a class capability, not a TOML setting: Flash uses
 it to reject a text-only model before model work. Set it only for environments that
@@ -971,8 +1027,10 @@ is never killed for being slow.
 ### `credit_assignment = "per_turn"` is inert unless your environment emits `per_turn_rewards`
 
 **First, check that per-turn credit is available to you at all.** It is supported on the
-pure multi-turn rollout path — an `EnvironmentMultiTurn` that drives its own turn loop. A
-multi-turn environment that exposes **tools** is not supported at all: the worker raises
+pure multi-turn rollout path — an `EnvironmentMultiTurn` that drives its own turn loop
+(including one that declares native `tool_schemas` and executes the calls in `step_episode`). An
+environment whose **callables Flash would execute** (trl-style function calling) is not supported
+at all: the worker raises
 `verl grpo does not support openai function-calling tool environments; this env reports
 is_tool_env` and the run dies at startup. Nothing catches this earlier —
 `flash train --dry-run` accepts the config, because the check depends on the environment

freesolo_flash_dev-1.4.20/flash/content/processor.py

@@ -0,0 +1,37 @@
+"""Normalize chat-template metadata from a checkpoint's own processor and tokenizer."""
+
+from typing import Any
+
+
+def inherit_tokenizer_chat_template(processor: Any) -> None:
+    """Support checkpoints that publish their template only in tokenizer_config.json.
+
+    Transformers loads that template onto the tokenizer but not AutoProcessor.
+    Preserve explicit processor templates and never substitute another model's tokenizer.
+    Missing templates remain missing so the normal request validation can reject them.
+    """
+    if getattr(processor, "chat_template", None) is None:
+        tokenizer = getattr(processor, "tokenizer", None)
+        template = getattr(tokenizer, "chat_template", None)
+        if template is not None:
+            processor.chat_template = template
+
+
+def processor_template_kwargs(processor: Any, kwargs: dict[str, Any]) -> dict[str, Any]:
+    """Keep rendering options out of Transformers' legacy processor-kwargs path.
+
+    Serving renders text only: vLLM processes the decoded images separately. Options
+    unused by the selected Jinja template (often preserve_thinking) must not be
+    interpreted as image/tokenization options. Keep tools, an explicit HF argument.
+    Use HF's cached introspection so the classification matches its warning check.
+    """
+    from transformers.utils.chat_template_utils import _get_template_variables
+
+    template = getattr(processor, "chat_template", None)
+    if isinstance(template, dict):
+        template = template.get("default")
+    if not isinstance(template, str):
+        # Let the processor report missing/ambiguous template metadata as usual.
+        return kwargs
+    variables = _get_template_variables(template)
+    return {key: value for key, value in kwargs.items() if key == "tools" or key in variables}

freesolo_flash_dev-1.4.20/flash/content/training_template.py

@@ -0,0 +1,16 @@
+"""Chat-template options shared by supervised and reinforcement learning."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def training_template_kwargs(thinking: bool, tools: list[dict[str, Any]] | None) -> dict[str, Any]:
+    """Shared chat-template options for SFT rows and RL prompts and reply glue.
+
+    Tools are normalized wire declarations. Omit the key for tool-free renders.
+    """
+    kwargs: dict[str, Any] = {"enable_thinking": thinking, "preserve_thinking": False}
+    if tools is not None:
+        kwargs["tools"] = tools
+    return kwargs

{freesolo_flash_dev-1.4.18 → freesolo_flash_dev-1.4.20}/flash/core/catalog.py

@@ -543,7 +543,7 @@ MODELS["Qwen/Qwen3.5-9B-Base"] = replace(
     display_name="Qwen3.5 9B Base (pretrained)",
     managed_revision="68c46c4b3498877f3ef123c856ecfde50c39f404",
     serving=ServingCapacity(
-        gpu="H100",
+        gpu="L40S",
         serve_model_id="Qwen/Qwen3.5-9B-Base",
         max_loras=16,
         max_cpu_loras=16,
@@ -556,7 +556,8 @@ MODELS["Qwen/Qwen3.5-9B-Base"] = replace(
     ),
     notes="Pretrained-only Qwen3.5 9B; bf16 LoRA SFT/GRPO. Uses its own weights and "
     "tokenizer, not the post-trained 9B. Native chat/thinking formatting is available for "
-    "fine-tuning; instruction following and reasoning are not post-trained. BF16 serving on H100.",
+    "fine-tuning; instruction following and reasoning are not post-trained. Hosted FP8 serving "
+    "on L40S; customer-owned BF16 serving on H100.",
 )
 
 

{freesolo_flash_dev-1.4.18 → freesolo_flash_dev-1.4.20}/flash/engine/profiling/sft_tools.py

@@ -12,8 +12,11 @@ from __future__ import annotations
 
 from typing import Any
 
+from flash.content.training_template import training_template_kwargs as sft_template_kwargs
 from flash.serve.request.tool_calls import normalize_tools, tools_wire
 
+__all__ = ["reject_image_row_tools", "sft_row_tools", "sft_template_kwargs"]
+
 
 def sft_row_tools(example) -> list[dict[str, Any]] | None:
     """The row's tools in the form serving renders them, or None when it declares none."""
@@ -25,19 +28,6 @@ def sft_row_tools(example) -> list[dict[str, Any]] | None:
         raise ValueError(f"sft tools: {exc}") from exc
 
 
-def sft_template_kwargs(thinking: bool, tools: list[dict[str, Any]] | None) -> dict[str, Any]:
-    """Chat-template kwargs for every training view of a row.
-
-    The transcript, the prompt boundary, the reasoning probe and the loss mask's field probe all
-    render with these, so the supervised tokens are located in exactly the text that is trained on.
-    Without tools this is the pre-existing thinking-only render.
-    """
-    kwargs: dict[str, Any] = {"enable_thinking": thinking, "preserve_thinking": False}
-    if tools is not None:
-        kwargs["tools"] = tools
-    return kwargs
-
-
 def reject_image_row_tools(example, *, image_bearing: bool) -> None:
     """Refuse tools on an image row before any tokenizer or processor is resolved.
 

{freesolo_flash_dev-1.4.18 → freesolo_flash_dev-1.4.20}/flash/engine/worker/train/core/child/glue.py

@@ -17,8 +17,17 @@ from flash.content.image_descriptors import MAX_IMAGES_PER_CONVERSATION
 from flash.content.reasoning_normalization import (
     messages_for_chat_template as _messages_for_chat_template,
 )
+from flash.content.training_template import training_template_kwargs
+from flash.engine.worker.train.core.child.tool_messages import (
+    TOOL_MESSAGE_KEYS,
+    template_tool_messages,
+    tool_message_fields,
+)
 
 _ALLOWED_MESSAGE_KEYS = frozenset({"role", "content", "reasoning_content"})
+# the processor glue path renders without tools, and a tool environment's images would need it to
+# render with them; refuse rather than glue a reply whose declarations silently disappeared.
+_TOOL_IMAGE_REPLY_ERROR = "environment replies with images are not supported for tool environments"
 _PROBE_PREFIX = "flash-env-glue-probe"
 # the media block types verl's own dataset parser substitutes for a placeholder, and the exact set
 # it then extracts (rl_dataset.py `_build_messages`: `<image>`/`<video>`/`<audio>` become blocks of
@@ -122,7 +131,36 @@ def content_block_text(content, *, source: str, position: int) -> str:
     return "".join(parts)
 
 
-def validate_structured_messages(messages: list[dict], *, source: str) -> list[dict]:
+def _message_metadata(message: dict, *, source: str, position: int, tools: bool) -> dict:
+    """the validated non-content fields one transcript message keeps.
+
+    ``tools`` admits the openai tool-call fields, and only for an environment that declares tools:
+    without them the template cannot render a call natively, so a tool-free transcript keeps
+    rejecting them rather than training on a turn the model never saw.
+    """
+    allowed = _ALLOWED_MESSAGE_KEYS | TOOL_MESSAGE_KEYS if tools else _ALLOWED_MESSAGE_KEYS
+    extras = sorted(key for key in message if key not in allowed)
+    if extras:
+        raise ValueError(
+            f"{source} message {position} carries unsupported transcript metadata {extras}; "
+            "tool names, call ids, tool calls, and other message fields cannot be represented "
+            "in a role/content multi-turn transcript"
+        )
+    role = message.get("role")
+    reasoning = message.get("reasoning_content")
+    if not isinstance(role, str) or not role.strip():
+        raise ValueError(f"{source} message {position} has an invalid role")
+    if "reasoning_content" in message and not isinstance(reasoning, str):
+        raise ValueError(f"{source} message {position} reasoning_content must be text")
+    metadata = {"reasoning_content": reasoning} if reasoning is not None else {}
+    if tools:
+        metadata.update(tool_message_fields(message, source=source, position=position))
+    return metadata
+
+
+def validate_structured_messages(
+    messages: list[dict], *, source: str, tools: bool = False
+) -> list[dict]:
     """validate and canonicalize role/content messages without dropping media placement."""
     if not isinstance(messages, list):
         raise ValueError(f"{source} messages must be a list")
@@ -130,21 +168,12 @@ def validate_structured_messages(messages: list[dict], *, source: str) -> list[d
     for position, message in enumerate(messages):
         if not isinstance(message, dict):
             raise ValueError(f"{source} message {position} must be an object")
-        extras = sorted(key for key in message if key not in _ALLOWED_MESSAGE_KEYS)
-        if extras:
-            raise ValueError(
-                f"{source} message {position} carries unsupported transcript metadata {extras}; "
-                "tool names, call ids, tool calls, and other message fields cannot be represented "
-                "in a role/content multi-turn transcript"
-            )
-        role = message.get("role")
+        metadata = _message_metadata(message, source=source, position=position, tools=tools)
+        role = message["role"]
         content = message.get("content")
-        reasoning = message.get("reasoning_content")
-        if not isinstance(role, str) or not role.strip():
-            raise ValueError(f"{source} message {position} has an invalid role")
-        if "reasoning_content" in message and not isinstance(reasoning, str):
-            raise ValueError(f"{source} message {position} reasoning_content must be text")
-        metadata = {"reasoning_content": reasoning} if reasoning is not None else {}
+        if content is None and "tool_calls" in metadata:
+            # an openai assistant turn that only calls tools may carry null content.
+            content = ""
         if isinstance(content, str):
             normalized.append({"role": role, "content": content, **metadata})
             continue
@@ -190,7 +219,7 @@ def validate_structured_messages(messages: list[dict], *, source: str) -> list[d
 
 
 def validate_transcript_messages(
-    messages: list[dict], *, source: str, allow_content_blocks: bool = False
+    messages: list[dict], *, source: str, allow_content_blocks: bool = False, tools: bool = False
 ) -> list[dict]:
     """require the exact role/content transcript shape the child rollout loops can represent.
 
@@ -206,30 +235,19 @@ def validate_transcript_messages(
     for position, message in enumerate(messages):
         if not isinstance(message, dict):
             raise ValueError(f"{source} message {position} must be an object")
-        extras = sorted(key for key in message if key not in _ALLOWED_MESSAGE_KEYS)
-        if extras:
-            raise ValueError(
-                f"{source} message {position} carries unsupported transcript metadata {extras}; "
-                "tool names, call ids, tool calls, and other message fields cannot be represented "
-                "in a role/content multi-turn transcript"
-            )
-        role = message.get("role")
+        metadata = _message_metadata(message, source=source, position=position, tools=tools)
+        role = message["role"]
         content = message.get("content")
-        reasoning = message.get("reasoning_content")
-        if not isinstance(role, str) or not role.strip():
-            raise ValueError(f"{source} message {position} has an invalid role")
-        if "reasoning_content" in message and not isinstance(reasoning, str):
-            raise ValueError(f"{source} message {position} reasoning_content must be text")
+        if content is None and "tool_calls" in metadata:
+            # an openai assistant turn that only calls tools may carry null content.
+            content = ""
         if allow_content_blocks and isinstance(content, list):
             # a multimodal prompt arrives as content BLOCKS, not a string; flatten to the text this
             # transcript can represent. the media rides separately as decoded pixels.
             content = content_block_text(content, source=source, position=position)
         elif not isinstance(content, str):
             raise ValueError(f"{source} message {position} content must be text for multi-turn")
-        normalized_message = {"role": role, "content": content}
-        if reasoning is not None:
-            normalized_message["reasoning_content"] = reasoning
-        normalized.append(normalized_message)
+        normalized.append({"role": role, "content": content, **metadata})
     return normalized
 
 
@@ -268,25 +286,36 @@ def dedup_seam_terminator(response_ids: list[int], glue_ids: list[int]) -> list[
 class EnvGlueTokenizer:
     """derive exact inter-turn glue without re-rendering accepted transcript history."""
 
-    def __init__(self, tokenizer, *, thinking: bool, cache_size: int = 8192) -> None:
+    def __init__(
+        self,
+        tokenizer,
+        *,
+        thinking: bool,
+        tools: list[dict] | None = None,
+        cache_size: int = 8192,
+    ) -> None:
         self.tokenizer = tokenizer
         self.thinking = bool(thinking)
+        self.tools = tools
         self.cache_size = int(cache_size)
         self.cache: dict[str, list[int]] = {}
 
     def __call__(self, env_messages: list[dict]) -> list[int]:
-        messages = validate_transcript_messages(env_messages, source="environment reply")
+        messages = validate_transcript_messages(
+            env_messages, source="environment reply", tools=self.tools is not None
+        )
         key = json.dumps(messages, sort_keys=True, separators=(",", ":"))
         cached = self.cache.get(key)
         if cached is not None:
             return list(cached)
         probe = _unique_glue_probe(messages)
         text = self.tokenizer.apply_chat_template(
-            _messages_for_chat_template(_glue_conversation(probe, messages)),
+            template_tool_messages(
+                _messages_for_chat_template(_glue_conversation(probe, messages))
+            ),
             add_generation_prompt=True,
             tokenize=False,
-            enable_thinking=self.thinking,
-            preserve_thinking=False,
+            **training_template_kwargs(self.thinking, self.tools),
         )
         first = text.find(probe)
         if first == -1 or text.find(probe, first + len(probe)) != -1:
@@ -580,16 +609,22 @@ def parent_environment_glue(
     package_root: str | None,
     *,
     thinking: bool,
+    tools: list[dict] | None = None,
 ) -> tuple[list[int], list[str]]:
     """derive the authenticated parent copy of one reply's glue and ordered image digests."""
-    structured = validate_structured_messages(messages, source="environment reply")
+    structured = validate_structured_messages(
+        messages, source="environment reply", tools=tools is not None
+    )
     if not image_descriptors:
         transcript = validate_transcript_messages(
             structured,
             source="environment reply",
             allow_content_blocks=True,
+            tools=tools is not None,
         )
-        return EnvGlueTokenizer(tokenizer, thinking=thinking)(transcript), []
+        return EnvGlueTokenizer(tokenizer, thinking=thinking, tools=tools)(transcript), []
+    if tools is not None:
+        raise ValueError(_TOOL_IMAGE_REPLY_ERROR)
     if processor is None:
         raise ValueError("environment reply carries images but the parent has no processor")
     from flash.content.multimodal import decode_image_descriptors
@@ -625,9 +660,10 @@ class EnvironmentReplyGlue:
 class EnvGlueProcessor:
     """derive text or processor-aware environment glue and decode only newly transported images."""
 
-    def __init__(self, loop_self, *, thinking: bool) -> None:
+    def __init__(self, loop_self, *, thinking: bool, tools: list[dict] | None = None) -> None:
         self.loop_self = loop_self
-        self.text = EnvGlueTokenizer(loop_self.tokenizer, thinking=thinking)
+        self.tools = tools
+        self.text = EnvGlueTokenizer(loop_self.tokenizer, thinking=thinking, tools=tools)
         self.apply_chat_template_kwargs = dict(
             getattr(loop_self, "apply_chat_template_kwargs", {}) or {}
         )
@@ -640,15 +676,19 @@ class EnvGlueProcessor:
         image_data_uris: list[str] | None = None,
     ) -> EnvironmentReplyGlue:
         image_data_uris = list(image_data_uris or ())
-        structured = validate_structured_messages(messages, source="environment reply")
+        tools = self.tools is not None
+        structured = validate_structured_messages(messages, source="environment reply", tools=tools)
         _validate_reply_image_count(structured, image_data_uris)
         if not image_data_uris:
             text_messages = validate_transcript_messages(
                 structured,
                 source="environment reply",
                 allow_content_blocks=True,
+                tools=tools,
             )
             return EnvironmentReplyGlue(self.text(text_messages), [], [])
+        if tools:
+            raise ValueError(_TOOL_IMAGE_REPLY_ERROR)
         processor = getattr(self.loop_self, "processor", None)
         if processor is None:
             raise ValueError("environment reply carries images but the rollout has no processor")
@@ -673,9 +713,9 @@ class EnvGlueProcessor:
             raise
 
 
-def validate_glue_template(tokenizer, *, thinking: bool) -> None:
+def validate_glue_template(tokenizer, *, thinking: bool, tools: list[dict] | None = None) -> None:
     """fail before rollout when assistant content cannot round-trip through the template."""
-    EnvGlueTokenizer(tokenizer, thinking=thinking)(
+    EnvGlueTokenizer(tokenizer, thinking=thinking, tools=tools)(
         [{"role": "user", "content": "flash multi-turn glue validation"}]
     )
 
@@ -848,12 +888,16 @@ class EpisodePrompt:
         return snapshot
 
 
-async def prepare_episode_prompt(loop_self, raw_prompt) -> EpisodePrompt:
+async def prepare_episode_prompt(
+    loop_self, raw_prompt, *, tools: list[dict] | None = None
+) -> EpisodePrompt:
     """extract media and ids before building the canonical structured prompt view.
 
     order matters: an image prompt arrives as content blocks, so the media and block-rendered ids
     must be captured before structured validation. the canonical view preserves media placement for
     bridge authentication and rejects unsupported blocks and message metadata before rollout.
+    ``tools`` reaches verl's native ``tools=`` render, the same declarations the parent froze the
+    prompt ids with, so a tool environment's first prompt matches serving's.
     """
     messages = [dict(message) for message in raw_prompt]
     for message in messages:
@@ -877,6 +921,7 @@ async def prepare_episode_prompt(loop_self, raw_prompt) -> EpisodePrompt:
     mm_processor_kwargs = loop_self._get_mm_processor_kwargs(audios)
     prompt_ids = await loop_self.ct_build_initial_tokens(
         messages,
+        tools=tools,
         images=images,
         videos=videos,
         audios=audios,

freesolo_flash_dev-1.4.20/flash/engine/worker/train/core/child/tool_messages.py

@@ -0,0 +1,63 @@
+"""OpenAI tool-call message fields in a multi-turn transcript for an environment that declares tools.
+
+An environment without tools keeps the role/content transcript and its rejection of every other
+field. One that declares tools renders them natively, the way serving does, so its transcript may
+also carry the two shapes serving accepts in history: an assistant turn's ``tool_calls`` and a
+tool result's ``tool_call_id``/``name``. Only those fields, on those roles, are admitted here; the
+call arguments stay the JSON string the wire carries, and are decoded into the mapping the chat
+template iterates only at render time, exactly as serving's ``detached_template_messages`` does.
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+TOOL_MESSAGE_KEYS = frozenset({"tool_calls", "tool_call_id", "name"})
+
+
+def _call_text(value, *, source: str, position: int, field: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"{source} message {position} {field} must be a nonempty string")
+    return value
+
+
+def tool_message_fields(message: dict, *, source: str, position: int) -> dict[str, Any]:
+    """the validated tool fields one message carries, or {} when it carries none.
+
+    ``tool_calls`` belongs to an assistant turn and ``tool_call_id``/``name`` to a tool result,
+    matching serving's ``validate_tool_history``; on any other role they are rejected rather than
+    carried, because the template would silently drop them. Call validation is shared with serving;
+    full-history validation cannot run here because a rollout validates calls before results exist.
+    """
+    role = message.get("role")
+    fields: dict[str, Any] = {}
+    if message.get("tool_calls") is not None:
+        if role != "assistant":
+            raise ValueError(f"{source} message {position} tool_calls require the assistant role")
+        from flash.serve.request.tool_calls import validate_tool_calls
+
+        try:
+            validate_tool_calls(message["tool_calls"], message_index=position)
+        except ValueError as error:
+            raise ValueError(f"{source} {error}") from error
+        fields["tool_calls"] = deepcopy(message["tool_calls"])
+    for key in ("tool_call_id", "name"):
+        if message.get(key) is None:
+            continue
+        if role != "tool":
+            raise ValueError(f"{source} message {position} {key} requires the tool role")
+        fields[key] = _call_text(message[key], source=source, position=position, field=key)
+    return fields
+
+
+def template_tool_messages(messages: list[dict]) -> list[dict]:
+    """decode call arguments into the mapping the qwen template iterates, as serving does."""
+    if not any(message.get("tool_calls") for message in messages):
+        return messages
+    from flash.serve.request.tool_calls import detached_template_messages
+
+    return detached_template_messages(messages)
+
+
+__all__ = ["TOOL_MESSAGE_KEYS", "template_tool_messages", "tool_message_fields"]