alysis-code 0.13.0__py3-none-any.whl

alysis_code/approval_scope.py

@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any
+
+SCOPE_EXACT_COMMAND_HASH = "exact_command_hash"
+SCOPE_EXACT_FILE_SET = "exact_file_set"
+SCOPE_EXACT_VERIFY_COMMAND_SET = "exact_verify_command_set"
+SCOPE_EXPLICIT_BACKEND_SAFE_KIND = "explicit_backend_safe_kind"
+
+SUPPORTED_APPROVAL_SCOPES = frozenset(
+    {
+        SCOPE_EXACT_COMMAND_HASH,
+        SCOPE_EXACT_FILE_SET,
+        SCOPE_EXACT_VERIFY_COMMAND_SET,
+        SCOPE_EXPLICIT_BACKEND_SAFE_KIND,
+    }
+)
+
+_SHA256_PATTERN = re.compile(r"^[a-f0-9]{64}$")
+_FILE_SCOPE_KINDS = frozenset(
+    {
+        "fs_write",
+        "fs_edit",
+        "fs_move",
+        "fs_copy",
+        "fs_delete",
+        "fs_mkdir",
+        "git_apply_patch",
+    }
+)
+_COMMAND_SCOPE_KINDS = frozenset({"shell_run", "shell_background"})
+
+
+@dataclass(frozen=True, slots=True)
+class ApprovalSessionScope:
+    supported: bool
+    scope: dict[str, Any] | None
+    key: str | None
+    warning: str | None
+
+
+def exact_command_scope(command: str, *, kind: str | None = None) -> dict[str, Any]:
+    scope: dict[str, Any] = {
+        "type": SCOPE_EXACT_COMMAND_HASH,
+        "algorithm": "sha256",
+        "command_hash": _sha256_text(command),
+    }
+    if kind:
+        scope["kind"] = str(kind)
+    return scope
+
+
+def exact_file_set_scope(files: Iterable[str], *, operation: str | None = None) -> dict[str, Any]:
+    normalized = _normalize_files(files)
+    scope: dict[str, Any] = {
+        "type": SCOPE_EXACT_FILE_SET,
+        "algorithm": "sha256",
+        "files_hash": _sha256_json(list(normalized)),
+        "file_count": len(normalized),
+        "files": list(normalized),
+    }
+    if operation:
+        scope["operation"] = str(operation)
+    return scope
+
+
+def exact_verify_command_set_scope(commands: Iterable[str]) -> dict[str, Any]:
+    normalized = tuple(str(command) for command in commands)
+    return {
+        "type": SCOPE_EXACT_VERIFY_COMMAND_SET,
+        "algorithm": "sha256",
+        "commands_hash": _sha256_json(list(normalized)),
+        "command_count": len(normalized),
+    }
+
+
+def explicit_backend_safe_kind_scope(kind: str) -> dict[str, Any]:
+    return {
+        "type": SCOPE_EXPLICIT_BACKEND_SAFE_KIND,
+        "safe_kind": str(kind),
+        "backend_owned": True,
+    }
+
+
+def approval_session_scope_for_request(request: Any) -> ApprovalSessionScope:
+    kind = str(getattr(request, "kind", "") or "approval")
+    raw_scope = getattr(request, "allow_for_session_scope", None)
+    metadata = getattr(request, "metadata", None)
+    if raw_scope is None and isinstance(metadata, dict):
+        candidate = metadata.get("allow_for_session_scope")
+        if isinstance(candidate, dict):
+            raw_scope = candidate
+    if not isinstance(raw_scope, dict):
+        return _unsupported(
+            "Allow for session is unavailable because this approval did not include an exact safe scope."
+        )
+
+    scope_type = str(raw_scope.get("type") or raw_scope.get("scope_type") or "").strip()
+    if scope_type not in SUPPORTED_APPROVAL_SCOPES:
+        return _unsupported(
+            "Allow for session is unavailable because the approval scope is unsupported."
+        )
+
+    if _is_command_like_kind(kind):
+        if scope_type != SCOPE_EXACT_COMMAND_HASH:
+            return _unsupported(
+                "Allow for session is unavailable because command approvals require an exact command hash scope."
+            )
+    elif kind == "verify_run":
+        if scope_type != SCOPE_EXACT_VERIFY_COMMAND_SET:
+            return _unsupported(
+                "Allow for session is unavailable because verification approvals require an exact verification command set scope."
+            )
+    elif kind in _FILE_SCOPE_KINDS:
+        if scope_type != SCOPE_EXACT_FILE_SET:
+            return _unsupported(
+                "Allow for session is unavailable because file approvals require an exact file set scope."
+            )
+    elif scope_type != SCOPE_EXPLICIT_BACKEND_SAFE_KIND:
+        return _unsupported(
+            "Allow for session is unavailable because this approval kind is not backend-marked as session safe."
+        )
+
+    if scope_type == SCOPE_EXACT_COMMAND_HASH:
+        return _command_hash_scope(kind, raw_scope, getattr(request, "command", None))
+    if scope_type == SCOPE_EXACT_FILE_SET:
+        return _file_set_scope(kind, raw_scope, getattr(request, "files", ()))
+    if scope_type == SCOPE_EXACT_VERIFY_COMMAND_SET:
+        return _verify_command_set_scope(kind, raw_scope)
+    return _explicit_backend_safe_kind_scope(kind, raw_scope)
+
+
+def _command_hash_scope(
+    kind: str,
+    raw_scope: dict[str, Any],
+    command: Any,
+) -> ApprovalSessionScope:
+    command_hash = str(raw_scope.get("command_hash") or "").strip().lower()
+    if _SHA256_PATTERN.fullmatch(command_hash) is None:
+        return _unsupported(
+            "Allow for session is unavailable because the command scope is malformed."
+        )
+    if command is not None and _sha256_text(str(command)) != command_hash:
+        return _unsupported(
+            "Allow for session is unavailable because the command scope does not match the approval request."
+        )
+    scope = {
+        "type": SCOPE_EXACT_COMMAND_HASH,
+        "algorithm": "sha256",
+        "kind": kind,
+        "command_hash": command_hash,
+    }
+    return _supported(scope)
+
+
+def _file_set_scope(
+    kind: str,
+    raw_scope: dict[str, Any],
+    files: Any,
+) -> ApprovalSessionScope:
+    files_hash = str(raw_scope.get("files_hash") or "").strip().lower()
+    normalized_files = _normalize_files(files if isinstance(files, list | tuple) else ())
+    if _SHA256_PATTERN.fullmatch(files_hash) is None:
+        return _unsupported("Allow for session is unavailable because the file scope is malformed.")
+    if not normalized_files:
+        return _unsupported(
+            "Allow for session is unavailable because file approvals require at least one scoped file."
+        )
+    if _sha256_json(list(normalized_files)) != files_hash:
+        return _unsupported(
+            "Allow for session is unavailable because the file scope does not match the approval request."
+        )
+    scope = {
+        "type": SCOPE_EXACT_FILE_SET,
+        "algorithm": "sha256",
+        "kind": kind,
+        "operation": str(raw_scope.get("operation") or kind),
+        "files_hash": files_hash,
+        "file_count": len(normalized_files),
+        "files": list(normalized_files),
+    }
+    return _supported(scope)
+
+
+def _verify_command_set_scope(kind: str, raw_scope: dict[str, Any]) -> ApprovalSessionScope:
+    commands_hash = str(raw_scope.get("commands_hash") or "").strip().lower()
+    if _SHA256_PATTERN.fullmatch(commands_hash) is None:
+        return _unsupported(
+            "Allow for session is unavailable because the verification scope is malformed."
+        )
+    command_count = _positive_int(raw_scope.get("command_count"))
+    if command_count is None:
+        return _unsupported(
+            "Allow for session is unavailable because the verification scope is missing its command count."
+        )
+    scope = {
+        "type": SCOPE_EXACT_VERIFY_COMMAND_SET,
+        "algorithm": "sha256",
+        "kind": kind,
+        "commands_hash": commands_hash,
+        "command_count": command_count,
+    }
+    return _supported(scope)
+
+
+def _explicit_backend_safe_kind_scope(
+    kind: str,
+    raw_scope: dict[str, Any],
+) -> ApprovalSessionScope:
+    safe_kind = str(raw_scope.get("safe_kind") or "").strip()
+    if safe_kind != kind or raw_scope.get("backend_owned") is not True:
+        return _unsupported(
+            "Allow for session is unavailable because the backend safe-kind scope is malformed."
+        )
+    scope = {
+        "type": SCOPE_EXPLICIT_BACKEND_SAFE_KIND,
+        "kind": kind,
+        "safe_kind": safe_kind,
+    }
+    return _supported(scope)
+
+
+def _supported(scope: dict[str, Any]) -> ApprovalSessionScope:
+    key = json.dumps(scope, ensure_ascii=True, sort_keys=True, separators=(",", ":"))
+    return ApprovalSessionScope(supported=True, scope=scope, key=key, warning=None)
+
+
+def _unsupported(warning: str) -> ApprovalSessionScope:
+    return ApprovalSessionScope(supported=False, scope=None, key=None, warning=warning)
+
+
+def _normalize_files(files: Iterable[Any]) -> tuple[str, ...]:
+    normalized: list[str] = []
+    seen: set[str] = set()
+    for file in files:
+        text = str(file).strip().replace("\\", "/")
+        if not text or text in seen:
+            continue
+        seen.add(text)
+        normalized.append(text)
+    return tuple(sorted(normalized))
+
+
+def _sha256_text(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8", errors="surrogatepass")).hexdigest()
+
+
+def _sha256_json(value: Any) -> str:
+    encoded = json.dumps(value, ensure_ascii=True, sort_keys=True, separators=(",", ":")).encode(
+        "utf-8"
+    )
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def _positive_int(value: Any) -> int | None:
+    if isinstance(value, bool):
+        return None
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return None
+    return parsed if parsed > 0 else None
+
+
+def _is_command_like_kind(kind: str) -> bool:
+    return (
+        kind in _COMMAND_SCOPE_KINDS
+        or kind.startswith("custom_tool_run:")
+        or kind.startswith("mcp_")
+        or kind.startswith("mcp_tool_run:")
+    )

alysis_code/assets/README.md

@@ -0,0 +1,33 @@
+# Assets
+
+This package implements assets used by planning and execution workflows. Assets
+can represent local files, text, images, OCR output, and derived comprehension
+records associated with a run.
+
+## Contents
+
+- `models.py`, `paths.py`, `index.py`, and `ingestion.py` define and persist
+  asset records.
+- `ocr.py`, `comprehender.py`, and `prompts.py` derive text and summaries.
+- `planner_context.py`, `replanner_context.py`, `worker_section.py`, and
+  `worker_tools.py` prepare assets for planning and execution.
+- `legacy_migration.py` handles older attached-asset layouts.
+- `untrusted_content.py` wraps extracted asset text.
+
+## Scope
+
+Asset content can come from repository files, user uploads, OCR, or generated
+summaries. Keep it bounded and provenance-aware before exposing it to prompts.
+
+Asset records are run artifacts. Mutations should preserve index consistency
+and avoid silently deleting original stored files.
+
+## Development
+
+Schema, migration, and prompt-context changes should include regression coverage
+for existing asset records.
+
+## See Also
+
+- [Forge](../../../docs/forge.md)
+- [Security model](../../../docs/security_model.md)

alysis_code/assets/__init__.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from .asset_read_core import AssetReadResult, perform_asset_read
+from .budget_allocator import (
+    AssetInclusionDecision,
+    TaskAssetAllocation,
+    allocate_task_assets,
+)
+from .comprehender import AssetComprehender
+from .index import AssetIndex
+from .ingestion import ingest_asset
+from .legacy_migration import (
+    LegacyAssetMigrationResult,
+    MigratedLegacyAsset,
+    migrate_legacy_assets,
+)
+from .models import (
+    AssetAlreadyExistsError,
+    AssetError,
+    AssetNotFoundError,
+    AssetRecord,
+    ComprehensionData,
+    ComprehensionRecord,
+    OcrError,
+)
+from .ocr import (
+    OcrProvider,
+    OcrResult,
+    ScriptDetection,
+    ScriptToLanguagesMapper,
+    TesseractOcrProvider,
+)
+from .plan_binding import (
+    AssetBriefingEntry,
+    TaskAssetBriefing,
+    bind_asset_to_matching_tasks,
+    collect_referenced_asset_ids,
+    infer_implicit_task_asset_briefing,
+    parse_task_asset_briefing,
+    serialize_task_asset_briefing,
+    task_asset_briefing,
+    task_asset_briefing_for_execution,
+)
+from .planner_context import (
+    AssetReadinessPolicy,
+    AssetReadinessReport,
+    AssetReferenceReport,
+    PlannerAssetsBundle,
+    PlannerAssetsContext,
+    asset_reference_check,
+    build_planner_assets_block,
+    build_planner_assets_bundle,
+    ensure_planner_asset_readiness,
+)
+from .replanner_context import (
+    PriorAssetUsageSummary,
+    ReplannerAssetsBundle,
+    build_replanner_assets_bundle,
+)
+from .surface import (
+    AssetSurface,
+    AssetSurfaceAddResult,
+    AssetSurfaceDetail,
+    AssetSurfaceEntry,
+    AssetSurfaceJoinReport,
+    ComprehensionRefreshHandle,
+)
+from .worker_mirror import MirroredAssetEntry, TaskAssetMirror, mirror_task_assets
+from .worker_section import render_relevant_assets_section
+
+__all__ = [
+    "AssetAlreadyExistsError",
+    "AssetComprehender",
+    "AssetError",
+    "AssetInclusionDecision",
+    "AssetIndex",
+    "AssetNotFoundError",
+    "AssetRecord",
+    "AssetReadResult",
+    "AssetReadinessPolicy",
+    "AssetReadinessReport",
+    "AssetReferenceReport",
+    "AssetSurface",
+    "AssetSurfaceAddResult",
+    "AssetSurfaceDetail",
+    "AssetSurfaceEntry",
+    "AssetSurfaceJoinReport",
+    "AssetBriefingEntry",
+    "ComprehensionData",
+    "ComprehensionRecord",
+    "ComprehensionRefreshHandle",
+    "LegacyAssetMigrationResult",
+    "MigratedLegacyAsset",
+    "OcrError",
+    "OcrProvider",
+    "OcrResult",
+    "PlannerAssetsContext",
+    "PlannerAssetsBundle",
+    "PriorAssetUsageSummary",
+    "ReplannerAssetsBundle",
+    "ScriptDetection",
+    "ScriptToLanguagesMapper",
+    "TesseractOcrProvider",
+    "TaskAssetBriefing",
+    "TaskAssetAllocation",
+    "TaskAssetMirror",
+    "MirroredAssetEntry",
+    "asset_reference_check",
+    "allocate_task_assets",
+    "bind_asset_to_matching_tasks",
+    "build_planner_assets_block",
+    "build_planner_assets_bundle",
+    "build_replanner_assets_bundle",
+    "collect_referenced_asset_ids",
+    "ensure_planner_asset_readiness",
+    "infer_implicit_task_asset_briefing",
+    "ingest_asset",
+    "migrate_legacy_assets",
+    "mirror_task_assets",
+    "parse_task_asset_briefing",
+    "perform_asset_read",
+    "render_relevant_assets_section",
+    "serialize_task_asset_briefing",
+    "task_asset_briefing",
+    "task_asset_briefing_for_execution",
+]