alysis-code 0.13.0__py3-none-any.whl

alysis_code/skills/validation.py

@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+from ..frontmatter_utils import parse_frontmatter_yaml, split_frontmatter
+from .prompting import (
+    EXPLICIT_SKILL_CONTEXT_TOTAL_MAX_CHARS,
+    EXPLICIT_SKILL_DESCRIPTION_DISPLAY_MAX_CHARS,
+    EXPLICIT_SKILL_ENTRYPOINT_MAX_CHARS,
+    EXPLICIT_SKILL_NAME_DISPLAY_MAX_CHARS,
+)
+
+SKILL_ENTRYPOINT_WARNING_CHARS = EXPLICIT_SKILL_ENTRYPOINT_MAX_CHARS
+SKILL_NAME_WARNING_CHARS = EXPLICIT_SKILL_NAME_DISPLAY_MAX_CHARS
+SKILL_DESCRIPTION_WARNING_CHARS = EXPLICIT_SKILL_DESCRIPTION_DISPLAY_MAX_CHARS
+
+
+@dataclass(frozen=True)
+class SkillValidationIssue:
+    severity: Literal["error", "warning"]
+    message: str
+    path: Path
+
+
+@dataclass(frozen=True)
+class SkillValidationResult:
+    bundle_path: Path
+    entry_path: Path
+    valid: bool
+    name: str = ""
+    description: str = ""
+    instructions: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+    issues: tuple[SkillValidationIssue, ...] = ()
+
+    @property
+    def errors(self) -> tuple[SkillValidationIssue, ...]:
+        return tuple(issue for issue in self.issues if issue.severity == "error")
+
+    @property
+    def warnings(self) -> tuple[SkillValidationIssue, ...]:
+        return tuple(issue for issue in self.issues if issue.severity == "warning")
+
+
+def validate_skill_bundle(bundle_path: Path) -> SkillValidationResult:
+    """Validate a skill bundle without allowing filesystem faults to escape.
+
+    Skill directories are untrusted workspace input.  On Windows in particular,
+    even metadata probes such as ``is_symlink()`` can raise ``PermissionError``
+    for a deny-ACL directory.  Discovery must fail that one bundle closed instead
+    of making session creation fail.
+    """
+
+    try:
+        return _validate_skill_bundle(bundle_path)
+    except OSError as exc:
+        try:
+            reported_bundle = bundle_path.expanduser().absolute()
+        except OSError:
+            reported_bundle = bundle_path
+        entry_path = reported_bundle / "SKILL.md"
+        issue = SkillValidationIssue(
+            severity="error",
+            message=f"Failed to inspect skill bundle: {exc}",
+            path=reported_bundle,
+        )
+        return SkillValidationResult(
+            bundle_path=reported_bundle,
+            entry_path=entry_path,
+            valid=False,
+            issues=(issue,),
+        )
+
+
+def _validate_skill_bundle(bundle_path: Path) -> SkillValidationResult:
+    resolved_bundle = bundle_path.expanduser().resolve()
+    entry_path = resolved_bundle / "SKILL.md"
+    issues: list[SkillValidationIssue] = []
+    if not resolved_bundle.exists() or not resolved_bundle.is_dir():
+        issues.append(
+            SkillValidationIssue(
+                severity="error",
+                message="Skill bundle path is not a directory.",
+                path=resolved_bundle,
+            )
+        )
+        return SkillValidationResult(
+            bundle_path=resolved_bundle,
+            entry_path=entry_path,
+            valid=False,
+            issues=tuple(issues),
+        )
+    if entry_path.is_symlink():
+        issues.append(
+            SkillValidationIssue(
+                severity="error",
+                message="SKILL.md may not be a symlink.",
+                path=entry_path,
+            )
+        )
+    if not entry_path.exists() or not entry_path.is_file():
+        issues.append(
+            SkillValidationIssue(
+                severity="error",
+                message="SKILL.md is missing.",
+                path=entry_path,
+            )
+        )
+        return SkillValidationResult(
+            bundle_path=resolved_bundle,
+            entry_path=entry_path,
+            valid=False,
+            issues=tuple(issues),
+        )
+    try:
+        raw_text = entry_path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        issues.append(
+            SkillValidationIssue(
+                severity="error",
+                message="SKILL.md is not valid UTF-8 text.",
+                path=entry_path,
+            )
+        )
+        return SkillValidationResult(
+            bundle_path=resolved_bundle,
+            entry_path=entry_path,
+            valid=False,
+            issues=tuple(issues),
+        )
+    except OSError as exc:
+        issues.append(
+            SkillValidationIssue(
+                severity="error",
+                message=f"Failed to read SKILL.md: {exc}",
+                path=entry_path,
+            )
+        )
+        return SkillValidationResult(
+            bundle_path=resolved_bundle,
+            entry_path=entry_path,
+            valid=False,
+            issues=tuple(issues),
+        )
+
+    frontmatter, body = split_frontmatter(raw_text)
+    if frontmatter is None:
+        issues.append(
+            SkillValidationIssue(
+                severity="error",
+                message="missing YAML-style frontmatter in SKILL.md",
+                path=entry_path,
+            )
+        )
+        return SkillValidationResult(
+            bundle_path=resolved_bundle,
+            entry_path=entry_path,
+            valid=False,
+            issues=tuple(issues),
+        )
+
+    meta = parse_frontmatter_yaml(
+        frontmatter,
+        allowed_keys={"name", "description", "aliases"},
+        list_fields={"aliases"},
+        string_fields={"name", "description"},
+    )
+    name = str(meta.get("name") or "").strip()
+    description = str(meta.get("description") or "").strip()
+    instructions = body.strip()
+    if not name:
+        issues.append(
+            SkillValidationIssue(
+                severity="error",
+                message="Missing required frontmatter field: name.",
+                path=entry_path,
+            )
+        )
+    if not description:
+        issues.append(
+            SkillValidationIssue(
+                severity="error",
+                message="Missing required frontmatter field: description.",
+                path=entry_path,
+            )
+        )
+    if not instructions:
+        issues.append(
+            SkillValidationIssue(
+                severity="error",
+                message="SKILL.md body/instructions are empty.",
+                path=entry_path,
+            )
+        )
+    if name and len(name) > SKILL_NAME_WARNING_CHARS:
+        issues.append(
+            SkillValidationIssue(
+                severity="warning",
+                message=(
+                    "Skill name is unusually large "
+                    f"(>{SKILL_NAME_WARNING_CHARS:,} chars); explicit /skill metadata display is "
+                    "bounded and may truncate the attached name preview."
+                ),
+                path=entry_path,
+            )
+        )
+    if description and len(description) > SKILL_DESCRIPTION_WARNING_CHARS:
+        issues.append(
+            SkillValidationIssue(
+                severity="warning",
+                message=(
+                    "Skill description is unusually large "
+                    f"(>{SKILL_DESCRIPTION_WARNING_CHARS:,} chars); explicit /skill metadata display "
+                    "is bounded and may truncate the attached description preview."
+                ),
+                path=entry_path,
+            )
+        )
+    if len(raw_text) > SKILL_ENTRYPOINT_WARNING_CHARS:
+        issues.append(
+            SkillValidationIssue(
+                severity="warning",
+                message=(
+                    "SKILL.md entrypoint is unusually large "
+                    f"(>{SKILL_ENTRYPOINT_WARNING_CHARS:,} chars); explicit /skill context is "
+                    f"bounded to a {EXPLICIT_SKILL_CONTEXT_TOTAL_MAX_CHARS:,}-char wrapper and may "
+                    "truncate the attached preview."
+                ),
+                path=entry_path,
+            )
+        )
+    for optional_name in ("references", "scripts", "assets"):
+        optional_path = resolved_bundle / optional_name
+        if optional_path.is_symlink():
+            issues.append(
+                SkillValidationIssue(
+                    severity="error",
+                    message=f"{optional_name}/ may not be a symlink.",
+                    path=optional_path,
+                )
+            )
+        elif optional_path.exists() and not optional_path.is_dir():
+            issues.append(
+                SkillValidationIssue(
+                    severity="error",
+                    message=f"{optional_name}/ must be a directory when present.",
+                    path=optional_path,
+                )
+            )
+    for candidate in resolved_bundle.rglob("*"):
+        if candidate == entry_path:
+            continue
+        if candidate.is_symlink():
+            issues.append(
+                SkillValidationIssue(
+                    severity="error",
+                    message="Skill bundles may not contain symlinks.",
+                    path=candidate,
+                )
+            )
+            break
+    total_bytes = 0
+    file_count = 0
+    for candidate in resolved_bundle.rglob("*"):
+        if not candidate.is_file():
+            continue
+        file_count += 1
+        try:
+            total_bytes += candidate.stat().st_size
+        except OSError:
+            continue
+    if total_bytes > 5 * 1024 * 1024:
+        issues.append(
+            SkillValidationIssue(
+                severity="warning",
+                message="Skill bundle is unusually large (>5 MiB).",
+                path=resolved_bundle,
+            )
+        )
+    if file_count > 256:
+        issues.append(
+            SkillValidationIssue(
+                severity="warning",
+                message="Skill bundle contains an unusually high file count (>256 files).",
+                path=resolved_bundle,
+            )
+        )
+
+    return SkillValidationResult(
+        bundle_path=resolved_bundle,
+        entry_path=entry_path,
+        valid=not any(issue.severity == "error" for issue in issues),
+        name=name,
+        description=description,
+        instructions=instructions,
+        metadata={
+            key: value
+            for key, value in meta.items()
+            if key in {"name", "description", "aliases"} and value
+        },
+        issues=tuple(issues),
+    )

alysis_code/step_budget.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+# These remain the default limits for the opt-in ``limited`` policy and for
+# backwards-compatible configuration files.  The default ``autonomous`` policy
+# does not consume them.
+DEFAULT_CHAT_MAX_STEPS = 80
+DEFAULT_TASK_MAX_STEPS = 160
+DEFAULT_SUBAGENT_MAX_STEPS = 28
+
+AUTONOMOUS_STEP_BUDGET_POLICY = "autonomous"
+LIMITED_STEP_BUDGET_POLICY = "limited"
+
+# ``adaptive`` and ``fixed`` are legacy spellings.  Keeping them loadable avoids
+# breaking existing installations while giving them the new, explicit contract:
+# adaptive -> autonomous, fixed -> limited.
+_STEP_BUDGET_POLICY_ALIASES = {
+    "adaptive": AUTONOMOUS_STEP_BUDGET_POLICY,
+    "fixed": LIMITED_STEP_BUDGET_POLICY,
+}
+VALID_STEP_BUDGET_POLICIES = {
+    AUTONOMOUS_STEP_BUDGET_POLICY,
+    LIMITED_STEP_BUDGET_POLICY,
+    *_STEP_BUDGET_POLICY_ALIASES,
+}
+
+
+def _positive_int(value: Any, *, default: int) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return max(1, int(default))
+    return max(1, parsed)
+
+
+def normalize_step_budget_policy(raw_value: Any) -> str:
+    normalized = str(raw_value or "").strip().lower()
+    normalized = _STEP_BUDGET_POLICY_ALIASES.get(normalized, normalized)
+    if normalized in {AUTONOMOUS_STEP_BUDGET_POLICY, LIMITED_STEP_BUDGET_POLICY}:
+        return normalized
+    return AUTONOMOUS_STEP_BUDGET_POLICY
+
+
+def step_budget_is_autonomous(raw_value: Any) -> bool:
+    return normalize_step_budget_policy(raw_value) == AUTONOMOUS_STEP_BUDGET_POLICY
+
+
+def resolve_subagent_step_profile(subagent_name: Any) -> str | None:
+    normalized = str(subagent_name or "").strip().lower()
+    if not normalized:
+        return None
+    if normalized in {
+        "explorer",
+        "implementer",
+        "frontend-engineer",
+        "debugger",
+        "verifier",
+        "code-reviewer",
+        "visual-designer",
+    }:
+        return normalized
+    return "default"
+
+
+@dataclass(frozen=True)
+class StepBudgetRequest:
+    kind: str
+    policy: str
+    hard_cap: int | None
+    fixed_override: int | None = None
+    mode: str | None = None
+    route: str | None = None
+    one_shot_execution: bool = False
+    one_shot_turn_intent: str | None = None
+    verification_enabled: bool = False
+    subagents_enabled: bool = False
+    subagent_name: str | None = None
+    parent_turn_budget: int | None = None
+    attempt_count: int = 1
+    image_count: int = 0
+    explicit_path_count: int = 0
+    acceptance_criteria_count: int = 0
+    estimated_files_count: int = 0
+    write_scope_count: int = 0
+    dependency_count: int = 0
+    asset_count: int = 0
+    conflict_file_count: int = 0
+
+
+@dataclass(frozen=True)
+class StepBudgetResolution:
+    kind: str
+    policy: str
+    hard_cap: int | None
+    resolved_max_steps: int | None
+    override_applied: bool
+    reason: str
+    signals_used: dict[str, Any]
+    base_steps: int | None
+    profile: str | None = None
+
+    @property
+    def unlimited(self) -> bool:
+        return self.resolved_max_steps is None
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "kind": self.kind,
+            "policy": self.policy,
+            "hard_cap": self.hard_cap,
+            "resolved_max_steps": self.resolved_max_steps,
+            "unlimited": self.unlimited,
+            "override_applied": self.override_applied,
+            "reason": self.reason,
+            "signals_used": dict(self.signals_used),
+            "base_steps": self.base_steps,
+            "profile": self.profile,
+        }
+
+
+@dataclass
+class StepBudgetRuntime:
+    active_turn_budget: int | None = None
+    last_resolution: StepBudgetResolution | None = None
+
+
+def _default_cap(kind: str) -> int:
+    return {
+        "chat_turn": DEFAULT_CHAT_MAX_STEPS,
+        "managed_task": DEFAULT_TASK_MAX_STEPS,
+        "conflict_resolution": DEFAULT_TASK_MAX_STEPS,
+        "subagent": DEFAULT_SUBAGENT_MAX_STEPS,
+    }.get(kind, DEFAULT_CHAT_MAX_STEPS)
+
+
+def _resolve_limited_cap(request: StepBudgetRequest, *, kind: str) -> int:
+    hard_cap = _positive_int(request.hard_cap, default=_default_cap(kind))
+    if kind == "subagent" and request.parent_turn_budget is not None:
+        hard_cap = min(
+            hard_cap,
+            _positive_int(request.parent_turn_budget, default=hard_cap),
+        )
+    return max(1, hard_cap)
+
+
+def _request_signals(request: StepBudgetRequest) -> dict[str, Any]:
+    """Retain useful task-shape telemetry without using it to terminate work."""
+
+    return {
+        "mode": request.mode,
+        "route": request.route,
+        "one_shot_execution": bool(request.one_shot_execution),
+        "one_shot_turn_intent": request.one_shot_turn_intent,
+        "verification_enabled": bool(request.verification_enabled),
+        "subagents_enabled": bool(request.subagents_enabled),
+        "subagent_name": request.subagent_name,
+        "parent_turn_budget": request.parent_turn_budget,
+        "attempt_count": request.attempt_count,
+        "image_count": request.image_count,
+        "explicit_path_count": request.explicit_path_count,
+        "acceptance_criteria_count": request.acceptance_criteria_count,
+        "estimated_files_count": request.estimated_files_count,
+        "write_scope_count": request.write_scope_count,
+        "dependency_count": request.dependency_count,
+        "asset_count": request.asset_count,
+        "conflict_file_count": request.conflict_file_count,
+    }
+
+
+def resolve_step_budget(request: StepBudgetRequest) -> StepBudgetResolution:
+    """Resolve an optional safety ceiling for one autonomous agent loop.
+
+    Autonomous execution is intentionally unbounded.  A finite ceiling exists
+    only when the caller supplies an explicit override or selects the opt-in
+    limited policy.  Completion, cancellation, blockers, fatal errors, and an
+    optional wall-clock deadline remain independent termination conditions.
+    """
+
+    kind = str(request.kind or "").strip().lower() or "chat_turn"
+    policy = normalize_step_budget_policy(request.policy)
+    profile = resolve_subagent_step_profile(request.subagent_name) if kind == "subagent" else None
+
+    if request.fixed_override is not None:
+        explicit_limit = _positive_int(
+            request.fixed_override,
+            default=_default_cap(kind),
+        )
+        return StepBudgetResolution(
+            kind=kind,
+            policy=policy,
+            hard_cap=explicit_limit,
+            resolved_max_steps=explicit_limit,
+            override_applied=True,
+            reason="explicit_limit",
+            signals_used={
+                **_request_signals(request),
+                "policy": policy,
+                "explicit_limit": explicit_limit,
+            },
+            base_steps=explicit_limit,
+            profile=profile,
+        )
+
+    if policy == LIMITED_STEP_BUDGET_POLICY:
+        hard_cap = _resolve_limited_cap(request, kind=kind)
+        return StepBudgetResolution(
+            kind=kind,
+            policy=policy,
+            hard_cap=hard_cap,
+            resolved_max_steps=hard_cap,
+            override_applied=False,
+            reason="limited_policy",
+            signals_used={
+                **_request_signals(request),
+                "policy": policy,
+                "hard_cap": hard_cap,
+            },
+            base_steps=hard_cap,
+            profile=profile,
+        )
+
+    return StepBudgetResolution(
+        kind=kind,
+        policy=AUTONOMOUS_STEP_BUDGET_POLICY,
+        hard_cap=None,
+        resolved_max_steps=None,
+        override_applied=False,
+        reason="autonomous_unbounded",
+        signals_used={
+            **_request_signals(request),
+            "policy": AUTONOMOUS_STEP_BUDGET_POLICY,
+            "configured_legacy_cap": request.hard_cap,
+        },
+        base_steps=None,
+        profile=profile,
+    )

alysis_code/subagent_labels.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import re
+
+from .safety.subagent_report import sanitize_subagent_report, subagent_report_evidence_text
+
+SUBAGENT_TASK_LABEL_MAX_CHARS = 24
+
+_LABEL_TOKEN_RE = re.compile(r"[\w.-]+", flags=re.UNICODE)
+
+
+def subagent_task_label(task: object, *, requested_run_id: object = "") -> str:
+    """Return a stable, display-safe child label without exposing the generated id."""
+    caller_label = str(requested_run_id or "").strip()
+    if caller_label:
+        return caller_label
+
+    screened = sanitize_subagent_report(str(task or "")).text
+    evidence = subagent_report_evidence_text(screened)
+    words = [
+        token
+        for token in _LABEL_TOKEN_RE.findall(evidence)
+        if any(character.isalnum() for character in token)
+    ]
+    selected: list[str] = []
+    for word in words:
+        candidate = " ".join((*selected, word))
+        if len(candidate) > SUBAGENT_TASK_LABEL_MAX_CHARS:
+            break
+        selected.append(word)
+    if selected:
+        return " ".join(selected)
+    if words:
+        return words[0][:SUBAGENT_TASK_LABEL_MAX_CHARS]
+    return "task"
+
+
+def subagent_identity(name: object, label: object) -> str:
+    """Combine role and stable task identity for user-facing surfaces."""
+    role = str(name or "subagent").strip() or "subagent"
+    task_label = str(label or "").strip()
+    return f"{role} \u00b7 {task_label}" if task_label else role
+
+
+__all__ = [
+    "SUBAGENT_TASK_LABEL_MAX_CHARS",
+    "subagent_identity",
+    "subagent_task_label",
+]