okstra 0.207.1 → 0.209.0

package/runtime/python/okstra_ctl/business_flow/hooks.py

@@ -0,0 +1,221 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..json_boundary import JsonBoundaryError, load_owned_object
+from ..report_language import resolve_report_language
+from .contracts import (
+    BusinessFlowError,
+    FlowRequest,
+    artifact_path,
+    business_root,
+    fingerprint,
+    read_artifact,
+    write_artifact,
+)
+from .engine import explain_flow, load_execution
+from .invocation import FlowExecutor
+from .source import candidate_projects, capture_projects, changed_projects
+from .store import knowledge_packet, read_task_links, record_task_execution
+
+
+def prepare_task_knowledge(
+    project_root: Path,
+    instruction_set: Path,
+    ctx: dict,
+    question: str,
+    executor: FlowExecutor | None = None,
+) -> str:
+    source = (
+        ctx.get("VERIFICATION_WORKTREE_PATH")
+        or ctx.get("EXECUTOR_WORKTREE_PATH")
+        or str(project_root)
+    )
+    try:
+        business_root(project_root)
+        request = {
+            "taskKey": ctx["TASK_KEY"],
+            "taskType": ctx["TASK_TYPE"],
+            "question": question,
+            "sourceRoot": source,
+            "reportLanguage": resolve_report_language(project_root, {}, ctx),
+            "hostRuntime": ctx.get("HOST_RUNTIME")
+            or ctx.get("LEAD_RUNTIME", "claude-code"),
+        }
+        manifest = ctx.get("RUN_MANIFEST_RELATIVE_PATH")
+        path = (
+            artifact_path(
+                project_root, "task-requests", fingerprint(manifest) + ".json"
+            )
+            if manifest
+            else instruction_set / "business-flow-request.json"
+        )
+        if not path.resolve().is_relative_to((project_root / ".okstra").resolve()):
+            raise BusinessFlowError("business request path escapes project artifacts")
+        write_artifact(path, request, "taskRequest")
+        if ctx["TASK_TYPE"] == "implementation":
+            _ensure_pre_explanation(project_root, request, executor)
+    except (OSError, ValueError, JsonBoundaryError) as exc:
+        return f"## Shared Business Knowledge\n\nBusiness preparation failed: {exc}\n"
+    return knowledge_packet(project_root, question, Path(source))
+
+
+def _flow_request(
+    project_root: Path,
+    request: dict[str, Any],
+    mode: str,
+    baseline: str = "",
+    artifacts: tuple[str, ...] = (),
+) -> FlowRequest:
+    return FlowRequest(
+        project_root=project_root,
+        question=request["question"],
+        mode=mode,
+        task_key=request["taskKey"],
+        baseline=baseline,
+        source_root=Path(request["sourceRoot"]),
+        report_language=request["reportLanguage"],
+        source_artifacts=artifacts,
+        host_runtime=request["hostRuntime"],
+    )
+
+
+def _ensure_pre_explanation(
+    project_root: Path, request: dict[str, Any], executor: FlowExecutor | None
+) -> dict[str, Any]:
+    links = read_task_links(project_root, request["taskKey"])["executions"]
+    prior = next((row for row in reversed(links) if row["mode"] == "pre"), None)
+    flow_request = _flow_request(project_root, request, "pre")
+    if prior:
+        execution = load_execution(project_root, prior["id"])
+        current = capture_projects(candidate_projects(flow_request))
+        if not changed_projects(execution["projects"], current):
+            return prior
+    execution = explain_flow(flow_request, executor)
+    return record_task_execution(flow_request, execution, fingerprint(request))
+
+
+def finalize_business_flow(
+    project_root: Path,
+    manifest: dict,
+    data_path: Path,
+    executor: FlowExecutor | None = None,
+) -> dict[str, Any] | None:
+    instruction_root = manifest.get("instructionSetPath", "")
+    if not instruction_root:
+        return None
+    manifest_path = manifest.get("runManifestPath")
+    request_path = (
+        artifact_path(
+            project_root, "task-requests", fingerprint(manifest_path) + ".json"
+        )
+        if manifest_path
+        else project_root / instruction_root / "business-flow-request.json"
+    )
+    if (
+        not request_path.resolve().is_relative_to(project_root.resolve())
+        or not request_path.exists()
+    ):
+        return None
+    try:
+        request = read_artifact(request_path, "taskRequest")
+        if request["taskKey"] != manifest.get("taskKey") or (
+            manifest.get("taskType") and request["taskType"] != manifest["taskType"]
+        ):
+            raise BusinessFlowError(
+                "business request belongs to a different task or phase"
+            )
+        record = load_owned_object(
+            data_path, artifact="validated business contribution source"
+        )
+        digest = fingerprint({"record": record, "request": request})
+        links = read_task_links(project_root, request["taskKey"])
+        previous = [row for row in links["executions"] if row["inputDigest"] == digest]
+        if not previous:
+            _complete_task_effects(project_root, request, data_path, digest, executor)
+        links = read_task_links(project_root, request["taskKey"])
+        sidecar = data_path.with_name(data_path.name + ".business-flow.json")
+        write_artifact(sidecar, links, "taskLink")
+        return links
+    except (OSError, ValueError, JsonBoundaryError) as exc:
+        links = _failed_task_link(manifest.get("taskKey", ""), str(exc))
+        write_artifact(
+            data_path.with_name(data_path.name + ".business-flow.json"),
+            links,
+            "taskLink",
+        )
+        return links
+
+
+def _failed_task_link(task_key: str, error: str) -> dict[str, Any]:
+    failure = {
+        "id": "",
+        "mode": "unknown",
+        "status": "failed",
+        "inputDigest": "",
+        "reports": {},
+        "summary": "",
+        "error": error,
+    }
+    links = {
+        "schemaVersion": 1,
+        "taskKey": task_key,
+        "executions": [failure],
+    }
+    return links
+
+
+def _complete_task_effects(
+    project_root: Path,
+    request: dict[str, Any],
+    data_path: Path,
+    digest: str,
+    executor: FlowExecutor | None,
+) -> None:
+    artifacts = (str(data_path),)
+    phase = request["taskType"]
+    if phase.endswith("-analysis") or phase in {
+        "requirements-discovery",
+        "improvement-discovery",
+        "technical-verification",
+    }:
+        mode = "pre"
+    elif phase == "final-verification":
+        mode = "post"
+    else:
+        mode = "contribute"
+    prior = read_task_links(project_root, request["taskKey"])["executions"]
+    baseline = next((row["id"] for row in reversed(prior) if row["mode"] == "pre"), "")
+    flow_request = _flow_request(
+        project_root, request, mode, baseline if mode == "post" else "", artifacts
+    )
+    execution = explain_flow(flow_request, executor)
+    record_task_execution(flow_request, execution, digest)
+
+
+def report_links(data_path: Path) -> list[dict[str, Any]]:
+    sidecar = data_path.with_name(data_path.name + ".business-flow.json")
+    if not sidecar.exists():
+        return []
+    try:
+        return read_artifact(sidecar, "taskLink")["executions"]
+    except (OSError, ValueError, JsonBoundaryError) as exc:
+        return _failed_task_link("", str(exc))["executions"]
+
+
+def markdown_report_links(data_path: Path) -> str:
+    rows = report_links(data_path)
+    if not rows:
+        return ""
+    lines = ["", "## Business Flow Explanations", ""]
+    for row in rows:
+        lines.append(f"- {row['mode']}: {row['status']}. {row['summary']}")
+        lines.extend(f"  - [{kind}]({path})" for kind, path in row["reports"].items())
+        if row["error"]:
+            lines.append(f"  - Explanation error: {row['error']}")
+        if row["id"]:
+            lines.append(
+                f"  - Retry: `okstra explain-flow rerun --execution {row['id']}`"
+            )
+    return "\n".join(lines) + "\n"

package/runtime/python/okstra_ctl/business_flow/invocation.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import contextlib
+import io
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from ..agent.invocation import verify_agent_invocation
+from ..agent.standalone import (
+    StandaloneInvocationRequest,
+    prepare_standalone_invocation,
+)
+from ..assignment_environment import load_assignment_context
+from ..dispatch_core import DispatchError, verify_served_model_ref
+from ..domain.provider import ServedModelAttestation
+from ..domain.worker_exec import WorkerExecRequest
+from ..domain.worker_role import role_spec
+from ..json_boundary import load_owned_object
+from ..model_pool import ModelPool
+from ..operation_invocation import resolve_operation_slots
+from ..paths import find_asset_root
+from ..registry.provider_registry import default_provider_registry
+from ..worker_request import build_request
+from ..worker_runner import QUIET, run_worker
+from ..write_policy import build_write_policy, derive_write_enforcement
+from .contracts import OPERATION, BusinessFlowError, FlowRequest
+
+
+@dataclass(frozen=True)
+class PreparedCall:
+    project_root: Path
+    prompt_path: Path
+    metadata_path: Path
+
+
+class FlowExecutor(Protocol):
+    def prepare(
+        self, request: FlowRequest, execution_id: str, instructions: str
+    ) -> PreparedCall: ...
+    def invoke(self, call: PreparedCall) -> bytes: ...
+
+
+class ProviderFlowExecutor:
+    def prepare(
+        self, request: FlowRequest, execution_id: str, instructions: str
+    ) -> PreparedCall:
+        contract_root = find_asset_root(("agents", "operations", OPERATION + ".json"))
+        if contract_root is None:
+            raise BusinessFlowError(
+                "business investigation operation contract is unavailable"
+            )
+        pool = ModelPool.from_registry(default_provider_registry())
+        slot = resolve_operation_slots(
+            OPERATION, contract_root=contract_root, pool=pool
+        )[0]
+        root = request.project_root / ".okstra" / "agent-invocations" / OPERATION
+        if not root.resolve().is_relative_to(request.project_root.resolve()):
+            raise BusinessFlowError("invocation root escapes project")
+        root.mkdir(parents=True, exist_ok=True)
+        instruction = root / f"{execution_id}.instructions.md"
+        instruction.write_text(instructions, encoding="utf-8")
+        context = load_assignment_context(
+            host_runtime=request.host_runtime,
+            terminal_backend="cli-wrapper",
+            execution_provider_ids=(slot.provider_id,),
+            include_native_provider=False,
+        )
+        prepared = prepare_standalone_invocation(
+            StandaloneInvocationRequest(
+                project_root=request.project_root,
+                invocation_id=execution_id,
+                audience="business-flow-investigator",
+                purpose=OPERATION,
+                context=context,
+                provider=slot.provider_id,
+                model_role=slot.role_id,
+                model=slot.model_ref,
+                instruction_path=instruction,
+                prompt_path=root / f"{execution_id}.prompt.md",
+                requested_runner="cli-wrapper",
+            )
+        )
+        return PreparedCall(
+            request.project_root,
+            prepared.prompt_path,
+            prepared.metadata_path,
+        )
+
+    def invoke(self, call: PreparedCall) -> bytes:
+        violations = verify_agent_invocation(
+            metadata_path=call.metadata_path,
+            project_root=call.project_root,
+            expected_run_manifest_path=None,
+            expected_audience="business-flow-investigator",
+        )
+        if violations:
+            raise BusinessFlowError(
+                "business invocation verification failed: " + "; ".join(violations)
+            )
+        metadata = load_owned_object(
+            call.metadata_path, artifact="business flow invocation"
+        )
+        assignment = metadata["modelAssignment"]
+        if assignment["runner"] != "cli-wrapper":
+            raise BusinessFlowError(
+                "automatic business investigation requires a CLI execution binding"
+            )
+        registry = default_provider_registry()
+        provider = registry.resolve(assignment["provider"])
+        pool = ModelPool.from_registry(registry)
+        selected = pool.resolve_alias(assignment["provider"], assignment["model"])
+        request = _read_only_worker_request(call, assignment)
+        output, errors = io.StringIO(), io.StringIO()
+        with contextlib.redirect_stdout(output), contextlib.redirect_stderr(errors):
+            code = run_worker(
+                provider.exec_strategy,
+                request,
+                presentation=QUIET,
+                log_path=call.prompt_path.with_suffix(".log"),
+                status_path=call.prompt_path.with_suffix(".status.json"),
+                status_extra={
+                    "writePolicy": request.policy.write_policy.to_payload(),
+                    "writeEnforcement": request.policy.write_enforcement.to_payload(),
+                },
+                served_model_normalizer=provider.served_model_normalizer,
+                served_model_verifier=lambda attestation: _served_model_failure(
+                    str(selected.model_ref), attestation, pool
+                ),
+            )
+        if code:
+            raise BusinessFlowError(
+                f"business investigator exited {code}: {errors.getvalue().strip()}"
+            )
+        return output.getvalue().encode("utf-8")
+
+
+def _read_only_worker_request(
+    call: PreparedCall, assignment: dict[str, str]
+) -> WorkerExecRequest:
+    policy = build_write_policy(
+        {
+            "role": "analyser",
+            "projectRoot": str(call.project_root),
+            "artifactPaths": [str(call.prompt_path.relative_to(call.project_root))],
+        },
+        {"workerWriteCapability": {"maxBoundaryPrecision": "none"}},
+        None,
+    )
+    enforcement = derive_write_enforcement(policy, "none", role="analyser")
+    return build_request(
+        prompt_text=call.prompt_path.read_text(encoding="utf-8"),
+        model=assignment["modelExecutionValue"],
+        project_root=call.project_root,
+        worktree_path=None,
+        role="analyser",
+        idle_timeout_seconds=role_spec("analyser").idle_timeout_seconds,
+        write_policy=policy,
+        write_enforcement=enforcement,
+    )
+
+
+def _served_model_failure(
+    model_ref: str, attestation: ServedModelAttestation, pool: ModelPool
+) -> str:
+    try:
+        verify_served_model_ref(model_ref, attestation, pool=pool)
+    except DispatchError as exc:
+        return str(exc)
+    return ""

package/runtime/python/okstra_ctl/business_flow/report.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from okstra_vendor.jinja2 import Environment, StrictUndefined, select_autoescape
+
+from ..md_table import to_cell_text
+from ..paths import find_asset_root
+from ..report_template_loader import report_template_loader
+from .contracts import BusinessFlowError, FlowExecution, artifact_path
+from .store import read_knowledge
+
+
+def render_explanation(project_root: Path, execution: FlowExecution) -> dict[str, str]:
+    root = find_asset_root(("templates", "reports", "business-flow.template.md"))
+    if root is None:
+        raise BusinessFlowError("business flow report templates are unavailable")
+    templates = root / "templates" / "reports"
+    env = Environment(
+        loader=report_template_loader(templates),
+        autoescape=select_autoescape(("html",)),
+        undefined=StrictUndefined,
+    )
+    env.filters["cell"] = to_cell_text
+    context = {
+        "execution": execution,
+        "flow": execution["result"],
+        "claims": [
+            row
+            for row in read_knowledge(project_root)["claims"]
+            if row["key"] in {fact["key"] for fact in execution["result"]["facts"]}
+        ],
+        "css": (templates / "html" / "assets" / "base.css").read_text(encoding="utf-8"),
+    }
+    reports = {}
+    for kind, template in (
+        ("markdown", "business-flow.template.md"),
+        ("html", "html/business-flow.template.html"),
+    ):
+        suffix = ".md" if kind == "markdown" else ".html"
+        path = artifact_path(
+            project_root, "executions", execution["id"], "report" + suffix
+        )
+        rendered = env.get_template(template).render(**context)
+        temporary = path.with_suffix(suffix + ".tmp")
+        temporary.write_text(rendered, encoding="utf-8")
+        temporary.replace(path)
+        reports[kind] = str(path)
+    return reports

package/runtime/python/okstra_ctl/business_flow/source.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from ..json_boundary import load_owned_object
+from ..manager_store import discover_projects
+from ..paths import okstra_home
+from .contracts import (
+    BusinessEvidence,
+    BusinessFlowError,
+    FlowRequest,
+    ProjectCandidate,
+    SourceSnapshot,
+    fingerprint,
+)
+
+
+def candidate_projects(request: FlowRequest) -> list[ProjectCandidate]:
+    root = request.project_root.resolve()
+    config = root / ".okstra" / "project.json"
+    project_id = root.name
+    if config.is_file():
+        project_id = str(
+            load_owned_object(config, artifact="project configuration").get("projectId")
+            or project_id
+        )
+    candidates = {
+        row["projectId"]: {"projectId": row["projectId"], "root": row["projectRoot"]}
+        for row in discover_projects(okstra_home())
+    }
+    candidates[project_id] = {
+        "projectId": project_id,
+        "root": str(request.source_root or root),
+    }
+    return sorted(candidates.values(), key=lambda row: row["projectId"])
+
+
+def git_output(root: Path, *args: str) -> bytes:
+    result = subprocess.run(
+        ["git", "-C", str(root), *args], capture_output=True, check=False
+    )
+    if result.returncode:
+        raise BusinessFlowError(
+            f"Git source inspection failed at {root}: {result.stderr.decode(errors='replace').strip()}"
+        )
+    return result.stdout
+
+
+def source_inventory(root: Path) -> list[str]:
+    names = git_output(
+        root, "ls-files", "-z", "--cached", "--others", "--exclude-standard"
+    )
+    return sorted(
+        {
+            os.fsdecode(name)
+            for name in names.split(b"\0")
+            if name and ".okstra" not in Path(os.fsdecode(name)).parts
+        }
+    )
+
+
+def capture_project(candidate: ProjectCandidate) -> SourceSnapshot:
+    root = Path(candidate["root"])
+    state: SourceSnapshot = {
+        **candidate,
+        "head": "",
+        "digest": "",
+        "files": {},
+        "dirty": {},
+        "gaps": [],
+    }
+    try:
+        root = root.resolve(strict=True)
+        before = git_output(root, "status", "--porcelain=v1", "-z")
+        state["head"] = git_output(root, "rev-parse", "HEAD").decode().strip()
+        dirty = {
+            os.fsdecode(name)
+            for name in git_output(
+                root, "diff", "--no-ext-diff", "--name-only", "-z", "HEAD"
+            ).split(b"\0")
+            if name
+        }
+        tracked = {
+            os.fsdecode(name)
+            for name in git_output(root, "ls-files", "-z").split(b"\0")
+            if name
+        }
+        for name in source_inventory(root):
+            _capture_file(root, name, name in dirty or name not in tracked, state)
+        index = git_output(
+            root, "diff", "--no-ext-diff", "--no-textconv", "--cached", "--binary"
+        )
+        state["indexDigest"] = hashlib.sha256(index).hexdigest()
+        state["indexPatch"] = base64.b64encode(index).decode("ascii")
+        state["statusDigest"] = hashlib.sha256(before).hexdigest()
+        if before != git_output(root, "status", "--porcelain=v1", "-z"):
+            state["gaps"].append("Source status changed while collecting the baseline")
+        state["digest"] = fingerprint(
+            {
+                "head": state["head"],
+                "files": state["files"],
+                "index": state["indexDigest"],
+            }
+        )
+    except (OSError, BusinessFlowError) as exc:
+        state["gaps"].append(str(exc))
+    return state
+
+
+def _capture_file(root: Path, name: str, dirty: bool, state: SourceSnapshot) -> None:
+    path = root / name
+    if path.is_symlink():
+        state["gaps"].append(f"Symbolic link source was not followed: {name}")
+        state["files"][name] = fingerprint({"symlink": os.readlink(path)})
+        return
+    if not path.exists():
+        state["files"][name] = "deleted"
+        return
+    if not path.resolve().is_relative_to(root):
+        raise BusinessFlowError(f"source path escapes candidate: {name}")
+    body = path.read_bytes()
+    state["files"][name] = hashlib.sha256(body).hexdigest()
+    if dirty:
+        state["dirty"][name] = base64.b64encode(body).decode("ascii")
+
+
+def capture_projects(candidates: list[ProjectCandidate]) -> list[SourceSnapshot]:
+    return [capture_project(candidate) for candidate in candidates]
+
+
+def validate_evidence(
+    evidence: BusinessEvidence, projects: list[SourceSnapshot]
+) -> None:
+    project = next(
+        (row for row in projects if row["projectId"] == evidence["projectId"]), None
+    )
+    if project is None or evidence["path"] not in project["files"]:
+        raise BusinessFlowError(
+            f"evidence is outside the captured source inventory: {evidence['path']}"
+        )
+    path = Path(project["root"]) / evidence["path"]
+    if path.is_symlink() or not path.resolve().is_relative_to(
+        Path(project["root"]).resolve()
+    ):
+        raise BusinessFlowError("evidence follows an uncaptured symbolic link")
+    body = path.read_bytes()
+    if hashlib.sha256(body).hexdigest() != project["files"][evidence["path"]]:
+        raise BusinessFlowError(
+            f"evidence changed after the baseline: {evidence['path']}"
+        )
+    lines = body.decode("utf-8").splitlines()
+    start, end = evidence["line"], evidence["endLine"]
+    if end < start or end > len(lines):
+        raise BusinessFlowError("evidence line range is invalid")
+    if evidence["excerpt"] != "\n".join(lines[start - 1 : end]):
+        raise BusinessFlowError(
+            f"evidence excerpt does not match source: {evidence['path']}:{start}"
+        )
+
+
+def changed_projects(
+    before: list[SourceSnapshot], after: list[SourceSnapshot]
+) -> list[str]:
+    prior = {row["projectId"]: row["digest"] for row in before}
+    current = {row["projectId"]: row["digest"] for row in after}
+    return sorted(
+        key
+        for key in prior.keys() | current.keys()
+        if prior.get(key) != current.get(key)
+    )
+
+
+def source_changes(
+    baseline: list[SourceSnapshot], current: list[SourceSnapshot]
+) -> list[dict[str, Any]]:
+    prior = {row["projectId"]: row for row in baseline}
+    changes = []
+    for project in current:
+        old = prior.get(project["projectId"])
+        if old is None or not old["digest"]:
+            changes.append(
+                {
+                    "projectId": project["projectId"],
+                    "baselineAvailable": False,
+                    "paths": [],
+                }
+            )
+            continue
+        paths = sorted(
+            path
+            for path in old["files"].keys() | project["files"].keys()
+            if old["files"].get(path) != project["files"].get(path)
+        )
+        changes.append(
+            {
+                "projectId": project["projectId"],
+                "baselineAvailable": True,
+                "paths": paths,
+            }
+        )
+    return changes