Implementation Plan: T5-P5-A5-WP1 Define the Typed Failure Envelope and Factory Helpers (#4106)

## Summary

Add `ToolFailureEnvelope` TypedDict with a `retriable` discriminator and
two factory helpers (`server_failure_envelope`,
`input_failure_envelope`) to `src/autoskillit/server/tools/_types.py`.
This provides a typed contract for structured failure responses that
downstream P5-A4 WPs will consume, enabling orchestrator routing based
on retriability. The new type is intentionally distinct from the
existing `_kitchen_failure_envelope` function in `tools_kitchen.py` —
that function returns a raw JSON string with a `kitchen` field; this
TypedDict provides a typed dict contract with a `retriable`
discriminator.


## Implementation Plan

Plan file:
`/home/talon/projects/autoskillit-runs/impl-20260613-032734-695911/.autoskillit/temp/make-plan/t5-p5-a5-wp1-define-typed-failure-envelope_plan_2026-06-13_033600.md`

Closes #4038

🤖 Generated with [Claude Code](https://claude.com/claude-code) via
AutoSkillit
<!-- autoskillit:pipeline-signature
steps=prepare_pr,run_arch_lenses,compose_pr,annotate_pr_diff,review_pr
-->

## Token Usage Summary

| Step | Model | count | uncached | output | cache_read | peak_ctx |
turns | cache_write | time |

|------|-------|-------|----------|--------|------------|----------|-------|-------------|------|
| plan* | opus[1m] | 1 | 49 | 7.9k | 748.5k | 74.9k | 26 | 75.6k | 9m 7s
|
| verify* | sonnet | 1 | 52 | 8.2k | 217.3k | 49.0k | 17 | 28.1k | 3m 1s
|
| implement* | MiniMax-M3 | 1 | 1.3M | 5.1k | 0 | 0 | 43 | 0 | 2m 31s |
| audit_impl* | sonnet | 1 | 44 | 6.2k | 166.0k | 41.6k | 11 | 26.7k |
3m 26s |
| prepare_pr* | MiniMax-M3 | 1 | 150.3k | 1.7k | 0 | 0 | 10 | 0 | 37s |
| compose_pr* | MiniMax-M3 | 1 | 211.8k | 1.2k | 0 | 0 | 11 | 0 | 41s |
| **Total** | | | 1.6M | 30.4k | 1.1M | 74.9k | | 130.5k | 19m 26s |

\* *Step used a non-Anthropic provider; caching behavior may differ.*

## Token Efficiency

| Step | LoC Changed | cache_read/LoC | cache_write/LoC | output/LoC |
|------|-------------|----------------|-----------------|------------|
| plan | 0 | — | — | — |
| verify | 0 | — | — | — |
| implement | 132 | 0.0 | 0.0 | 38.9 |
| audit_impl | 0 | — | — | — |
| prepare_pr | 0 | — | — | — |
| compose_pr | 0 | — | — | — |
| **Total** | **132** | 8574.3 | 988.7 | 230.0 |

## Model Usage Breakdown

| Model | steps | uncached | output | cache_read | cache_write | time |
|-------|-------|----------|--------|------------|-------------|------|
| opus[1m] | 1 | 49 | 7.9k | 748.5k | 75.6k | 9m 7s |
| sonnet | 2 | 96 | 14.5k | 383.3k | 54.9k | 6m 28s |
| MiniMax-M3 | 3 | 1.6M | 8.0k | 0 | 0 | 3m 50s |

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: Trecek

src/autoskillit/server/tools/AGENTS.md

@@ -9,7 +9,7 @@ MCP `@mcp.tool()` handlers registered on import (20 tool modules).
 | `__init__.py` | Docstring-only — tools register via `@mcp.tool()` on import |
 | `_auto_overrides.py` | Shared `_build_auto_overrides()` factory for server-authoritative ingredient injection |
 | `_cancellation_shield.py` | `_cancellation_shield` decorator — catches `asyncio.CancelledError` at MCP tool boundary, returns structured JSON |
-| `_types.py` | TypedDict definitions for server tool JSON responses (RunSkillResult, RunCmdResult, etc.) |
+| `_types.py` | TypedDict definitions for server tool JSON responses (RunSkillResult, RunCmdResult, ToolFailureEnvelope, etc.) and failure envelope factory helpers |
 | `tools_kitchen.py` | `open_kitchen`, `close_kitchen` (gate lifecycle), `recipe://` MCP resource |
 | `tools_config.py` | `configure_fleet`, `configure_order` (session config overlay) |
 | `tools_agents.py` | `unlock_agent_pack` tool + `agent://` resource templates |

src/autoskillit/server/tools/_types.py

@@ -7,7 +7,7 @@
 
 from __future__ import annotations
 
-from typing import Any, TypedDict
+from typing import Any, Literal, TypedDict
 
 from autoskillit.core import ModelTotalEntry, RetryReason
 
@@ -20,6 +20,9 @@
     "TimingSummaryResult",
     "KitchenStatusResult",
     "DispatchEnvelopeResult",
+    "ToolFailureEnvelope",
+    "server_failure_envelope",
+    "input_failure_envelope",
 ]
 
 
@@ -190,3 +193,53 @@ class DispatchEnvelopeResult(TypedDict, total=False):
     error: str
     user_visible_message: str
     details: dict[str, Any] | None
+
+
+class _ToolFailureEnvelopeRequired(TypedDict):
+    """Required fields for the structured failure envelope."""
+
+    success: Literal[False]
+    error: str
+    stage: str
+    retriable: bool
+
+
+class ToolFailureEnvelope(_ToolFailureEnvelopeRequired, total=False):
+    """Typed failure envelope with retriable discriminator for orchestrator routing.
+
+    Distinct from ``_kitchen_failure_envelope`` in tools_kitchen.py which returns
+    a raw JSON string with a ``kitchen`` field. This TypedDict provides a typed
+    dict contract with a ``retriable`` discriminator for P5-A4 orchestrator routing.
+    """
+
+    user_visible_message: str
+
+
+def server_failure_envelope(
+    exc: BaseException,
+    stage: str,
+) -> ToolFailureEnvelope:
+    """Build a failure envelope for server/infrastructure errors (retriable=True)."""
+    return ToolFailureEnvelope(
+        success=False,
+        error=f"{type(exc).__name__}: {exc}",
+        stage=stage,
+        retriable=True,
+        user_visible_message=(
+            f"Server error during {stage}: {type(exc).__name__}. "
+            "This may be transient — the orchestrator may retry."
+        ),
+    )
+
+
+def input_failure_envelope(
+    message: str,
+    stage: str,
+) -> ToolFailureEnvelope:
+    """Build a failure envelope for input/validation errors (retriable=False)."""
+    return ToolFailureEnvelope(
+        success=False,
+        error=message,
+        stage=stage,
+        retriable=False,
+    )

tests/server/AGENTS.md

@@ -131,7 +131,7 @@ Server tool handler unit tests — kitchen, execution, CI, clone, workspace tool
 | `test_tools_status_mcp_response.py` | Tests for MCP response tracking integration in tools_status handlers |
 | `test_tools_status_quota_and_db.py` | Tests for server status tools: quota events, telemetry writing, and DB access |
 | `test_tools_status_summaries.py` | Tests for server status tools: token and timing summaries |
-| `test_tools_types_module.py` | Tests for server/tools/_types.py TypedDict imports |
+| `test_tools_types_module.py` | Tests for server/tools/_types.py TypedDict imports and failure envelope factory functions |
 | `test_tools_workspace.py` | Tests for autoskillit server workspace tools |
 | `test_tools_agents.py` | Tests for agent pack registry, MCP resources, and `unlock_agent_pack` |
 | `test_track_response_size.py` | Tests for the track_response_size decorator in autoskillit.server._notify |

tests/server/test_tools_types_module.py

@@ -65,3 +65,76 @@ def test_model_total_entry_still_in_core(self):
         from autoskillit.core.types._type_results import ModelTotalEntry
 
         assert "model" in ModelTotalEntry.__required_keys__
+
+
+class TestToolFailureEnvelope:
+    """Verify ToolFailureEnvelope TypedDict and factory helpers."""
+
+    def test_tool_failure_envelope_importable(self):
+        from autoskillit.server.tools._types import ToolFailureEnvelope
+
+        assert "success" in ToolFailureEnvelope.__required_keys__
+
+    def test_tool_failure_envelope_required_keys(self):
+        from autoskillit.server.tools._types import ToolFailureEnvelope
+
+        expected = {"success", "error", "stage", "retriable"}
+        assert expected <= ToolFailureEnvelope.__required_keys__
+
+    def test_tool_failure_envelope_optional_keys(self):
+        from autoskillit.server.tools._types import ToolFailureEnvelope
+
+        assert "user_visible_message" in ToolFailureEnvelope.__optional_keys__
+
+    def test_tool_failure_envelope_success_type(self):
+        import typing
+
+        from autoskillit.server.tools._types import ToolFailureEnvelope
+
+        hints = typing.get_type_hints(ToolFailureEnvelope)
+        assert typing.get_args(hints["success"]) == (False,)
+
+    def test_server_failure_envelope_factory(self):
+        from autoskillit.server.tools._types import server_failure_envelope
+
+        result = server_failure_envelope(ValueError("boom"), "init")
+        assert result["success"] is False
+        assert result["retriable"] is True
+        assert result["stage"] == "init"
+        assert "ValueError" in result["error"]
+        assert "boom" in result["error"]
+
+    def test_input_failure_envelope_factory(self):
+        from autoskillit.server.tools._types import input_failure_envelope
+
+        result = input_failure_envelope("bad input", "validate")
+        assert result["success"] is False
+        assert result["retriable"] is False
+        assert result["stage"] == "validate"
+        assert result["error"] == "bad input"
+
+    def test_server_failure_envelope_user_visible_message(self):
+        from autoskillit.server.tools._types import server_failure_envelope
+
+        result = server_failure_envelope(RuntimeError("oops"), "startup")
+        assert "user_visible_message" in result
+        assert len(result["user_visible_message"]) > 0
+
+    def test_tool_failure_envelope_in_all(self):
+        from autoskillit.server.tools._types import __all__ as types_all
+
+        assert "ToolFailureEnvelope" in types_all
+        assert "server_failure_envelope" in types_all
+        assert "input_failure_envelope" in types_all
+
+    def test_tool_failure_envelope_distinct_from_kitchen_envelope(self):
+        from autoskillit.server.tools._types import ToolFailureEnvelope
+        from autoskillit.server.tools.tools_kitchen import (
+            _kitchen_failure_envelope,
+        )
+
+        assert "retriable" in ToolFailureEnvelope.__required_keys__
+        all_keys = ToolFailureEnvelope.__required_keys__ | ToolFailureEnvelope.__optional_keys__
+        assert "kitchen" not in all_keys
+        result = _kitchen_failure_envelope(ValueError("x"), "test")
+        assert isinstance(result, str)