alysis-code 0.13.0__py3-none-any.whl

alysis_code/context/__init__.py

@@ -0,0 +1 @@
+"""Context planning and request-size diagnostics."""

alysis_code/context/tool_schema_budgeter.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from ..token_budget import estimate_tokens
+
+DEFAULT_TOOL_SCHEMA_BUDGET_TOKENS = 8_000
+DEFAULT_LARGEST_TOOL_COUNT = 5
+DEFAULT_CUSTOM_MCP_DESCRIPTION_MAX_CHARS = 800
+
+CUSTOM_MCP_SCHEMA_FAMILIES = frozenset({"custom", "custom_tool", "mcp", "mcp_tool"})
+MODEL_FACING_SCHEMA_ANNOTATION_KEYS = frozenset(
+    {
+        "$comment",
+        "default",
+        "description",
+        "example",
+        "examples",
+        "markdownDescription",
+        "title",
+    }
+)
+JSON_SCHEMA_NAMED_SCHEMA_MAP_KEYS = frozenset(
+    {
+        "$defs",
+        "definitions",
+        "dependentSchemas",
+        "patternProperties",
+        "properties",
+    }
+)
+JSON_SCHEMA_OPAQUE_DATA_KEYS = frozenset(
+    {
+        "const",
+        "default",
+        "enum",
+    }
+)
+
+
+@dataclass(frozen=True)
+class ToolSchemaBudgetEntry:
+    name: str
+    token_estimate: int
+    family: str
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "token_estimate": self.token_estimate,
+            "family": self.family,
+        }
+
+    @classmethod
+    def from_payload(cls, payload: Any) -> ToolSchemaBudgetEntry | None:
+        if not isinstance(payload, dict):
+            return None
+        name = str(payload.get("name") or "").strip()
+        if not name:
+            return None
+        return cls(
+            name=name,
+            token_estimate=_as_non_negative_int(payload.get("token_estimate")),
+            family=_tool_family(name, payload.get("family")),
+        )
+
+
+@dataclass(frozen=True)
+class ToolSchemaBudgetReport:
+    tool_count: int
+    total_tokens: int
+    budget_tokens: int
+    over_budget_tokens: int
+    signature: str
+    largest_tools: tuple[ToolSchemaBudgetEntry, ...] = ()
+
+    @property
+    def over_budget(self) -> bool:
+        return self.over_budget_tokens > 0
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "tool_count": self.tool_count,
+            "total_tokens": self.total_tokens,
+            "budget_tokens": self.budget_tokens,
+            "over_budget_tokens": self.over_budget_tokens,
+            "over_budget": self.over_budget,
+            "signature": self.signature,
+            "largest_tools": [entry.to_payload() for entry in self.largest_tools],
+        }
+
+    @classmethod
+    def from_payload(cls, payload: Any) -> ToolSchemaBudgetReport | None:
+        if not isinstance(payload, dict):
+            return None
+        signature = str(payload.get("signature") or "").strip()
+        entries: list[ToolSchemaBudgetEntry] = []
+        raw_entries = payload.get("largest_tools")
+        if isinstance(raw_entries, list):
+            for raw_entry in raw_entries:
+                entry = ToolSchemaBudgetEntry.from_payload(raw_entry)
+                if entry is not None:
+                    entries.append(entry)
+        return cls(
+            tool_count=_as_non_negative_int(payload.get("tool_count")),
+            total_tokens=_as_non_negative_int(payload.get("total_tokens")),
+            budget_tokens=_as_non_negative_int(payload.get("budget_tokens")),
+            over_budget_tokens=_as_non_negative_int(payload.get("over_budget_tokens")),
+            signature=signature,
+            largest_tools=tuple(entries),
+        )
+
+
+def analyze_tool_schema_budget(
+    tool_list: list[dict[str, Any]] | None,
+    *,
+    budget_tokens: int = DEFAULT_TOOL_SCHEMA_BUDGET_TOKENS,
+    largest_count: int = DEFAULT_LARGEST_TOOL_COUNT,
+) -> ToolSchemaBudgetReport:
+    tools = [tool for tool in (tool_list or []) if isinstance(tool, dict)]
+    entries: list[ToolSchemaBudgetEntry] = []
+    for index, tool in enumerate(tools, start=1):
+        name = _tool_name(tool, fallback=f"tool_{index}")
+        entries.append(
+            ToolSchemaBudgetEntry(
+                name=name,
+                token_estimate=_estimate_single_tool_schema_tokens(tool),
+                family=_tool_family(name, None),
+            )
+        )
+    total = estimate_tokens(_stable_json(tools)) if tools else 0
+    budget = max(0, int(budget_tokens or 0))
+    largest_n = max(0, int(largest_count or 0))
+    largest_tools = tuple(
+        sorted(entries, key=lambda entry: (-entry.token_estimate, entry.name.casefold()))[
+            :largest_n
+        ]
+    )
+    return ToolSchemaBudgetReport(
+        tool_count=len(tools),
+        total_tokens=total,
+        budget_tokens=budget,
+        over_budget_tokens=max(0, total - budget) if budget > 0 else 0,
+        signature=tool_schema_signature(tools),
+        largest_tools=largest_tools,
+    )
+
+
+def tool_schema_signature(tool_list: list[dict[str, Any]] | None) -> str:
+    payload = _stable_json([tool for tool in (tool_list or []) if isinstance(tool, dict)])
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:16]
+
+
+def compact_custom_mcp_tool_parameters(
+    value: Any,
+    *,
+    _inside_named_schema_map: bool = False,
+) -> Any:
+    """Drop annotation-only JSON Schema prose from custom/MCP model-facing schemas."""
+    if isinstance(value, dict):
+        compacted: dict[str, Any] = {}
+        for key, item in value.items():
+            normalized_key = str(key)
+            if not _inside_named_schema_map:
+                if normalized_key in MODEL_FACING_SCHEMA_ANNOTATION_KEYS:
+                    continue
+                if normalized_key in JSON_SCHEMA_OPAQUE_DATA_KEYS:
+                    # enum/const/default hold constraint data, not subschemas.
+                    compacted[key] = copy.deepcopy(item)
+                    continue
+            compacted[key] = compact_custom_mcp_tool_parameters(
+                item,
+                _inside_named_schema_map=normalized_key in JSON_SCHEMA_NAMED_SCHEMA_MAP_KEYS,
+            )
+        return compacted
+    if isinstance(value, list):
+        return [compact_custom_mcp_tool_parameters(item) for item in value]
+    return value
+
+
+def _estimate_single_tool_schema_tokens(tool: dict[str, Any]) -> int:
+    return estimate_tokens(_stable_json(tool))
+
+
+def _stable_json(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+
+
+def _tool_name(tool: dict[str, Any], *, fallback: str) -> str:
+    function = tool.get("function")
+    if isinstance(function, dict):
+        name = str(function.get("name") or "").strip()
+        if name:
+            return name
+    name = str(tool.get("name") or "").strip()
+    return name or fallback
+
+
+def _tool_family(name: str, raw_family: Any) -> str:
+    family = str(raw_family or "").strip().lower()
+    if family:
+        return family
+    normalized = str(name or "").strip().lower()
+    if normalized.startswith("mcp__") or normalized.startswith("mcp_"):
+        return "mcp"
+    if normalized.startswith("custom__") or normalized.startswith("custom_"):
+        return "custom"
+    return "builtin"
+
+
+def _as_non_negative_int(value: Any) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return 0
+    return max(0, parsed)

alysis_code/crash_diagnostics.py

@@ -0,0 +1,282 @@
+from __future__ import annotations
+
+import json
+import math
+import os
+import threading
+import time
+import warnings
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from .error_text import sanitize_error_summary
+from .failure_category import classify_failure_category, extract_status_code
+from .logging_redaction import redact_log_text
+
+CRASH_DIAGNOSTIC_SCHEMA_VERSION = 1
+
+_PATH_LOCKS_GUARD = threading.Lock()
+_PATH_LOCKS: dict[str, threading.Lock] = {}
+
+_ALLOWED_FIELDS = {
+    "budget_seconds",
+    "checkpoint_fraction",
+    "completion_gate_decision",
+    "deadline_config_source",
+    "deadline",
+    "deadline_configured_seconds",
+    "deadline_exhausted",
+    "deadline_finalization_reason",
+    "deadline_finalization_reserve_seconds",
+    "deadline_normal_work_remaining_seconds",
+    "deadline_phase",
+    "deadline_prevented_launch",
+    "deadline_remaining_seconds",
+    "deadline_start_decision",
+    "duration_ms",
+    "elapsed_fraction",
+    "elapsed_seconds",
+    "error_summary",
+    "error_type",
+    "exit_code",
+    "failure_category",
+    "grace_seconds",
+    "material_edit_count",
+    "max_steps",
+    "model",
+    "operation",
+    "provider_status_code",
+    "reason",
+    "remaining_seconds",
+    "runtime_kind",
+    "session_source",
+    "status",
+    "step",
+    "steps_attempted",
+    "steps_completed",
+    # Machine-readable terminal marker. Without this entry the key is silently
+    # dropped by the allowlist filter below and a budget stop stays
+    # indistinguishable from a crash in the crash log.
+    "stop_reason",
+    "subagent",
+    "subagent_role",
+    "subagent_session_id",
+    "success",
+    "termination_kind",
+    "tool_name",
+    "usage_counts",
+    "verification_attempt_count",
+}
+_NESTED_ALLOWED_FIELDS = {
+    "allowed",
+    "average_seconds",
+    "configured_seconds",
+    "count",
+    "deadline_monotonic",
+    "dispatch_overhead_seconds",
+    "duration_observations",
+    "elapsed_seconds",
+    "enabled",
+    "estimated_duration_seconds",
+    "exhausted",
+    "finalization_directive_sent",
+    "finalization_llm_started",
+    "finalization_reason",
+    "finalization_reserve_seconds",
+    "adaptive_retry_llm",
+    "compaction_llm",
+    "exploration_tool",
+    "local_final_summary",
+    "main_llm",
+    "main_llm_retry",
+    "max_seconds",
+    "minimum_required_seconds",
+    "mutation_tool",
+    "normal_work_remaining_seconds",
+    "operation",
+    "phase",
+    "provider_retry_sleep",
+    "remaining_seconds",
+    "shell_background",
+    "shell_tool",
+    "source",
+    "subagent",
+    "tool_dispatch",
+    "verification",
+}
+
+_HIGH_VALUE_EVENTS = {
+    "run_started",
+    "terminal_error",
+    "deadline_exhausted",
+    "progress_checkpoint_failed",
+    "run_budget_watchdog_fired",
+    "run_finished",
+    "turn_finished",
+}
+
+
+def _lock_for_path(path: Path) -> threading.Lock:
+    key = os.fspath(path.resolve())
+    with _PATH_LOCKS_GUARD:
+        lock = _PATH_LOCKS.get(key)
+        if lock is None:
+            lock = threading.Lock()
+            _PATH_LOCKS[key] = lock
+        return lock
+
+
+def _now_ts() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def _safe_scalar(value: Any) -> Any:
+    if isinstance(value, bool) or value is None:
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return round(value, 6) if math.isfinite(value) else None
+    if isinstance(value, str):
+        return value[:240]
+    if isinstance(value, dict):
+        return {
+            str(key)[:80]: _safe_scalar(item)
+            for key, item in value.items()
+            if str(key) in _ALLOWED_FIELDS or str(key) in _NESTED_ALLOWED_FIELDS
+        }
+    if isinstance(value, (list, tuple)):
+        return [_safe_scalar(item) for item in list(value)[:20]]
+    return str(value)[:120]
+
+
+@dataclass
+class CrashDiagnosticLogger:
+    path: Path | None
+    run_id: str
+    session_id: str
+    runtime_kind: str = ""
+    _started_at_monotonic: float = field(default_factory=time.monotonic)
+    write_failures: int = 0
+
+    @classmethod
+    def disabled(cls) -> CrashDiagnosticLogger:
+        return cls(path=None, run_id="", session_id="", runtime_kind="")
+
+    @property
+    def enabled(self) -> bool:
+        return self.path is not None
+
+    def event(
+        self,
+        event_type: str,
+        payload: dict[str, Any] | None = None,
+        *,
+        durable: bool = False,
+    ) -> None:
+        if self.path is None:
+            return
+        event_type = str(event_type or "").strip()
+        if not event_type:
+            return
+        raw_payload = dict(payload or {})
+        safe_payload = {
+            key: _safe_scalar(value) for key, value in raw_payload.items() if key in _ALLOWED_FIELDS
+        }
+        if self.runtime_kind and "runtime_kind" not in safe_payload:
+            safe_payload["runtime_kind"] = self.runtime_kind
+        event = {
+            "schema_version": CRASH_DIAGNOSTIC_SCHEMA_VERSION,
+            "event_type": event_type,
+            "ts": _now_ts(),
+            "monotonic_elapsed_seconds": round(
+                max(0.0, time.monotonic() - self._started_at_monotonic),
+                6,
+            ),
+            "run_id": self.run_id,
+            "session_id": self.session_id,
+            "payload": safe_payload,
+        }
+        self._write_line(event, durable=durable or event_type in _HIGH_VALUE_EVENTS)
+
+    def _write_line(self, event: dict[str, Any], *, durable: bool) -> None:
+        assert self.path is not None
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            line = redact_log_text(json.dumps(event, ensure_ascii=True, sort_keys=True) + "\n")
+            lock = _lock_for_path(self.path)
+            with lock:
+                with self.path.open("a", encoding="utf-8") as fh:
+                    fh.write(line)
+                    fh.flush()
+                    if durable:
+                        os.fsync(fh.fileno())
+        except Exception as exc:
+            # A broken diagnostic sink must not crash the run, but it must not be
+            # silent either: an autonomous fix-loop that "captured nothing" while
+            # believing it captured everything is worse than a loud one-time warning.
+            self.write_failures += 1
+            if self.write_failures == 1:
+                warnings.warn(
+                    f"crash diagnostic write to {self.path} failed "
+                    f"({type(exc).__name__}: {exc}); subsequent write failures are counted "
+                    "in write_failures but not re-warned.",
+                    RuntimeWarning,
+                    stacklevel=2,
+                )
+            return
+
+
+def build_crash_diagnostic_logger(
+    *,
+    path: str | os.PathLike[str] | None,
+    run_id: str,
+    session_id: str,
+    runtime_kind: str = "",
+) -> CrashDiagnosticLogger:
+    raw = str(path or "").strip()
+    if not raw:
+        return CrashDiagnosticLogger.disabled()
+    return CrashDiagnosticLogger(
+        path=Path(raw),
+        run_id=run_id,
+        session_id=session_id,
+        runtime_kind=runtime_kind,
+    )
+
+
+def build_error_event_fields(
+    error: BaseException | str | None,
+    *,
+    operation: str | None = None,
+    step: int | None = None,
+) -> dict[str, Any]:
+    """Build the redacted, joinable error block for a terminal/diagnostic event.
+
+    The block answers the question an autonomous fix-loop actually needs after a
+    failed build — *why* did it die — without ever persisting a secret:
+
+    - ``error_type``: the exception class name (e.g. ``LLMError``),
+    - ``error_summary``: the message, secret-redacted and length-bounded via the
+      shared :func:`sanitize_error_summary`,
+    - ``failure_category``: a real :class:`FailureCategory` (never the legacy
+      ``"llm_error"`` literal) so the cause joins across chat/run and Forge artifacts,
+    - ``provider_status_code``: the HTTP status when one can be recovered.
+
+    Safe to call from inside a failure path: it never raises.
+    """
+    fields: dict[str, Any] = {
+        "error_type": type(error).__name__,
+        "error_summary": sanitize_error_summary(str(error or "")),
+        "failure_category": classify_failure_category(error).value,
+    }
+    status_code = extract_status_code(error)
+    if status_code is not None:
+        fields["provider_status_code"] = status_code
+    if operation:
+        fields["operation"] = str(operation)
+    if step is not None:
+        fields["step"] = int(step)
+    return fields

alysis_code/custom_tools/README.md

@@ -0,0 +1,34 @@
+# Custom Tools
+
+This package implements Alysis Code's single-file Python custom tools. A custom
+tool is user- or workspace-provided code with a literal manifest and a
+`run(args)` entrypoint.
+
+## Contents
+
+- `discovery.py` validates candidate tool files without importing them.
+- `trust.py` records project-tool trust by workspace, relative path, and file
+  hash.
+- `session.py` builds the effective custom-tool catalog for a session.
+- `runtime.py` executes trusted tools and applies declared capability checks.
+
+## Scope
+
+Project tools are not trusted by default. Editing or moving a trusted project
+tool invalidates trust.
+
+Discovery must remain import-free. Candidate code should not run while the host
+is deciding whether the tool is valid or trusted.
+
+Capability checks are not a complete sandbox. Treat custom tools as trusted
+code and keep the documentation precise about that boundary.
+
+## Development
+
+Manifest, trust, and runtime changes should test valid and rejected tools, plus
+the structured errors users will see.
+
+## See Also
+
+- [Custom tools](../../../docs/custom_tools.md)
+- [Security model](../../../docs/security_model.md)

alysis_code/custom_tools/__init__.py

@@ -0,0 +1,43 @@
+from .discovery import (
+    CustomToolCapabilities,
+    CustomToolDiscoveryResult,
+    CustomToolIssue,
+    CustomToolSpec,
+    discover_custom_tools,
+    global_custom_tools_root,
+    project_custom_tools_root,
+)
+from .runtime import run_custom_tool
+from .session import (
+    CustomToolCatalogEntry,
+    CustomToolSessionState,
+    build_custom_tool_session_state,
+)
+from .trust import (
+    ProjectToolTrustKey,
+    ProjectToolTrustState,
+    is_project_tool_trusted,
+    load_trust_state,
+    trust_project_tool,
+    untrust_project_tool,
+)
+
+__all__ = [
+    "CustomToolCatalogEntry",
+    "CustomToolCapabilities",
+    "CustomToolDiscoveryResult",
+    "CustomToolIssue",
+    "CustomToolSessionState",
+    "CustomToolSpec",
+    "ProjectToolTrustKey",
+    "ProjectToolTrustState",
+    "build_custom_tool_session_state",
+    "discover_custom_tools",
+    "global_custom_tools_root",
+    "is_project_tool_trusted",
+    "load_trust_state",
+    "project_custom_tools_root",
+    "run_custom_tool",
+    "trust_project_tool",
+    "untrust_project_tool",
+]