ai-push-hooks 0.2.1 → 0.3.1

package/src/ai_push_hooks/engine.py

@@ -8,10 +8,26 @@ from .artifacts import ArtifactStore
 from .config import resolve_prompt_text
 from .executors.apply import run_apply_step
 from .executors.assertions import ASSERTION_HANDLERS
-from .executors.exec import EXEC_HANDLERS, env_bool
-from .executors.llm import run_llm_step
+from .executors.exec import EXEC_HANDLERS
+from .git_utils import env_bool
+from .executors.ask import run_ask_step
+from .executors.step_commands import execute_step_command
 from .modules import COLLECTORS
-from .types import CollectorResult, HookError, ModuleRuntimeState, RuntimeContext, StepConfig, StepResult, WorkflowRunResult
+from .plugin_loader import PluginDispatcher
+from .plugins import (
+    validate_assert_result,
+    validate_collector_result,
+    validate_exec_result,
+)
+from .types import (
+    CollectorResult,
+    HookError,
+    ModuleRuntimeState,
+    RuntimeContext,
+    StepConfig,
+    StepResult,
+    WorkflowRunResult,
+)
 
 CollectorHandler = Callable[[RuntimeContext, ModuleRuntimeState], CollectorResult]
 ExecHandler = Callable[[RuntimeContext, ModuleRuntimeState, StepConfig, list[pathlib.Path]], dict[str, Any]]
@@ -26,7 +42,7 @@ class WorkflowEngine:
         collectors: dict[str, CollectorHandler] | None = None,
         exec_handlers: dict[str, ExecHandler] | None = None,
         assertion_handlers: dict[str, AssertionHandler] | None = None,
-        llm_executor: Callable[[RuntimeContext, StepConfig, str, list[pathlib.Path], str], Any] = run_llm_step,
+        ask_executor: Callable[[RuntimeContext, StepConfig, str, list[pathlib.Path], str], Any] = run_ask_step,
         apply_executor: Callable[[RuntimeContext, ModuleRuntimeState, StepConfig, str, list[pathlib.Path], str], dict[str, object]] = run_apply_step,
     ) -> None:
         self.context = context
@@ -34,11 +50,16 @@ class WorkflowEngine:
         self.collectors = collectors or COLLECTORS
         self.exec_handlers = exec_handlers or EXEC_HANDLERS
         self.assertion_handlers = assertion_handlers or ASSERTION_HANDLERS
-        self.llm_executor = llm_executor
+        self.ask_executor = ask_executor
         self.apply_executor = apply_executor
+        self._plugin_dispatcher: PluginDispatcher | None = None
 
     def run(self) -> WorkflowRunResult:
         self.artifacts.prepare()
+        # A loader/cache is deliberately scoped to one workflow run.  In
+        # particular, a second run must not reuse a module snapshot from the
+        # first run.
+        self._plugin_dispatcher = PluginDispatcher()
         states = [
             ModuleRuntimeState(module=self.context.config.modules[module_id])
             for module_id in self.context.config.workflow.modules
@@ -110,14 +131,20 @@ class WorkflowEngine:
             return StepResult(status="skipped", artifacts={"result.json": path}, metadata={})
 
         if step.type == "collect":
+            if step.python:
+                input_paths = self._resolve_plugin_inputs(state, step)
+                result = validate_collector_result(
+                    self._dispatch_plugin(state, step, input_paths)
+                )
+                return self._persist_plugin_collect(state, step, result)
             return self._run_collect(state, step)
 
         input_paths = [self.artifacts.resolve_input(state, reference) for reference in step.inputs]
         stage_name = f"{state.module.id}.{step.id}"
 
-        if step.type == "llm":
+        if step.type == "ask":
             prompt = resolve_prompt_text(self.context.repo_root, step)
-            payload = self.llm_executor(self.context, step, prompt, input_paths, stage_name)
+            payload = self.ask_executor(self.context, step, prompt, input_paths, stage_name)
             artifact_name = step.output or "result.json"
             if isinstance(payload, (dict, list)) or artifact_name.endswith(".json"):
                 path = self.artifacts.write_json(state, state.step_index, step.id, artifact_name, payload)
@@ -132,6 +159,22 @@ class WorkflowEngine:
             return StepResult(artifacts={"result.json": path})
 
         if step.type == "exec":
+            if step.python:
+                plugin_inputs = dict(zip(step.inputs, input_paths))
+                payload = validate_exec_result(
+                    self._dispatch_plugin(state, step, plugin_inputs)
+                )
+                path = self._persist_plugin_result(state, step, payload)
+                return StepResult(artifacts={"result.json": path})
+            if step.command:
+                persisted = execute_step_command(
+                    self.context,
+                    state,
+                    step,
+                    dict(zip(step.inputs, input_paths)),
+                    artifacts=self.artifacts,
+                )
+                return StepResult(artifacts=dict(persisted.artifacts))
             handler = self.exec_handlers.get(step.executor or "")
             if handler is None:
                 raise HookError(f"Unknown exec handler: {step.executor}")
@@ -140,6 +183,24 @@ class WorkflowEngine:
             return StepResult(artifacts={"result.json": path})
 
         if step.type == "assert":
+            if step.python:
+                plugin_inputs = dict(zip(step.inputs, input_paths))
+                payload = validate_assert_result(
+                    self._dispatch_plugin(state, step, plugin_inputs)
+                )
+                path = self._persist_plugin_result(state, step, payload)
+                if not payload["ok"]:
+                    raise HookError(payload.get("message", "assertion failed"))
+                return StepResult(artifacts={"result.json": path})
+            if step.command:
+                persisted = execute_step_command(
+                    self.context,
+                    state,
+                    step,
+                    dict(zip(step.inputs, input_paths)),
+                    artifacts=self.artifacts,
+                )
+                return StepResult(artifacts=dict(persisted.artifacts))
             handler = self.assertion_handlers.get(step.assertion or "")
             if handler is None:
                 raise HookError(f"Unknown assertion handler: {step.assertion}")
@@ -151,6 +212,54 @@ class WorkflowEngine:
 
         raise HookError(f"Unsupported step type: {step.type}")
 
+    def _resolve_plugin_inputs(
+        self, state: ModuleRuntimeState, step: StepConfig
+    ) -> dict[str, pathlib.Path]:
+        """Resolve declared inputs in declaration order for a callback."""
+
+        return {
+            reference: self.artifacts.resolve_input(state, reference)
+            for reference in step.inputs
+        }
+
+    def _dispatch_plugin(
+        self,
+        state: ModuleRuntimeState,
+        step: StepConfig,
+        input_paths: dict[str, pathlib.Path],
+    ) -> Any:
+        dispatcher = self._plugin_dispatcher
+        if dispatcher is None:  # pragma: no cover - only direct private calls
+            dispatcher = PluginDispatcher()
+        return dispatcher.dispatch(self.context, state, step, input_paths)
+
+    def _persist_plugin_collect(
+        self, state: ModuleRuntimeState, step: StepConfig, result: CollectorResult
+    ) -> StepResult:
+        # Serialize and enforce both limits before the first write/register.
+        serialized = self.artifacts.serialize_plugin_artifacts(result.artifacts)
+        artifacts: dict[str, pathlib.Path] = {}
+        for artifact_name, content in serialized.items():
+            artifacts[artifact_name] = self.artifacts.write_bytes(
+                state, state.step_index, step.id, artifact_name, content
+            )
+        metadata = dict(result.metadata)
+        if result.skip_module:
+            metadata["skip_module"] = True
+            metadata["skip_reason"] = result.skip_reason
+        return StepResult(artifacts=artifacts, metadata=metadata)
+
+    def _persist_plugin_result(
+        self, state: ModuleRuntimeState, step: StepConfig, payload: dict[str, Any]
+    ) -> pathlib.Path:
+        # Use the same bounded serializer as collector artifacts.  Validation
+        # happens first, and serialization happens before the result is written
+        # or registered.
+        serialized = self.artifacts.serialize_plugin_artifacts({"result.json": payload})
+        return self.artifacts.write_bytes(
+            state, state.step_index, step.id, "result.json", serialized["result.json"]
+        )
+
     def _run_collect(self, state: ModuleRuntimeState, step: StepConfig) -> StepResult:
         handler = self.collectors.get(step.collector or "")
         if handler is None:

package/src/ai_push_hooks/executors/apply.py

@@ -9,6 +9,7 @@ import tempfile
 from dataclasses import dataclass
 from typing import Any
 
+from ..config import resolve_runner_profile
 from ..paths import (
     atomic_write_bytes,
     ensure_private_directory,
@@ -20,14 +21,15 @@ from ..paths import (
     sanitize_file_mode,
 )
 from ..types import HookError, ModuleRuntimeState, RuntimeContext, StepConfig
-from .exec import (
+from ..git_utils import (
     list_repo_changes,
     path_matches,
     resolve_git_common_dir,
     resolve_git_dir,
     run_command,
 )
-from .llm import call_opencode, finalize_opencode_session, validate_opencode_attachments
+from .runner_workflow import run_runner_once
+from .runners.opencode_support import validate_hook_owned_artifacts
 
 METADATA_MAX_FILES = 20_000
 METADATA_MAX_BYTES = 64 * 1024 * 1024
@@ -354,6 +356,8 @@ def _copy_checkout_to_staging(
     context: RuntimeContext,
     staging_root: pathlib.Path,
     allow_paths: tuple[str, ...],
+    *,
+    project_access: str = "artifacts",
 ) -> dict[str, DestinationState]:
     repo_root = context.repo_root
     git_roots = (
@@ -364,16 +368,25 @@ def _copy_checkout_to_staging(
     copied_bytes = 0
     baselines: dict[str, DestinationState] = {}
     resolved_repo_root = repo_root.resolve(strict=True)
-    allowed_paths = {
-        relative_path
-        for relative_path in _tracked_and_unignored_paths(repo_root)
-        if not _is_protected_path(relative_path)
-        and any(path_matches(relative_path, pattern) for pattern in allow_paths)
-    }
-    allowed_paths -= _ignored_changed_paths(repo_root, allowed_paths)
-    for relative_path in sorted(allowed_paths):
+    checkout_paths = _tracked_and_unignored_paths(repo_root)
+    if project_access == "project":
+        projection_candidates = checkout_paths
+    else:
+        projection_candidates = {
+            relative_path
+            for relative_path in checkout_paths
+            if not _is_protected_path(relative_path)
+            and any(path_matches(relative_path, pattern) for pattern in allow_paths)
+        }
+    ignored_paths = _ignored_changed_paths(repo_root, projection_candidates)
+    projection_paths = projection_candidates - ignored_paths
+    for relative_path in sorted(projection_paths):
+        if _is_protected_path(relative_path):
+            continue
         source = _repo_path_from_git(repo_root, relative_path)
         if path_has_symlink(repo_root, source):
+            if project_access == "project":
+                continue
             raise HookError(
                 f"Allowed checkout path is or traverses a symlink or reparse point: {relative_path}"
             )
@@ -384,7 +397,9 @@ def _copy_checkout_to_staging(
             continue
         if not source.exists():
             continue
-        if not source.is_file():
+        if not stat.S_ISREG(source.lstat().st_mode):
+            if project_access == "project":
+                continue
             raise HookError(f"Allowed checkout path is not a regular file: {relative_path}")
         copied_files += 1
         if copied_files > STAGING_MAX_FILES:
@@ -449,8 +464,11 @@ def _changed_staging_paths(
     unexpected = sorted(
         path
         for path in all_paths
-        if _is_protected_path(path)
-        or not any(path_matches(path, pattern) for pattern in allow_paths)
+        if before.get(path) != after.get(path)
+        and (
+            _is_protected_path(path)
+            or not any(path_matches(path, pattern) for pattern in allow_paths)
+        )
     )
     if unexpected:
         raise HookError("Apply staging workspace contains paths outside allowlist: " + ", ".join(unexpected))
@@ -732,14 +750,33 @@ def _verify_post_propagation_security_state(
         )
 
 
-def _apply_prompt(prompt: str, allow_paths: tuple[str, ...]) -> str:
+def _apply_prompt(
+    prompt: str,
+    allow_paths: tuple[str, ...],
+    *,
+    project_access: str = "artifacts",
+) -> str:
     rendered_paths = "\n".join(f"- {pattern}" for pattern in allow_paths)
+    if project_access == "project":
+        projection_text = (
+            "This workspace contains the eligible readable project projection and may "
+            "include readable repository files beyond the allowlist."
+        )
+    else:
+        projection_text = (
+            "This workspace contains only eligible readable files selected by the "
+            "allowlist."
+        )
     return (
         prompt.rstrip()
-        + "\n\nMANDATORY STAGING WRITE BOUNDARY:\n"
-        + "This workspace contains only approved files. Modify only paths matching:\n"
+        + "\n\nMANDATORY STAGING BOUNDARY:\n"
+        + projection_text
+        + "\nOnly changes to paths matching the allowlist below propagate to the real "
+        "checkout. Any other staging change fails the apply step.\n"
+        + "Allowlisted paths:\n"
         + rendered_paths
-        + "\nDo not create symlinks. Do not use commands, tasks, web access, or external paths.\n"
+        + "\nTool availability is controlled by runner and user policy; this instruction "
+        + "does not impose a universal tool ban. Do not create symlinks.\n"
     )
 
 
@@ -778,11 +815,12 @@ def run_apply_step(
     input_paths: list[pathlib.Path],
     stage_name: str,
 ) -> dict[str, object]:
-    validated_inputs = validate_opencode_attachments(context, input_paths)
+    validated_inputs = validate_hook_owned_artifacts(context, input_paths)
     for input_path in validated_inputs:
         if input_path.name.endswith("issues.json"):
             issues = json.loads(input_path.read_text(encoding="utf-8"))
             if isinstance(issues, list) and not issues:
+                # Legacy compatibility shortcut; keep until an explicit replacement exists.
                 return {"changed": False, "changed_files": [], "skipped": True}
 
     _assert_apply_targets_checked_out_head(context)
@@ -798,17 +836,25 @@ def run_apply_step(
     propagated_expected: dict[str, StagedFile | None] = {}
     with tempfile.TemporaryDirectory(prefix="ai-push-hooks-apply-") as temporary_directory:
         staging_root = pathlib.Path(temporary_directory).resolve(strict=True)
-        destination_baselines = _copy_checkout_to_staging(context, staging_root, step.allow_paths)
+        profile = resolve_runner_profile(context.config, step)
+        destination_baselines = _copy_checkout_to_staging(
+            context,
+            staging_root,
+            step.allow_paths,
+            project_access=profile.project_access,
+        )
         staged_before = _inventory_staging(staging_root)
         try:
-            result = call_opencode(
+            result = run_runner_once(
                 context,
-                stage_name=stage_name,
-                purpose=f"{step.type}:{step.id}",
-                prompt=_apply_prompt(prompt, step.allow_paths),
-                files=validated_inputs,
-                agent="apply",
-                allow_paths=step.allow_paths,
+                step,
+                _apply_prompt(
+                    prompt,
+                    step.allow_paths,
+                    project_access=profile.project_access,
+                ),
+                validated_inputs,
+                stage_name,
                 working_directory=staging_root,
             )
         except Exception as exc:  # noqa: BLE001
@@ -823,13 +869,6 @@ def run_apply_step(
             if call_error is None:
                 call_error = exc
 
-        if result is not None:
-            try:
-                finalize_opencode_session(context, stage_name, result.session_id)
-            except Exception as exc:  # noqa: BLE001
-                if call_error is None:
-                    call_error = exc
-
         _verify_pre_propagation_security_state(
             context,
             baseline,
@@ -840,9 +879,9 @@ def run_apply_step(
         if call_error is not None:
             raise HookError(f"Apply step failed in isolated staging: {call_error}") from call_error
         if result is None:
-            raise HookError("Apply step failed without an OpenCode result")
-        if result.return_code != 0:
-            details = result.stderr.strip() or result.stdout.strip() or f"exit code {result.return_code}"
+            raise HookError("Apply step failed without a runner result")
+        if result.returncode != 0:
+            details = result.stderr.strip() or result.stdout.strip() or f"exit code {result.returncode}"
             raise HookError(f"Apply step failed in isolated staging: {details}")
         propagated_expected = _propagate_staging_changes(
             context,

package/src/ai_push_hooks/executors/ask.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import tempfile
+from typing import Any
+
+from ..types import HookError, RuntimeContext, StepConfig
+
+
+def extract_json_array(text: str) -> list[Any]:
+    start = text.find("[")
+    end = text.rfind("]")
+    if start < 0 or end < start:
+        raise HookError("Could not find JSON array in model output")
+    try:
+        payload = json.loads(text[start : end + 1])
+    except json.JSONDecodeError as exc:
+        raise HookError(f"Failed to parse JSON array from model output: {exc}") from exc
+    if not isinstance(payload, list):
+        raise HookError("Model output JSON is not an array")
+    return payload
+
+
+def extract_json_object(text: str) -> dict[str, Any]:
+    start = text.find("{")
+    end = text.rfind("}")
+    if start < 0 or end < start:
+        raise HookError("Could not find JSON object in model output")
+    try:
+        payload = json.loads(text[start : end + 1])
+    except json.JSONDecodeError as exc:
+        raise HookError(f"Failed to parse JSON object from model output: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise HookError("Model output JSON is not an object")
+    return payload
+
+
+def validate_schema(schema: str | None, payload: Any) -> Any:
+    if schema is None:
+        return payload
+    if schema == "string_array":
+        if not isinstance(payload, list) or not all(isinstance(item, str) for item in payload):
+            raise HookError("Expected schema string_array")
+        return payload
+    if schema == "docs_issue_array":
+        if not isinstance(payload, list):
+            raise HookError("Expected schema docs_issue_array")
+        for item in payload:
+            if not isinstance(item, dict):
+                raise HookError("docs_issue_array items must be objects")
+            if not str(item.get("file", "")).strip() or not str(item.get("description", "")).strip():
+                raise HookError("docs_issue_array items require file and description")
+        return payload
+    if schema == "beads_alignment_result":
+        if not isinstance(payload, dict):
+            raise HookError("Expected schema beads_alignment_result")
+        commands = payload.get("commands", [])
+        if commands is not None and (
+            not isinstance(commands, list) or not all(isinstance(item, str) for item in commands)
+        ):
+            raise HookError("beads_alignment_result.commands must be an array of strings")
+        return payload
+    if schema == "pr_create_payload":
+        if not isinstance(payload, dict):
+            raise HookError("Expected schema pr_create_payload")
+        return payload
+    raise HookError(f"Unsupported schema: {schema}")
+
+
+def _safe_invalid_output(invocation: Any, output: str) -> str:
+    from .runners.contracts import request_sensitive_diagnostics
+
+    request = invocation.request
+    return request_sensitive_diagnostics(request, output, max_chars=400, env=os.environ)
+
+
+def run_ask_step(
+    context: RuntimeContext,
+    step: StepConfig,
+    prompt: str,
+    input_paths: list[pathlib.Path],
+    stage_name: str,
+) -> Any:
+    from .runner_workflow import _finalize_invocation, _invoke_runner, _named_error
+    from ..config import resolve_runner_profile
+
+    total_attempts = context.config.llm.json_max_retries + 1
+    prompt_text = prompt
+    last_error = ""
+    last_output = ""
+    wants_json = bool(step.schema)
+    expects_json_array = step.schema in {"string_array", "docs_issue_array"}
+    session_id: str | None = None
+    resume_session = False
+    selected_profile = step.runner or context.config.llm.runner
+    try:
+        profile = resolve_runner_profile(context.config, step)
+    except Exception as exc:  # noqa: BLE001
+        raise _named_error(selected_profile, "unknown", stage_name, exc) from exc
+    retained_invocation = None
+
+    # Artifact-only analysis must retain its historical empty scratch cwd;
+    # project-aware analysis gets the actual checkout root so the adapter can
+    # provide the selected runner's project-read behavior.
+    if profile.project_access == "project":
+        working_directory = context.repo_root.resolve(strict=True)
+        temporary_directory = None
+    else:
+        temporary_directory = tempfile.TemporaryDirectory(prefix="ai-push-hooks-ask-")
+        working_directory = pathlib.Path(temporary_directory.name).resolve(strict=True)
+
+    try:
+        for attempt in range(1, total_attempts + 1):
+            invocation = _invoke_runner(
+                context,
+                step,
+                prompt_text,
+                input_paths,
+                stage_name,
+                working_directory=working_directory,
+                session_id=session_id,
+                resume_session=resume_session,
+                attempt=attempt,
+                total_attempts=total_attempts,
+                prior_invocation=retained_invocation,
+            )
+            retained_invocation = None
+            result = invocation.result
+            try:
+                if not wants_json:
+                    payload = result.final_text
+                else:
+                    if expects_json_array:
+                        payload = extract_json_array(result.final_text)
+                    else:
+                        payload = extract_json_object(result.final_text)
+                    payload = validate_schema(step.schema, payload)
+            except HookError as exc:
+                last_error = str(exc)
+                last_output = result.final_text
+                if attempt >= total_attempts:
+                    _finalize_invocation(context, invocation, failed=True)
+                    safe_error = _safe_invalid_output(invocation, last_error)
+                    raise HookError(
+                        f"Runner profile `{profile.name}` ({profile.type}) failed at stage "
+                        f"`{stage_name}`: invalid JSON: {safe_error}. "
+                        f"{_safe_invalid_output(invocation, last_output)}"
+                    ) from exc
+
+                snippet = last_output[: context.config.llm.invalid_json_feedback_max_chars]
+                suffix = (
+                    "Return ONLY valid JSON array."
+                    if expects_json_array
+                    else "Return ONLY valid JSON object."
+                )
+                prompt_text = (
+                    prompt
+                    + "\n\nIMPORTANT: Your previous response was invalid JSON and could not be parsed.\n"
+                    + f"Parse error: {last_error}\n"
+                    + suffix
+                    + "\nPrevious invalid output:\n```text\n"
+                    + snippet
+                    + "\n```"
+                )
+
+                session = result.session
+                can_resume = bool(
+                    getattr(getattr(invocation.runner, "capabilities", None), "supports_resume", False)
+                    and session is not None
+                    and session.session_id
+                    and session.resumable
+                )
+                if context.config.llm.json_retry_new_session or not can_resume:
+                    if not session or not session.session_id:
+                        retry_reason = "session absent"
+                    elif context.config.llm.json_retry_new_session:
+                        retry_reason = "fresh session configured"
+                    else:
+                        retry_reason = "runner does not support resume"
+                    retry_message = "Retrying with a fresh runner invocation."
+                    if retry_reason == "runner does not support resume":
+                        retry_message = (
+                            "Retrying with a fresh runner invocation; unsupported session reuse."
+                        )
+                    elif retry_reason == "session absent":
+                        retry_message = (
+                            "Retrying with a fresh runner invocation; no reusable session was captured."
+                        )
+                    context.logger.status(
+                        "llm.retry_fresh_session",
+                        retry_message,
+                        stage_name=stage_name,
+                        runner_profile=profile.name,
+                        runner_type=profile.type,
+                        reason=retry_reason,
+                    )
+                    _finalize_invocation(context, invocation, failed=True)
+                    session_id = None
+                    resume_session = False
+                else:
+                    # Keep the exact captured session ID.  Do not invent a
+                    # provider-specific resume command for completion output.
+                    session_id = session.session_id
+                    resume_session = True
+                    retained_invocation = invocation
+                    # The invocation itself completed, although its response
+                    # failed downstream validation; report truthful metadata
+                    # before reusing the retained session.
+                    from .runner_workflow import _completion
+
+                    _completion(context, invocation, failed=True)
+                continue
+
+            _finalize_invocation(context, invocation, failed=False)
+            return payload
+        raise HookError(
+            f"Runner profile `{profile.name}` ({profile.type}) failed at stage `{stage_name}`: "
+            "model did not return a valid result"
+        )  # pragma: no cover
+    finally:
+        if temporary_directory is not None:
+            temporary_directory.cleanup()