"""Which machine a write tool call writes to, as the hooks place it.
The hooks place every hooked call before they judge it: the stdlib twin's
``hook_write_target`` (``osprey_target_state.py``) answers ``None`` for a call
that writes nothing, the session's target for an application tool, the real
machine for a facility write tool, the lane's target for a lane-addressed tool,
and the session's target for every other framework write tool. :func:`write_target_for_tool` is the package restatement
of that placement, for a surface that has to name the machine before the hook
has run — the operator chat's approval card (C-FRAME). A parity test
(``tests/hooks/test_write_target_parity.py``) pins the two against each other
for every write tool.
The placement is not the gateway role: which gateway a connector writes
through is the connector's own choice and says nothing about which machine's
switch covers the call.
:data:`KIND_BANNERS` holds the owner-facing banner for each machine kind
(C-WORDS), the words a card or chip shows beside the machine. They are not
:data:`~osprey_connectors.refusals.KIND_WORDS`, which a refusal phrase uses.
"""
from __future__ import annotations
import logging
import os
from collections.abc import Iterable, Mapping
from pathlib import Path
from typing import Literal
from osprey_connectors import control_context, posture_store
from osprey_connectors.types import (
CONTROL_TARGETS,
TARGET_LIVE,
baseline_target,
published_machine_kind,
)
__all__ = [
"KIND_BANNERS",
"UNRESOLVED",
"Unresolved",
"frame_target",
"write_target_for_tool",
]
logger = logging.getLogger(__name__)
#: The banner an owner reads beside each kind of machine (C-WORDS).
KIND_BANNERS: dict[str, str] = {
"real": "Live — writes move hardware",
"rehearsal": "Rehearsal — nothing moves",
"simulator": "Simulator — nothing moves",
}
#: The write list a deployment with no rendered ``write_tools`` falls back to.
#: Restated from the hooks' ``_FALLBACK_WRITE_TOOLS`` (``osprey_hook_log.py``):
#: this package cannot import the framework, and the hooks cannot import this
#: package. The parity test pins the two.
_FALLBACK_WRITE_TOOLS: tuple[str, ...] = (
"mcp__bluesky__queue_add",
"mcp__bluesky__queue_start",
"mcp__controls__channel_write",
"mcp__phoebus__phoebus_drive",
"mcp__python__execute",
"mcp__python__execute_file",
"mcp__python__pyaml_measure",
)
#: The suffix of a whole-server matcher, ``mcp__<server>__.*``.
_MATCHER_WILDCARD = ".*"
#: The one tool whose call may write nothing: a readonly execution.
_EXECUTE_TOOL = "execute"
#: The hook_config key naming the tools a plan lane addresses, as short names.
_LANE_ADDRESSED_KEY = "lane_addressed_tools"
#: The hook_config key naming the ``control_system.write_tools`` entries the
#: render appended to ``write_tools``: the deployment's own write tools.
_FACILITY_EXTRAS_KEY = "control_system_write_tools"
#: The hook_config key naming the facility (custom-server) write set: exact
#: names for a declaring server, ``mcp__<name>__.*`` for one with no list.
_FACILITY_WRITES_KEY = "facility_write_tools"
#: The hook_config key holding every application tool's approval declaration,
#: keyed by full tool name: an application writes to the session's target.
_APP_APPROVALS_KEY = "app_approvals"
#: The hook_config keys naming server prefixes, longest match stripped.
_PREFIX_KEYS = ("server_prefixes", "approval_prefixes")
#: The service key of the default lane, and every service key that can name a
#: lane, in render order. Restated from ``osprey.bluesky_bridge_connection``.
_LANE_ONE = "bluesky"
_LANE_KEYS = (_LANE_ONE, "bluesky_va", "bluesky_live", "bluesky_standin")
[docs]
class Unresolved:
"""A write whose machine could not be placed: one instance, compared by identity.
Distinct from ``None``, which :func:`write_target_for_tool` keeps for a call
that writes nothing. A write nobody can place is refused by the hooks,
never waved through as a read.
"""
__slots__ = ()
def __repr__(self) -> str:
return "<unresolved>"
__str__ = __repr__
#: The answer for a write whose machine cannot be placed.
UNRESOLVED = Unresolved()
def _entries(value: object) -> Iterable[object]:
"""A hook-config list as the hooks iterate it: nothing when unset or empty.
A value that does not iterate raises :class:`TypeError`, as iterating it
would, so :func:`write_target_for_tool` places that write nowhere.
"""
if not value:
return ()
if not isinstance(value, Iterable):
raise TypeError(f"a hook-config list is a {type(value).__name__}, which does not iterate")
return value
def _is_write_tool(tool_name: str, write_tools: object) -> bool:
"""Whether *tool_name* is covered by *write_tools*: exact names and ``.*`` matchers."""
for entry in _entries(write_tools):
if not isinstance(entry, str):
continue
if entry == tool_name:
return True
if entry.endswith(_MATCHER_WILDCARD) and tool_name.startswith(
entry[: -len(_MATCHER_WILDCARD)]
):
return True
return False
def _is_write_call(tool_input: object, short_name: str) -> bool:
"""Whether this call writes: only a readonly (or modeless) ``execute`` does not."""
if short_name != _EXECUTE_TOOL:
return True
if not isinstance(tool_input, Mapping):
tool_input = {}
return bool(tool_input.get("execution_mode", "readonly") != "readonly")
def _short_tool_name(tool_name: str, prefixes: Iterable[object]) -> str:
"""*tool_name* without its server prefix; the longest matching prefix wins.
With no prefix matching, the ``mcp__<server>__<tool>`` shape decides, and a
name in no MCP shape is its own short name.
"""
matched = [p for p in prefixes or () if isinstance(p, str) and tool_name.startswith(p)]
if matched:
return tool_name[len(max(matched, key=len)) :]
parts = tool_name.split("__")
if tool_name.startswith("mcp__") and len(parts) > 2:
return "__".join(parts[2:])
return tool_name
def _hook_prefixes(hook_config: Mapping[str, object]) -> list[str]:
"""Every server prefix *hook_config* names."""
prefixes: list[str] = []
for key in _PREFIX_KEYS:
value = hook_config.get(key)
if isinstance(value, list):
prefixes.extend(p for p in value if isinstance(p, str))
return prefixes
def _is_facility_tool(tool_name: str, hook_config: Mapping[str, object]) -> bool:
"""Whether *tool_name* is a write tool the deployment declared, not the framework.
The rendered ``facility_write_tools`` set, plus the ``control_system.write_tools``
entries the render appended. A render from before that key carried no exact
names, so there the whole-server matchers in ``write_tools`` are the set.
"""
declared = hook_config.get(_FACILITY_WRITES_KEY)
if isinstance(declared, list):
if _is_write_tool(tool_name, declared):
return True
else:
for entry in _entries(hook_config.get("write_tools")):
if (
isinstance(entry, str)
and entry.endswith(_MATCHER_WILDCARD)
and _is_write_tool(tool_name, [entry])
):
return True
extras = _entries(hook_config.get(_FACILITY_EXTRAS_KEY))
return tool_name in [extra for extra in extras if isinstance(extra, str)]
def _section(config: object) -> object:
return config.get("control_system") if isinstance(config, Mapping) else None
def _lane_block(config: object, lane_key: str) -> Mapping[str, object]:
services = config.get("services") if isinstance(config, Mapping) else None
block = services.get(lane_key) if isinstance(services, Mapping) else None
return block if isinstance(block, Mapping) else {}
def _rendered_lanes(config: object) -> list[tuple[str, str]]:
"""``[(lane key, the target it serves)]`` in render order; lane one always present."""
baseline = baseline_target(_section(config))
lanes: list[tuple[str, str]] = []
for key in _LANE_KEYS:
block = _lane_block(config, key)
if not block:
continue
declared = block.get("target")
lanes.append((key, declared if isinstance(declared, str) and declared else baseline))
if not any(key == _LANE_ONE for key, _ in lanes):
lanes.insert(0, (_LANE_ONE, baseline))
return lanes
def _lane_machine(config: object, tool_input: object) -> str | Unresolved:
"""The target the call's lane serves, or :data:`UNRESOLVED`."""
lanes = _rendered_lanes(config)
lane = tool_input.get("lane") if isinstance(tool_input, Mapping) else None
if not lane:
target = lanes[0][1] if len(lanes) == 1 else None
else:
target = next((served for key, served in lanes if key == lane), None)
return target if target in CONTROL_TARGETS else UNRESOLVED
def _session_machine(
config: object, record_path: Path | None, stamped: bool | None
) -> str | Unresolved:
"""The target the session is pointed at, or :data:`UNRESOLVED`.
The record's target when it is readable. With no record at all, the
baseline — but only when the agent-data root was stamped: an unstamped
process that finds no record cannot tell "nobody switched" from "looked in
the wrong place", and the hook refuses it as ``posture_unknown``.
"""
if record_path is None:
record, status = control_context.read_record_status()
else:
record, status = control_context.read_record_status(path=record_path)
if record is not None:
return record.target
if stamped is None:
stamped = posture_store.stamped_agent_data_root() is not None
if status != "missing" or not stamped:
return UNRESOLVED
return baseline_target(_section(config))
[docs]
def frame_target(
target: str | None | Unresolved,
*,
state_dir: str | os.PathLike[str] | None = None,
) -> dict[str, str] | None:
"""C-FRAME's ``target``: ``{key, machine_kind, kind_words}``, or ``None``.
``None`` for a call that writes nothing and for one that cannot be placed.
The kind is the published one (C-KIND), so a ``standin`` the controls
server has not vouched for reads as the real machine.
Args:
target: An answer of :func:`write_target_for_tool`.
state_dir: The servers' report directory; ``None`` reads this process's.
"""
if not isinstance(target, str):
return None
kind: Literal["real", "rehearsal", "simulator"] = published_machine_kind(
target, state_dir=state_dir
)
return {"key": target, "machine_kind": kind, "kind_words": KIND_BANNERS[kind]}