Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 4 additions & 5 deletions src/autoskillit/core/_tool_registry_builders.py
Original file line number Diff line number Diff line change
Expand Up @@ -306,11 +306,10 @@ def _verify_review_receipt() -> ToolDef:
)


# The single classification authority for what each run_skill parameter is
# for. Every attestation-relevant surface (the runtime gate's always-admit
# set, the actual-kwargs assembly, the execution-tuning fallback table, and
# the frozen ledger in tests/contracts/test_run_skill_kwarg_ledger.py) is
# derived from this mapping — see ToolParamRole for what each role means.
# Classification authority for run_skill runtime admission and forwarding prose.
# The gate's always-admit set, execution-tuning fallback table, and frozen ledger
# derive from this mapping; kwarg membership is ToolDef.mcp_kwarg_names.
# See ToolParamRole for what each role means.
_RUN_SKILL_PARAM_ROLES: Mapping[str, ToolParamRole] = MappingProxyType(
{
"skill_command": ToolParamRole.CHILD_INPUT,
Expand Down
21 changes: 16 additions & 5 deletions src/autoskillit/core/types/recipe/_type_recipe_binding.py
Original file line number Diff line number Diff line change
Expand Up @@ -90,11 +90,11 @@ class ToolInitializationOperation(StrEnum):


class ToolParamRole(StrEnum):
"""The single classification authority for what a tool parameter is for.
"""The classification authority for what a tool parameter is for.

The runtime attestation gate's always-admit set, the actual-kwargs
assembly, and the server-side ``RecipeStep`` fallback obligation for
execution-tuning parameters are all derived from this field. The
The runtime gate's always-admit set and ``RecipeStep`` execution-tuning
fallback obligations derive from this field; kwarg membership comes
from ``ToolDef.mcp_kwarg_names``. The
per-role runtime-admission *policy* is declared once, alongside this
enum, in ``RUNTIME_ADMISSION_BY_ROLE`` — see ``runtime_exempt_param_names``
(core/tool_registry.py) and ``bind_runtime_skill_invocation``
Expand Down Expand Up @@ -152,7 +152,11 @@ def _assert_admission_policy_total(

@dataclass(frozen=True, slots=True)
class ToolParamDef:
"""Static definition of one public MCP handler parameter."""
"""Static definition of one recipe-authorable tool parameter.

``handler_parameter=False`` denotes an orchestrator directive never sent
to the handler; ``structured_skill_inputs`` uses the separate child-input channel.
"""

name: str
wire_type: ToolWireType = ToolWireType.SCALAR
Expand Down Expand Up @@ -255,6 +259,13 @@ def param_set(self) -> frozenset[str]:
def handler_param_set(self) -> frozenset[str]:
return frozenset(param.name for param in self.params if param.handler_parameter)

@property
def mcp_kwarg_names(self) -> frozenset[str]:
"""Sole membership authority for compiled and runtime ``mcp_kwargs``."""
return self.handler_param_set - frozenset(
param.name for param in self.params if param.structured_skill_inputs
)

def param_def(self, name: str) -> ToolParamDef | None:
return next((param for param in self.params if param.name == name), None)

Expand Down
4 changes: 2 additions & 2 deletions src/autoskillit/recipe/_binding.py
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,7 @@ def _compile_tool_parameters(
hidden_inputs: frozenset[str],
ingredient_values: Mapping[str, BoundScalar] | None,
) -> tuple[list[BoundValue], list[BindingFailure]]:
"""Compile declared tool parameters in canonical registry order."""
"""Compile declared tool parameters in registry order; return only handler kwargs."""
failures: list[BindingFailure] = []
undeclared_effective_params = frozenset(effective_with) - frozenset(declared_with)
for name in sorted(undeclared_effective_params):
Expand Down Expand Up @@ -295,7 +295,7 @@ def _compile_tool_parameters(
f"tool parameter {param.name!r} expects {param.wire_type.value!r}",
)
)
return mcp_kwargs, failures
return [value for value in mcp_kwargs if value.name in tool_def.mcp_kwarg_names], failures


def _bind_run_skill_inputs(
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -187,39 +187,32 @@ def _build_actual_mcp_kwargs(
) -> dict[str, BoundScalar]:
"""Assemble the actual runtime kwargs the attestation gate checks.

Iterates ``tool_def``'s handler params only — a param declared
``handler_parameter=False`` (e.g. ``dispatch_items``) or
``structured_skill_inputs=True`` (``skill_inputs``, which has its own
dedicated channel) is excluded — and pulls each remaining param's
runtime value from ``values``, keyed by param name, which the caller
builds from the handler's locals.
Uses ``tool_def.mcp_kwarg_names`` and pulls each member's runtime value
from ``values``, keyed by param name, which the caller builds from the
handler's locals.

A param missing from ``values``, or a ``values`` key absent from the
filtered param set, is a loud construction-time bug: adding a
MCP kwarg set, is a loud construction-time bug: adding a
``ToolParamDef`` without wiring its runtime value (or vice versa) fails
the first attested call instead of silently drifting. ``None`` values
are omitted — the vacancy sentinel for optional params such as
``stale_threshold``/``idle_output_timeout`` (subsumes the prior
hand-typed ``if ... is not None`` special case).
"""
handler_param_names = frozenset(
param.name
for param in tool_def.params
if param.handler_parameter and not param.structured_skill_inputs
)
missing = handler_param_names - values.keys()
mcp_kwarg_names = tool_def.mcp_kwarg_names
missing = mcp_kwarg_names - values.keys()
if missing:
raise ValueError(
f"{tool_def.name}: no runtime value supplied for handler params: {sorted(missing)!r}"
)
unknown = values.keys() - handler_param_names
unknown = values.keys() - mcp_kwarg_names
if unknown:
raise ValueError(
f"{tool_def.name}: runtime values supplied for unknown handler params: "
f"{sorted(unknown)!r}"
)
result: dict[str, BoundScalar] = {}
for name in handler_param_names:
for name in mcp_kwarg_names:
value = values[name]
if value is not None:
result[name] = value
Expand Down
2 changes: 1 addition & 1 deletion src/autoskillit/skill_resources/arch-constraint-catalog.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ classified `REJECT` with `category: "arch_violation"`.
| Env-var-set constant consumption | `test_canonical_constant_consumption.py` | `*_ENV_FORWARD_VARS` or `*_REQUIRED_ENV` constant with zero production importers — every canonical env-var-set must be consumed |
| MCP env forward coverage | `test_mcp_env_forward_coverage.py` | `mcp_env_forward_vars` values missing from `CmdSpec.env` in any cmd-builder (skill, food-truck, headless, resume, interactive) |
| Rule severity consistency | `test_rule_severity_consistency.py` | Direct `RuleFinding()` construction in `@semantic_rule`/`@block_rule` bodies — must use `make_finding()`/`make_block_finding()`; `_KNOWN_NON_CONFORMING_RULES` entries without `# tracking: #NNNN` comments |
| Xfail bridge policy | `test_xfail_bridge_policy.py` | `xfail(strict=True)` decorators and `pytest.param` marks whose `reason` string does not cite a `#NNNN` tracking issue; `_XFAIL_POLICY_EXEMPT_FILES` entries without `# permanent:` or `# tracking:` rationale comments |
| Xfail bridge policy | `tests/arch/test_xfail_bridge_policy.py`; `tests/server/test_attested_admission_replay.py` (`_assert_admitted`) | `xfail(strict=True)` decorators and `pytest.param` marks must cite a `#NNNN` tracking issue and declare a specific `raises=` exception type (excluding `Exception`, `BaseException`, and `AssertionError`, including tuple members and `builtins`-qualified forms); class-valued matching includes subclasses, while `_assert_admitted` checks the exact rejection code and a pinned detail substring; `_XFAIL_POLICY_EXEMPT_FILES` entries need `# permanent:` or `# tracking:` rationale comments |
| No direct swap_labels in fleet | `test_swap_labels_guard.py` | Direct `swap_labels` calls in `fleet/` outside `_label_cleanup.py` — must route through `cleanup_orphaned_labels` |
| Issue URL extraction guard | `test_issue_url_extraction_guard.py` | Raw `.get("issue_url")` / `.get("issue_urls")` in `fleet/` outside `_issue_url_helpers.py` and `state_records.py` — must use `extract_issue_urls()`; `fleet_claim_guard.py` must retain both key variants |
| Pipeline ordering | `test_pipeline_ordering.py` | Moving `run_semantic_rules` before `_prune_skipped_steps` in `load_and_validate` — semantic rules must run on post-prune recipe |
Expand Down
233 changes: 233 additions & 0 deletions tests/_run_skill_caller_oracle.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,233 @@
"""Caller payload oracle and admission assertion protocol for ``run_skill`` tests.

Models the delivered ``with:`` block, the ``recipe_execution`` credential,
and the sous-chef's forwarding rules. It must never derive actual values from
the compiled template. Replay xfails use ``raises=AdmissionDefect`` to match
the class and its subclasses; the marker alone does not check a rejection's
code or detail. ``tests.server.test_attested_admission_replay._assert_admitted``
checks the exact code and pinned detail substring before raising
``AdmissionDefect``; other failures remain plain ``AssertionError`` instances.
"""

from __future__ import annotations

import re
from collections.abc import Mapping
from inspect import Parameter, signature
from typing import cast

from autoskillit.core import BoundScalar
from autoskillit.server.tools import tools_execution


class AdmissionDefect(AssertionError):
"""Raised only for a rejection matching both the pinned code and detail."""


ORCHESTRATOR_SAMPLES: Mapping[str, Mapping[str, BoundScalar]] = {
"context": {"pr_number": 7, "review_pr_number": 7},
"inputs": {"pr_number": 7, "review_pr_number": 7},
"item": {
"phase_id": "P1",
"context_path": ".autoskillit/temp/planner/run-test/assignments/ctx_P1.json",
"pr_number": "7",
"complexity": "simple",
},
}

_CONTEXT_INPUT_REF = re.compile(r"\$\{\{\s*(context|inputs)\.([^{}\s.]+)\s*\}\}")
_SINGLE_BRACE_TOKEN = re.compile(r"(?<!\{)\{([^{}]+)\}(?!\})")


def _sample_for(
samples: Mapping[str, Mapping[str, BoundScalar]], namespace: str, name: str
) -> BoundScalar:
"""Return a pinned sample or a stable path for an otherwise unknown name."""
values = samples.get(namespace)
if values is not None and name in values:
return values[name]
return f".autoskillit/temp/sample/{name}"


def _substitute_scalar(
value: BoundScalar, samples: Mapping[str, Mapping[str, BoundScalar]]
) -> BoundScalar:
"""Apply supported typed refs, then isolated item tokens, to one scalar."""
if not isinstance(value, str):
return value

exact_ref = _CONTEXT_INPUT_REF.fullmatch(value)
if exact_ref is not None:
return _sample_for(samples, exact_ref.group(1), exact_ref.group(2))

def replace_context_input(match: re.Match[str]) -> str:
return str(_sample_for(samples, match.group(1), match.group(2)))

substituted = _CONTEXT_INPUT_REF.sub(replace_context_input, value)

def replace_item(match: re.Match[str]) -> str:
return str(_sample_for(samples, "item", match.group(1).strip()))

return _SINGLE_BRACE_TOKEN.sub(replace_item, substituted)


def _declared_skill_inputs(value: object) -> dict[str, BoundScalar]:
"""Validate the scalar map declared by ``with.skill_inputs``."""
if not isinstance(value, Mapping):
raise TypeError("run_skill skill_inputs must be a mapping")
declared: dict[str, BoundScalar] = {}
for key, raw_value in value.items():
if not isinstance(key, str):
raise TypeError("run_skill skill_inputs keys must be strings")
if not isinstance(raw_value, (str, int, bool)):
raise TypeError(f"run_skill skill_inputs value for {key!r} must be a scalar")
declared[key] = raw_value
return declared


def _skill_input_shape(
step_key: str, credential: Mapping[str, object]
) -> tuple[list[str], Mapping[str, object]]:
"""Read ordered input keys and absence values from the caller credential."""
shapes_value = credential.get("skill_input_shapes")
if not isinstance(shapes_value, Mapping):
raise TypeError("recipe_execution skill_input_shapes must be a mapping")
shape_value = shapes_value.get(step_key)
if not isinstance(shape_value, Mapping):
raise AssertionError(f"step {step_key!r} has no skill input shape")
keys_value = shape_value.get("keys")
absence_values = shape_value.get("absence_values")
if not isinstance(keys_value, list):
raise TypeError(f"step {step_key!r} skill input shape keys must be strings")
if not isinstance(absence_values, Mapping):
raise TypeError(f"step {step_key!r} absence_values must be a mapping")
keys: list[str] = []
for key in keys_value:
if not isinstance(key, str):
raise TypeError(f"step {step_key!r} skill input shape keys must be strings")
keys.append(key)
return keys, absence_values


def _absence_value(step_key: str, key: str, absence_values: Mapping[str, object]) -> BoundScalar:
"""Return one advertised scalar absence value."""
value = absence_values[key]
if not isinstance(value, (str, int, bool)):
raise TypeError(f"step {step_key!r} absence value for {key!r} must be scalar")
return value


def _skill_input_payload(
step_key: str,
declared_value: object,
credential: Mapping[str, object],
samples: Mapping[str, Mapping[str, BoundScalar]],
) -> dict[str, BoundScalar]:
"""Build declared inputs in credential order with advertised absence values."""
declared = _declared_skill_inputs(declared_value)
keys, absence_values = _skill_input_shape(step_key, credential)
substituted = {key: _substitute_scalar(value, samples) for key, value in declared.items()}
result: dict[str, BoundScalar] = {}
for key in keys:
if key in substituted:
result[key] = substituted[key]
elif key in absence_values:
result[key] = _absence_value(step_key, key, absence_values)
else:
raise AssertionError(f"step {step_key!r} skill input {key!r} has no caller value")
for key, value in substituted.items():
if key not in result:
result[key] = value
return result


def build_run_skill_payload(
step_key: str,
step_body: Mapping[str, object],
credential: Mapping[str, object],
*,
cwd: str,
samples: Mapping[str, Mapping[str, BoundScalar]] = ORCHESTRATOR_SAMPLES,
) -> dict[str, object]:
"""Build one caller payload after orchestrator placeholder substitution."""
payload = literal_run_skill_payload(step_key, step_body, credential, cwd=cwd)
with_values = cast(Mapping[str, object], step_body.get("with", {}))
for name, value in with_values.items():
if name == "skill_inputs":
payload["skill_inputs"] = _skill_input_payload(step_key, value, credential, samples)
elif name in payload:
if value is None:
payload[name] = None
elif isinstance(value, (str, int, bool)):
payload[name] = _substitute_scalar(value, samples)
payload["cwd"] = cwd
return payload


def literal_run_skill_payload(
step_key: str,
step_body: Mapping[str, object],
credential: Mapping[str, object],
*,
cwd: str,
) -> dict[str, object]:
"""Build delivered ``with:`` kwargs verbatim, without template substitution."""
with_value = step_body.get("with", {})
if not isinstance(with_value, Mapping):
raise TypeError("recipe step 'with' must be a mapping")
with_values: Mapping[str, object] = with_value

parameters = signature(tools_execution.run_skill).parameters
payload: dict[str, object] = {}
for name, value in with_values.items():
if name in parameters and name != "skill_inputs":
if value is not None and not isinstance(value, (str, int, bool)):
raise TypeError(f"run_skill payload value {name!r} must be a scalar")
payload[name] = value

step_name_value = with_values.get("step_name", step_key)
if not isinstance(step_name_value, str):
raise TypeError("run_skill step_name must be a string")
execution_id = credential.get("execution_id")
if not isinstance(execution_id, str):
raise TypeError("recipe_execution execution_id must be a string")
digests_value = credential.get("invocation_template_digests")
if not isinstance(digests_value, Mapping):
raise TypeError("recipe_execution invocation_template_digests must be a mapping")
digest = digests_value.get(step_key)
if not isinstance(digest, str):
raise TypeError("recipe_execution step digest must be a string")

payload["step_name"] = step_name_value
payload["recipe_execution_id"] = execution_id
payload["invocation_template_digest"] = digest
payload["cwd"] = cwd
return payload


def run_skill_actual_mcp_kwargs(
payload: Mapping[str, object],
) -> dict[str, BoundScalar]:
"""Project payload values and signature defaults through the real MCP builder."""
parameters = signature(tools_execution.run_skill).parameters
values: dict[str, BoundScalar | None] = {}
for name, parameter in parameters.items():
if name in {"ctx", "skill_inputs"}:
continue
if name in payload:
value = payload[name]
elif parameter.default is not Parameter.empty:
value = parameter.default
else:
continue
if value is None:
values[name] = None
elif isinstance(value, (str, int, bool)):
values[name] = value
else:
raise TypeError(f"run_skill argument {name!r} must be a scalar")

tool_def = tools_execution.get_tool_def("run_skill")
if tool_def is None:
raise RuntimeError("run_skill must be a registered ToolDef")
return tools_execution._build_actual_mcp_kwargs(tool_def, values)
1 change: 1 addition & 0 deletions tests/_test_filter.py
Original file line number Diff line number Diff line change
Expand Up @@ -1355,6 +1355,7 @@ class SourceMapRejection(enum.StrEnum):
"server/test_serve_idempotence.py",
"server/test_attestation_delivery_reachability.py",
"server/test_recipe_execution_receipt_completeness.py",
"server/test_attested_admission_replay.py",
"server/test_recipe_checkpoint_delivery_regressions.py",
"server/test_tools_status_kitchen.py",
"server/test_open_kitchen_deferred_recall.py",
Expand Down
Loading
Loading