refactor: no comments left - one-line module docstrings, contracts on public fields only; jobs/job.py; example config and README

src/beaver_gateway/mcp/redacting.py

@@ -1,26 +1,7 @@
-"""Redact credentials on the way out of an MCP tool.
+"""Redact credentials in MCP tool output before it reaches the model.
 
-A tool result is a wider channel than the log. It goes straight into the
-model's context, from there into the turn record in Postgres, and from
-there into the markdown transcript in ``💬 чаты`` — which Obsidian Sync
-carries off the machine. One ``komodo`` deploy returns the resolved
-compose file, ``environment:`` block and all, so a single call can put
-every secret of a stack into all four places at once.
-
-One filter, not a list of exceptions: every MCP the model can reach is
-built into a ``FastMCP`` by :mod:`beaver_gateway.mcp.internal_app` —
-``python_tool`` bundles like komodo, stdio subprocesses, remote HTTP
-servers — and every route into one of them runs its middleware chain.
-That covers the per-namespace ``/mcp/<name>/`` mounts claude-code talks
-to, the ``/mcp/all`` bundle, the external MCP frontend reverse-proxying
-into both, and the Raycast backend's direct ``call_tool``. A new MCP in
-``config.py`` is covered the day it is added, without anyone
-remembering to list it here.
-
-What this does not reach: tools that never touch a FastMCP server — the
-gateway's own ``gateway`` tools, and everything claude-code runs inside
-its own process (``Bash``, ``Read``). Those are guarded by
-:mod:`beaver_gateway.agents.policy` and the vault mounts instead.
+Covers every MCP route; in-process tools like ``Bash``/``Read`` are
+guarded separately by ``agents.policy``.
 """
 
 from __future__ import annotations
@@ -69,6 +50,12 @@ class RedactingMiddleware(Middleware):
         context: MiddlewareContext[mt.CallToolRequestParams],
         call_next: CallNext[mt.CallToolRequestParams, ToolResult],
     ) -> ToolResult:
+        """Mask the result.
+
+        A non-``None`` ``meta`` on the masked copy takes the
+        ``CallToolResult`` path that skips output-schema validation,
+        since masked structured content may no longer match it.
+        """
         result = await call_next(context)
         content = [_redact_block(block) for block in result.content]
         structured = redact_data(result.structured_content)
@@ -77,9 +64,5 @@ class RedactingMiddleware(Middleware):
         return ToolResult(
             content=content,
             structured_content=structured,
-            # Masked structured content no longer has to satisfy the
-            # tool's output schema; a non-None meta takes the
-            # ``CallToolResult`` path that skips that validation, the
-            # same trick ``ResponseLimitingMiddleware`` uses.
             meta=result.meta if result.meta is not None else {},
         )