ldw-agent 0.2.1__py3-none-any.whl

ldw_agent/__init__.py

@@ -0,0 +1,101 @@
+"""Capability-bounded local coding-agent runtimes."""
+
+from ldw_agent.broker import AgentBroker
+from ldw_agent.consent import ProjectConsentStore
+from ldw_agent.errors import (
+    AgentContextError,
+    AgentLimitError,
+    AgentPolicyError,
+    AgentProtocolError,
+    AgentRuntimeError,
+    AgentSchemaError,
+)
+from ldw_agent.inventory import (
+    MirrorSession,
+    TrackedInventoryBuilder,
+    ephemeral_tracked_mirror,
+    exclusion_reason,
+)
+from ldw_agent.models import (
+    AgentCapability,
+    AgentChangeKind,
+    AgentEvent,
+    AgentEventKind,
+    AgentFileChange,
+    AgentLimits,
+    AgentRequest,
+    AgentResult,
+    AgentRuntimeName,
+    AgentStatus,
+    CapabilityPolicy,
+    ConsentRecord,
+    ConsentScope,
+    ProjectRuntimePreference,
+    RuntimeProbe,
+    TerminalInvocation,
+    TrackedFile,
+    TrackedInventory,
+    request_context_hash,
+)
+from ldw_agent.process import (
+    BoundedProcessExecutor,
+    ParsedProviderLine,
+    ProcessTranscript,
+    validate_exact_terminal,
+)
+from ldw_agent.providers import (
+    AgentRuntime,
+    ClaudeAgentRuntime,
+    CodexAgentRuntime,
+    UnavailableAgentRuntime,
+)
+from ldw_agent.schema import (
+    canonical_schema_json,
+    parse_and_validate_structured_output,
+    validate_schema_definition,
+)
+
+__all__ = [
+    "AgentBroker",
+    "AgentCapability",
+    "AgentChangeKind",
+    "AgentContextError",
+    "AgentEvent",
+    "AgentEventKind",
+    "AgentFileChange",
+    "AgentLimitError",
+    "AgentLimits",
+    "AgentPolicyError",
+    "AgentProtocolError",
+    "AgentRequest",
+    "AgentResult",
+    "AgentRuntime",
+    "AgentRuntimeError",
+    "AgentRuntimeName",
+    "AgentSchemaError",
+    "AgentStatus",
+    "BoundedProcessExecutor",
+    "CapabilityPolicy",
+    "ClaudeAgentRuntime",
+    "CodexAgentRuntime",
+    "ConsentRecord",
+    "ConsentScope",
+    "MirrorSession",
+    "ParsedProviderLine",
+    "ProcessTranscript",
+    "ProjectConsentStore",
+    "ProjectRuntimePreference",
+    "RuntimeProbe",
+    "TerminalInvocation",
+    "TrackedFile",
+    "TrackedInventory",
+    "TrackedInventoryBuilder",
+    "UnavailableAgentRuntime",
+    "canonical_schema_json",
+    "ephemeral_tracked_mirror",
+    "exclusion_reason",
+    "parse_and_validate_structured_output",
+    "request_context_hash",
+    "validate_exact_terminal",
+    "validate_schema_definition",
+]

ldw_agent/broker.py

@@ -0,0 +1,489 @@
+from __future__ import annotations
+
+import asyncio
+import os
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+
+from ldw_agent.consent import ProjectConsentStore
+from ldw_agent.errors import (
+    AgentLimitError,
+    AgentPolicyError,
+    AgentRuntimeError,
+    AgentSchemaError,
+)
+from ldw_agent.inventory import (
+    TrackedInventoryBuilder,
+    ephemeral_tracked_mirror,
+)
+from ldw_agent.models import (
+    AgentCapability,
+    AgentEvent,
+    AgentEventKind,
+    AgentRequest,
+    AgentResult,
+    AgentRuntimeName,
+    AgentStatus,
+    RuntimeProbe,
+    request_context_hash,
+)
+from ldw_agent.process import BoundedProcessExecutor
+from ldw_agent.providers import (
+    AgentRuntime,
+    ClaudeAgentRuntime,
+    CodexAgentRuntime,
+)
+from ldw_agent.schema import (
+    canonical_schema_json,
+    parse_and_validate_structured_output,
+)
+from local_devops_workbench.redaction import Redactor
+
+NO_RUNTIME_REASON = "no eligible coding-agent runtime is installed"
+NO_CONSENT_REASON = "coding-agent execution requires explicit project consent"
+MISSING_CAPABILITY_REASON = "coding-agent execution exceeds the granted capability policy"
+MAX_TRANSIENT_RETRIES = 2
+TRANSIENT_FAILURE_MARKERS = (
+    "429",
+    "502",
+    "503",
+    "connection reset",
+    "rate limit",
+    "temporarily unavailable",
+    "temporary failure",
+)
+
+
+class AgentBroker:
+    """Select and execute one consented runtime against an isolated tracked-file mirror."""
+
+    def __init__(
+        self,
+        *,
+        consent_store: ProjectConsentStore,
+        runtimes: Sequence[AgentRuntime] | None = None,
+        inventory_builder: TrackedInventoryBuilder | None = None,
+        process_executor: BoundedProcessExecutor | None = None,
+        source_environment: Mapping[str, str] | None = None,
+    ) -> None:
+        configured = tuple(
+            (CodexAgentRuntime(), ClaudeAgentRuntime()) if runtimes is None else runtimes
+        )
+        if any(not isinstance(runtime.name, AgentRuntimeName) for runtime in configured):
+            raise ValueError("agent runtimes must use a typed runtime name")
+        by_name = {runtime.name: runtime for runtime in configured}
+        if len(by_name) != len(configured):
+            raise ValueError("agent runtime names must be unique")
+        if AgentRuntimeName.UNAVAILABLE in by_name:
+            raise ValueError("the unavailable runtime is broker-owned fallback state")
+        self._runtimes = by_name
+        self._consent_store = consent_store
+        self._inventory_builder = inventory_builder
+        self._process_executor = process_executor or BoundedProcessExecutor()
+        environment = os.environ if source_environment is None else source_environment
+        self._source_environment = dict(environment)
+        self._redactor = Redactor.from_environment(self._source_environment)
+
+    def probe(self) -> tuple[RuntimeProbe, ...]:
+        """Probe configured providers in stable runtime-name order."""
+        return tuple(
+            self._safe_probe(self._runtimes[name])
+            for name in sorted(self._runtimes, key=lambda item: item.value)
+        )
+
+    def eligible_runtimes(self, request: AgentRequest) -> tuple[RuntimeProbe, ...]:
+        """Return available providers allowed by the policy, without reading project files."""
+        probes: list[RuntimeProbe] = []
+        for name in self._ordered_runtime_names(request):
+            runtime = self._runtimes.get(name)
+            if runtime is None or not runtime.required_capabilities.issubset(
+                request.policy.capabilities
+            ):
+                continue
+            probe = self._safe_probe(runtime)
+            if probe.available:
+                probes.append(probe)
+        return tuple(probes)
+
+    async def run(self, request: AgentRequest) -> AgentResult:
+        runtime: AgentRuntime | None = None
+        probe: RuntimeProbe | None = None
+        context_hash: str | None = None
+        try:
+            if request.output_schema is not None:
+                canonical_schema_json(request.output_schema)
+            selection = self._select_runtime(request)
+            if isinstance(selection, AgentResult):
+                return selection
+            runtime, probe = selection
+
+            # The repository is deliberately not read until both capability and consent
+            # checks have selected one provider.
+            inventory_builder = self._inventory_builder or TrackedInventoryBuilder()
+            inventory = inventory_builder.build(request.project_root, request.policy)
+            context_hash = request_context_hash(request, inventory)
+            with ephemeral_tracked_mirror(inventory, request.policy) as mirror:
+                schema_path = self._write_schema(request, mirror.control_root)
+                # Consume one-shot consent at the last synchronous boundary before
+                # process creation. A revoked or concurrently consumed record fails closed.
+                if not self._consent_store.authorized(
+                    project_id=request.project_id,
+                    project_root=request.project_root,
+                    runtime=runtime.name,
+                    policy=request.policy,
+                    consume=True,
+                ):
+                    return self._result(
+                        request,
+                        runtime=runtime.name,
+                        status=AgentStatus.DENIED,
+                        error=NO_CONSENT_REASON,
+                        probe=probe,
+                        context_hash=context_hash,
+                    )
+                execution_request = request
+                collected_events: list[AgentEvent] = []
+                observed_output_bytes = 0
+                transient_retries = 0
+                correction_attempted = False
+                while True:
+                    invocation = runtime.build_invocation(
+                        execution_request,
+                        mirror,
+                        probe,
+                        self._source_environment,
+                        schema_path=schema_path,
+                    )
+                    expected = runtime.build_invocation(
+                        execution_request,
+                        mirror,
+                        probe,
+                        self._source_environment,
+                        schema_path=schema_path,
+                    )
+                    self._validate_probe_binding(runtime, probe, invocation.argv[0])
+                    self._validate_probe_binding(runtime, probe, expected.argv[0])
+                    transcript = await self._process_executor.run(
+                        invocation,
+                        expected=expected,
+                        parser=runtime,
+                        limits=request.policy.limits,
+                    )
+                    observed_output_bytes += len(transcript.stdout.encode()) + len(
+                        transcript.stderr.encode()
+                    )
+                    if observed_output_bytes > request.policy.limits.max_output_bytes:
+                        raise AgentLimitError("provider retry output exceeds max_output_bytes")
+                    _append_events(collected_events, transcript.events)
+                    if len(collected_events) > request.policy.limits.max_events:
+                        raise AgentLimitError("provider retry output exceeds max_events")
+                    if transcript.returncode != 0:
+                        detail = transcript.stderr.strip() or (
+                            f"{runtime.name.value} exited {transcript.returncode}"
+                        )
+                        if transient_retries < MAX_TRANSIENT_RETRIES and _is_transient_failure(
+                            detail
+                        ):
+                            transient_retries += 1
+                            collected_events.append(
+                                _broker_event(
+                                    len(collected_events),
+                                    runtime.name,
+                                    f"transient provider failure; retry "
+                                    f"{transient_retries}/{MAX_TRANSIENT_RETRIES}",
+                                )
+                            )
+                            await asyncio.sleep(0)
+                            continue
+                        return self._result(
+                            request,
+                            runtime=runtime.name,
+                            status=AgentStatus.FAILED,
+                            error=self._safe_error(detail),
+                            probe=probe,
+                            context_hash=context_hash,
+                            events=tuple(collected_events),
+                        )
+                    if transcript.final_text is None:
+                        return self._result(
+                            request,
+                            runtime=runtime.name,
+                            status=AgentStatus.INVALID_OUTPUT,
+                            error="provider completed without a final response",
+                            probe=probe,
+                            context_hash=context_hash,
+                            events=tuple(collected_events),
+                        )
+                    structured_output: object | None = None
+                    if request.output_schema is not None:
+                        try:
+                            structured_output = parse_and_validate_structured_output(
+                                transcript.final_text,
+                                request.output_schema,
+                                max_bytes=request.policy.limits.max_output_bytes,
+                            )
+                        except AgentSchemaError:
+                            correction = _schema_correction_request(
+                                request,
+                                correction_attempted=correction_attempted,
+                            )
+                            if correction is None:
+                                raise
+                            correction_attempted = True
+                            execution_request = correction
+                            collected_events.append(
+                                _broker_event(
+                                    len(collected_events),
+                                    runtime.name,
+                                    "structured output rejected; requesting one correction",
+                                )
+                            )
+                            continue
+                    break
+                changes = mirror.collect_changes()
+                return AgentResult(
+                    request_id=request.request_id,
+                    project_id=request.project_id,
+                    runtime=runtime.name,
+                    status=AgentStatus.SUCCEEDED,
+                    context_hash=context_hash,
+                    events=tuple(collected_events),
+                    final_text=transcript.final_text,
+                    structured_output=structured_output,
+                    changes=changes,
+                    probe=probe,
+                )
+        except asyncio.CancelledError:
+            return self._result(
+                request,
+                runtime=runtime.name if runtime is not None else AgentRuntimeName.UNAVAILABLE,
+                status=AgentStatus.CANCELLED,
+                error="coding-agent execution was cancelled",
+                probe=probe,
+                context_hash=context_hash,
+            )
+        except AgentLimitError as error:
+            return self._result(
+                request,
+                runtime=runtime.name if runtime is not None else AgentRuntimeName.UNAVAILABLE,
+                status=AgentStatus.LIMIT_EXCEEDED,
+                error=self._safe_error(error),
+                probe=probe,
+                context_hash=context_hash,
+            )
+        except AgentSchemaError as error:
+            return self._result(
+                request,
+                runtime=runtime.name if runtime is not None else AgentRuntimeName.UNAVAILABLE,
+                status=AgentStatus.INVALID_OUTPUT,
+                error=self._safe_error(error),
+                probe=probe,
+                context_hash=context_hash,
+            )
+        except AgentPolicyError as error:
+            return self._result(
+                request,
+                runtime=runtime.name if runtime is not None else AgentRuntimeName.UNAVAILABLE,
+                status=AgentStatus.DENIED,
+                error=self._safe_error(error),
+                probe=probe,
+                context_hash=context_hash,
+            )
+        except AgentRuntimeError as error:
+            return self._result(
+                request,
+                runtime=runtime.name if runtime is not None else AgentRuntimeName.UNAVAILABLE,
+                status=AgentStatus.FAILED,
+                error=self._safe_error(error),
+                probe=probe,
+                context_hash=context_hash,
+            )
+        except OSError as error:
+            return self._result(
+                request,
+                runtime=runtime.name if runtime is not None else AgentRuntimeName.UNAVAILABLE,
+                status=AgentStatus.FAILED,
+                error=self._safe_error(error),
+                probe=probe,
+                context_hash=context_hash,
+            )
+
+    def _select_runtime(
+        self,
+        request: AgentRequest,
+    ) -> tuple[AgentRuntime, RuntimeProbe] | AgentResult:
+        found_available = False
+        found_missing_capability = False
+        found_consent_missing = False
+        first_available: tuple[AgentRuntime, RuntimeProbe] | None = None
+        for name in self._ordered_runtime_names(request):
+            runtime = self._runtimes.get(name)
+            if runtime is None:
+                continue
+            probe = self._safe_probe(runtime)
+            if not probe.available:
+                continue
+            found_available = True
+            if first_available is None:
+                first_available = (runtime, probe)
+            if not runtime.required_capabilities.issubset(request.policy.capabilities):
+                found_missing_capability = True
+                continue
+            if self._consent_store.authorized(
+                project_id=request.project_id,
+                project_root=request.project_root,
+                runtime=name,
+                policy=request.policy,
+            ):
+                return runtime, probe
+            found_consent_missing = True
+        if found_available:
+            runtime_name = (
+                first_available[0].name
+                if first_available is not None
+                else AgentRuntimeName.UNAVAILABLE
+            )
+            reason = (
+                NO_CONSENT_REASON
+                if found_consent_missing
+                else MISSING_CAPABILITY_REASON
+                if found_missing_capability
+                else NO_CONSENT_REASON
+            )
+            return self._result(
+                request,
+                runtime=runtime_name,
+                status=AgentStatus.DENIED,
+                error=reason,
+                probe=first_available[1] if first_available is not None else None,
+            )
+        return self._result(
+            request,
+            runtime=AgentRuntimeName.UNAVAILABLE,
+            status=AgentStatus.UNAVAILABLE,
+            error=NO_RUNTIME_REASON,
+        )
+
+    def _ordered_runtime_names(self, request: AgentRequest) -> tuple[AgentRuntimeName, ...]:
+        if request.runtime is not None:
+            return (request.runtime,)
+        preferred = self._consent_store.preference_for(request.project_id)
+        ordered = (*preferred, *request.policy.runtime_preference)
+        return tuple(dict.fromkeys(ordered))
+
+    def _safe_probe(self, runtime: AgentRuntime) -> RuntimeProbe:
+        try:
+            probe = runtime.probe(self._source_environment)
+            if probe.runtime is not runtime.name:
+                raise ValueError("runtime probe returned the wrong identity")
+        except Exception:  # A third-party adapter probe cannot break deterministic fallback.
+            return RuntimeProbe(
+                runtime=runtime.name,
+                available=False,
+                reason=f"{runtime.name.value} runtime probe failed",
+            )
+        return probe
+
+    @staticmethod
+    def _validate_probe_binding(
+        runtime: AgentRuntime,
+        probe: RuntimeProbe,
+        invoked_executable: str,
+    ) -> None:
+        if probe.executable is None:
+            raise AgentPolicyError("runtime invocation has no probed executable")
+        try:
+            executable = probe.executable.resolve(strict=True)
+        except OSError as error:
+            raise AgentPolicyError("runtime executable disappeared after probing") from error
+        if runtime.name is not probe.runtime or str(executable) != invoked_executable:
+            raise AgentPolicyError("runtime invocation does not match its executable probe")
+
+    @staticmethod
+    def _write_schema(request: AgentRequest, control_root: Path) -> Path | None:
+        if request.output_schema is None:
+            return None
+        schema_path = control_root / "output-schema.json"
+        descriptor = os.open(
+            schema_path,
+            os.O_WRONLY | os.O_CREAT | os.O_EXCL,
+            0o600,
+        )
+        try:
+            with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+                handle.write(canonical_schema_json(request.output_schema))
+                handle.write("\n")
+                handle.flush()
+                os.fsync(handle.fileno())
+        except Exception:
+            schema_path.unlink(missing_ok=True)
+            raise
+        return schema_path
+
+    def _safe_error(self, error: object) -> str:
+        return self._redactor.redact(str(error))[:1_000]
+
+    @staticmethod
+    def _result(
+        request: AgentRequest,
+        *,
+        runtime: AgentRuntimeName,
+        status: AgentStatus,
+        error: str,
+        probe: RuntimeProbe | None = None,
+        context_hash: str | None = None,
+        events: tuple[AgentEvent, ...] = (),
+    ) -> AgentResult:
+        return AgentResult(
+            request_id=request.request_id,
+            project_id=request.project_id,
+            runtime=runtime,
+            status=status,
+            context_hash=context_hash,
+            events=events,
+            error=error,
+            probe=probe,
+        )
+
+
+def _is_transient_failure(detail: str) -> bool:
+    normalized = detail.casefold()
+    return any(marker in normalized for marker in TRANSIENT_FAILURE_MARKERS)
+
+
+def _schema_correction_request(
+    request: AgentRequest,
+    *,
+    correction_attempted: bool,
+) -> AgentRequest | None:
+    if correction_attempted or request.policy.capabilities.intersection(
+        {
+            AgentCapability.WRITE_EPHEMERAL_MIRROR,
+            AgentCapability.CREATE_EPHEMERAL_FILES,
+        }
+    ):
+        return None
+    suffix = (
+        "\n\nYour previous response did not match the required output schema. "
+        "Return one corrected JSON value only; do not add prose or code fences."
+    )
+    prompt = request.prompt + suffix
+    if len(prompt.encode()) > request.policy.limits.max_prompt_bytes:
+        return None
+    return request.model_copy(update={"prompt": prompt})
+
+
+def _append_events(destination: list[AgentEvent], events: tuple[AgentEvent, ...]) -> None:
+    for event in events:
+        destination.append(event.model_copy(update={"sequence": len(destination)}))
+
+
+def _broker_event(sequence: int, runtime: AgentRuntimeName, message: str) -> AgentEvent:
+    return AgentEvent(
+        sequence=sequence,
+        kind=AgentEventKind.DIAGNOSTIC,
+        runtime=runtime,
+        provider_type="broker.retry",
+        message=message,
+        stream="broker",
+    )