Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
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: 8 additions & 1 deletion docs/recipes/authoring.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ The rule families live in `src/autoskillit/recipe/rules_*.py` (28 files):
| `rules_features.py` | Feature-flag gating rules: steps that reference features not declared in `requires_packs` |
| `rules_fixing.py` | Fixing/Rectify workflow rules: rectify loops missing a terminal success route |
| `rules_graph.py` | Step graph reachability and cycle detection |
| `rules_inputs.py` | Ingredient/version validation — required ingredients are present, types are correct |
| `rules_inputs.py` | Ingredient/version validation — required ingredients are present, types are correct; `typed-skill-input-undeclared-source` checks dynamic typed inputs. Capture `type: integer` means canonical ASCII decimal text. |
| `rules_isolation.py` | Workspace isolation breaches: `source-isolation-violation` and `git-mutation-on-source` |
| `rules_merge.py` | `merge_worktree` routing completeness — every `MergeFailedStep` value must have a route |
| `rules_packs.py` | Unknown pack names in `requires_packs`; packs required by dispatched skill categories or by direct tool steps' food-truck visibility missing from `requires_packs` |
Expand All @@ -97,6 +97,13 @@ The rule families live in `src/autoskillit/recipe/rules_*.py` (28 files):

The semantic-rule catalog is defined by the rule modules under `recipe/rules/`.

`typed-skill-input-undeclared-source` is an advisory warning about producer
declarations. Runtime admission checks the input's actual value independently:
integer skill inputs accept JSON integers (excluding booleans), or canonical ASCII
decimal text from exact context or ingredient references, even without an integer
producer declaration. Malformed text is rejected regardless of the declaration.
A capture declared `type: integer` also validates its output when it is captured.

## Contract cards

Every skill referenced by a recipe carries a **contract card** in
Expand Down
2 changes: 2 additions & 0 deletions src/autoskillit/core/__init__.pyi
Original file line number Diff line number Diff line change
Expand Up @@ -514,6 +514,7 @@ from .types import BROKER_AUTHORITY_STATUSES as BROKER_AUTHORITY_STATUSES
from .types import CALLER_SOVEREIGN_INGREDIENTS as CALLER_SOVEREIGN_INGREDIENTS
from .types import CAMPAIGN_ID_ENV_VAR as CAMPAIGN_ID_ENV_VAR
from .types import CANONICAL_ACCOUNTING_FIELDS as CANONICAL_ACCOUNTING_FIELDS
from .types import CANONICAL_INTEGER_DIGITS as CANONICAL_INTEGER_DIGITS
from .types import CANONICAL_LAUNCH_DIGEST_FIELDS as CANONICAL_LAUNCH_DIGEST_FIELDS
from .types import CAPTURE_VALID_VALUE_TYPES as CAPTURE_VALID_VALUE_TYPES
from .types import CATEGORY_TAGS as CATEGORY_TAGS
Expand Down Expand Up @@ -1444,6 +1445,7 @@ from .types import extract_skill_name as extract_skill_name
from .types import fleet_error as fleet_error
from .types import group_by_pair as group_by_pair
from .types import hookdef_session_scope as hookdef_session_scope
from .types import is_canonical_integer_text as is_canonical_integer_text
from .types import is_canonical_plugin_artifact_digest as is_canonical_plugin_artifact_digest
from .types import (
is_canonical_plugin_artifact_incarnation_id as is_canonical_plugin_artifact_incarnation_id,
Expand Down
18 changes: 14 additions & 4 deletions src/autoskillit/core/types/recipe/_type_capture.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,24 @@
from typing import Literal, TypeGuard

__all__ = [
"CANONICAL_INTEGER_DIGITS",
"CAPTURE_VALID_VALUE_TYPES",
"CaptureEntrySpec",
"CaptureValueType",
"CaptureValueTypeError",
"is_capture_value_type",
"is_canonical_integer_text",
"resolve_payload_field",
]

_RESULT_REF_RE = re.compile(r"^\$\{\{\s*result\.([\w-]+)\s*\}\}$")
CANONICAL_INTEGER_DIGITS = 19
_CANONICAL_INTEGER_TEXT = re.compile(rf"0|-?[1-9][0-9]{{0,{CANONICAL_INTEGER_DIGITS - 1}}}")


def is_canonical_integer_text(value: str) -> bool:
"""Return whether text is an ASCII decimal integer within the wire digit limit."""
return _CANONICAL_INTEGER_TEXT.fullmatch(value) is not None


def resolve_payload_field(entry: CaptureEntrySpec) -> str | None:
Expand All @@ -36,9 +45,9 @@ def resolve_payload_field(entry: CaptureEntrySpec) -> str | None:
return m.group(1) if m else None


CAPTURE_VALID_VALUE_TYPES = frozenset({"path", "url", "string", "optional_string"})
CAPTURE_VALID_VALUE_TYPES = frozenset({"path", "url", "string", "optional_string", "integer"})

CaptureValueType = Literal["path", "url", "string", "optional_string"]
CaptureValueType = Literal["path", "url", "string", "optional_string", "integer"]


def is_capture_value_type(value: str) -> TypeGuard[CaptureValueType]:
Expand All @@ -53,11 +62,12 @@ class CaptureEntrySpec:
Attributes:
from_: The ``${{ result.<field_name> }}`` template string — what was previously
the plain string value in the ``dict[str, str]`` capture spec.
value_type: One of ``path``, ``url``, ``string``, ``optional_string``.
value_type: A declared capture type. ``integer`` means canonical ASCII
decimal text decoded by integer skill inputs.
"""

from_: str
value_type: Literal["path", "url", "string", "optional_string"]
value_type: CaptureValueType

def __post_init__(self) -> None:
if not self.from_ or not self.from_.strip():
Expand Down
4 changes: 4 additions & 0 deletions src/autoskillit/core/types/recipe/_type_recipe_binding.py
Original file line number Diff line number Diff line change
Expand Up @@ -349,6 +349,10 @@ def absent(cls, name: str) -> BoundValue:
def is_present(self) -> bool:
return self.state is BoundValueState.PRESENT

@property
def is_dynamic(self) -> bool:
return bool(self.context_dependencies or self.input_dependencies)


class BindingFailureCode(StrEnum):
UNKNOWN_TOOL = "unknown_tool"
Expand Down
10 changes: 10 additions & 0 deletions src/autoskillit/fleet/_capture.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
CaptureValueType,
CaptureValueTypeError,
get_logger,
is_canonical_integer_text,
is_capture_value_type,
resolve_payload_field,
)
Expand Down Expand Up @@ -58,6 +59,15 @@ def _validate_capture_value(key: str, value: str, declared_type: str) -> None:

Raises CaptureValueTypeError if validation fails.
"""
if declared_type == "integer":
if not is_canonical_integer_text(value):
raise CaptureValueTypeError(
key=key,
value=value,
declared_type=declared_type,
reason="integer value must be canonical ASCII decimal text",
)
return
if declared_type == "optional_string":
return
if declared_type not in ("path", "string", "url"):
Expand Down
18 changes: 7 additions & 11 deletions src/autoskillit/recipe/_binding.py
Original file line number Diff line number Diff line change
Expand Up @@ -285,7 +285,7 @@ def _compile_tool_parameters(
)
value = _bound_value(param.name, declared, resolved)
mcp_kwargs.append(value)
unresolved = bool(value.context_dependencies or value.input_dependencies)
unresolved = value.is_dynamic
if not unresolved and not _wire_value_is_valid(resolved, param):
failures.append(
_failure(
Expand Down Expand Up @@ -565,10 +565,6 @@ def bind_recipe(
return RecipeBindingProjection(invocations)


def _is_dynamic_binding(value: BoundValue) -> bool:
return bool(value.context_dependencies or value.input_dependencies)


def _undeclared_runtime_param_message(tool_def: ToolDef, undeclared_names: list[str]) -> str:
"""Denial text for undeclared non-empty runtime tool parameters.

Expand Down Expand Up @@ -712,17 +708,17 @@ def _bind_runtime_skill_values(
"recipe_execution_contract_mismatch",
f"compiled skill input {value.name!r} is absent from the runtime contract",
)
if not input_def.accepts(actual):
admitted = input_def.admit_runtime_wire(actual, value)
if admitted is None:
raise RuntimeBindingError(
"recipe_execution_input_type",
f"runtime skill input {value.name!r} expects {input_def.type!r}",
"recipe_execution_input_type", input_def.wire_mismatch_message(actual, value)
)
if not _is_dynamic_binding(value) and actual != value.effective_value:
if not value.is_dynamic and admitted != value.effective_value:
raise RuntimeBindingError(
"recipe_execution_static_input_mismatch",
f"static skill input {value.name!r} differs from the template",
)
bound_inputs.append((value.name, actual))
bound_inputs.append((value.name, admitted))
return tuple(bound_inputs)


Expand All @@ -738,7 +734,7 @@ def _validate_runtime_mcp_values(
f"compiled tool parameter {value.name!r} is absent",
)
actual = actual_mcp_kwargs[value.name]
if not _is_dynamic_binding(value) and actual != value.effective_value:
if not value.is_dynamic and actual != value.effective_value:
raise RuntimeBindingError(
"recipe_execution_static_tool_mismatch",
f"static tool parameter {value.name!r} differs from the template",
Expand Down
4 changes: 2 additions & 2 deletions src/autoskillit/recipe/_binding_input.py
Original file line number Diff line number Diff line change
Expand Up @@ -370,7 +370,7 @@ def _inline_skill_inputs(
bound_declared, bound_effective = pair
value = _bound_value(input_def.name, bound_declared, bound_effective)
bound.append(value)
unresolved = bool(value.context_dependencies or value.input_dependencies)
unresolved = value.is_dynamic
if not unresolved and not _skill_value_is_valid(bound_effective, input_def):
failures.append(
_failure(
Expand Down Expand Up @@ -476,7 +476,7 @@ def _structured_skill_inputs(
optional_context_refs=optional_context_refs,
)
bound.append(value)
unresolved = bool(value.context_dependencies or value.input_dependencies)
unresolved = value.is_dynamic
if not unresolved and not _skill_value_is_valid(resolved, input_def):
failures.append(
_failure(
Expand Down
54 changes: 46 additions & 8 deletions src/autoskillit/recipe/contracts/_contracts_types.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,14 @@
import regex as re

from autoskillit.core import (
CANONICAL_INTEGER_DIGITS,
EXTERNAL_EFFECT_CHOICES,
VALID_EXTERNAL_EFFECTS,
BoundScalar,
BoundValue,
BoundValueOrigin,
PreflightKind,
is_canonical_integer_text,
)

_CONTEXT_REF_RE = re.compile(r"\$\{\{\s*context\.([A-Za-z_]\w*)\s*\}\}")
Expand All @@ -20,6 +24,11 @@
RESULT_CAPTURE_RE = re.compile(r"\$\{\{\s*result\.([\w-]+)\s*\}\}")


_TEXT_INPUT_TYPES = frozenset({"str", "string", "optional_string"})
_PATH_INPUT_TYPES = frozenset({"file_path", "file_path_list", "directory_path"})
_EXACT_REFERENCE_ORIGINS = frozenset({BoundValueOrigin.CONTEXT, BoundValueOrigin.RECIPE_INPUT})


@dataclasses.dataclass(frozen=True, slots=True)
class SkillInput:
name: str
Expand All @@ -46,14 +55,7 @@ def has_absence_value(self) -> bool:

def accepts(self, value: object) -> bool:
normalized = self.type
if normalized in {
"str",
"string",
"optional_string",
"file_path",
"file_path_list",
"directory_path",
}:
if normalized in _TEXT_INPUT_TYPES | _PATH_INPUT_TYPES:
return isinstance(value, str)
if normalized == "integer":
return isinstance(value, int) and not isinstance(value, bool)
Expand All @@ -63,6 +65,42 @@ def accepts(self, value: object) -> bool:
return isinstance(value, bool)
return False

def admit_runtime_wire(self, value: BoundScalar, bound: BoundValue) -> BoundScalar | None:
"""Return the bound value, or None when the declared type rejects its wire form."""
if self.accepts(value):
return value
if bound.origin not in _EXACT_REFERENCE_ORIGINS:
return None
if self.type == "integer":
if isinstance(value, str) and is_canonical_integer_text(value):
return int(value)
return None
if self.type not in _TEXT_INPUT_TYPES or not isinstance(value, int):
return None
if isinstance(value, bool):
text = "true" if value else "false"
elif abs(value) < 10**CANONICAL_INTEGER_DIGITS:
text = str(value)
else:
return None
return None if text == bound.absence_value else text

def wire_mismatch_message(self, value: BoundScalar, bound: BoundValue) -> str:
message = (
f"runtime skill input {self.name!r} expects {self.type!r}; "
f"received {type(value).__name__}"
)
if self.type == "integer":
message += "; send a JSON integer"
if bound.origin in _EXACT_REFERENCE_ORIGINS:
message += (
" or canonical ASCII decimal text"
f" (e.g. '31'; at most {CANONICAL_INTEGER_DIGITS} digits)"
)
elif self.type in _TEXT_INPUT_TYPES:
message += "; send a JSON string"
return message


@dataclasses.dataclass
class SkillOutput:
Expand Down
83 changes: 83 additions & 0 deletions src/autoskillit/recipe/rules/rules_inputs.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

from __future__ import annotations

from collections.abc import Iterator

import regex as re
from packaging.version import Version

Expand All @@ -11,17 +13,20 @@
CONFIG_AUTHORITY_KEYS,
SKILL_TOOLS,
BindingFailureCode,
BoundValue,
BoundValueOrigin,
Severity,
get_logger,
)
from autoskillit.recipe._analysis import ValidationContext, bfs_reachable
from autoskillit.recipe.contracts import (
SkillInput,
get_skill_contract,
load_bundled_manifest,
)
from autoskillit.recipe.io import iter_steps_with_context
from autoskillit.recipe.registry import RuleFinding, make_finding, semantic_rule
from autoskillit.recipe.schema import Recipe

logger = get_logger(__name__)

Expand Down Expand Up @@ -130,6 +135,84 @@ def _check_invalid_skill_invocation_binding(
return findings


def _typed_dynamic_inputs(
ctx: ValidationContext, step_name: str
) -> Iterator[tuple[BoundValue, SkillInput]]:
if ctx.recipe.steps[step_name].tool not in SKILL_TOOLS:
return
invocation = ctx.binding_projection.for_step(step_name)
if invocation is None or invocation.skill_name is None:
return
contract = get_skill_contract(invocation.skill_name, load_bundled_manifest())
if contract is None:
return
for input_def in contract.inputs:
bound = invocation.skill_input(input_def.name)
if (
bound is not None
and bound.is_present
and bound.is_dynamic
and input_def.type in {"integer", "boolean", "bool"}
):
yield bound, input_def


def _has_declared_integer_source(recipe: Recipe, bound: BoundValue, input_def: SkillInput) -> bool:
if input_def.type != "integer":
return False
if bound.origin is BoundValueOrigin.RECIPE_INPUT:
ingredient = recipe.ingredients.get(bound.input_dependencies[0])
return ingredient is not None and ingredient.type == "integer"
if bound.origin is BoundValueOrigin.CONTEXT:
variable = bound.context_dependencies[0]
producers = [
step
for step in recipe.steps.values()
if variable in step.capture or variable in step.capture_list
]
return bool(producers) and all(
variable in step.capture and step.capture[variable].value_type == "integer"
for step in producers
)
return False


@semantic_rule(
name="typed-skill-input-undeclared-source",
description="Dynamic integer skill inputs need declared sources; booleans need literals.",
severity=Severity.WARNING,
)
def _check_typed_skill_input_sources(ctx: ValidationContext) -> list[RuleFinding]:
findings: list[RuleFinding] = []
for step_name in sorted(ctx.recipe.steps):
for bound, input_def in _typed_dynamic_inputs(ctx, step_name):
if _has_declared_integer_source(ctx.recipe, bound, input_def):
continue
if input_def.type == "integer":
reason = "has no supported declared integer source"
remedy = (
"Bind an exact ${{ context.X }} whose producers declare "
"scalar capture type: integer (capture_list does not qualify), "
"or an exact ${{ inputs.X }} with ingredient type: integer; "
"interpolated templates do not qualify."
)
else:
reason = "uses an unsupported dynamic boolean source"
remedy = "Bind a boolean literal; no boolean producer declaration is supported."
findings.append(
make_finding(
rule_name="typed-skill-input-undeclared-source",
step_name=step_name,
message=(
f"Step {step_name!r} input {bound.name!r} from "
f"{bound.declared_value!r} {reason}."
),
remedy=remedy,
)
)
return findings


@semantic_rule(
name="missing-recommended-input",
description="Skill steps should provide recommended inputs for full-quality output.",
Expand Down
Loading
Loading