Coverage for src/governed_harness/agents/base.py: 100%
22 statements
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
1from __future__ import annotations
3from dataclasses import dataclass
4from typing import TYPE_CHECKING, Any, Protocol
6from governed_harness.agents.requests import CallKind
7from governed_harness.domain.enums import PhaseId, ResultStatus
8from governed_harness.domain.models import (
9 AgentInvocation,
10 Plan,
11 ResourceUsage,
12 Task,
13 ToolInvocation,
14)
16if TYPE_CHECKING:
17 from governed_harness.domain.models import CapabilityGrant, Provenance
18 from governed_harness.evidence.artifact_store import LocalArtifactStore
19 from governed_harness.runtime.cancellation import CancellationToken
20 from governed_harness.runtime.patches import PatchApplier
21 from governed_harness.runtime.process_runner import SafeProcessRunner
24@dataclass(frozen=True)
25class AgentExecutionResult:
26 status: ResultStatus
27 summary: str
28 invocation: AgentInvocation
29 tool_invocations: tuple[ToolInvocation, ...] = ()
30 output_ref: str | None = None
31 usage: ResourceUsage | None = None
32 self_report: Any = None
33 """The raw self-report the agent gave (``provenance.selfReport``), read by the engine."""
34 request_bytes: int | None = None
35 """Size of the request the invocation's prompt digest covers (JSON with sorted keys, UTF-8
36 bytes): what the agent contract records as the bytes sent. ``None``: not reported."""
39class AgentContext(Protocol):
40 """Read-only execution context the engine hands to every agent provider."""
42 @property
43 def execution_id(self) -> str:
44 """The identifier of the execution the agent works for."""
46 @property
47 def workspace(self) -> Any:
48 """The workspace the agent works in."""
50 @property
51 def grants(self) -> list[CapabilityGrant]:
52 """The capability grants the agent holds for this execution."""
54 @property
55 def artifact_store(self) -> LocalArtifactStore:
56 """The store where the agent records its artifacts."""
58 @property
59 def process_runner(self) -> SafeProcessRunner:
60 """The runner that executes the commands the agent is allowed to launch."""
62 @property
63 def patch_applier(self) -> PatchApplier:
64 """The applier that writes the changes of the agent into the workspace."""
66 @property
67 def provenance(self) -> Provenance:
68 """The provenance recorded for everything the agent produces."""
70 @property
71 def timeout_seconds(self) -> int:
72 """The time limit of the call, in seconds."""
74 @property
75 def max_output_bytes(self) -> int:
76 """The largest output the call may produce, in bytes."""
78 @property
79 def cancellation(self) -> CancellationToken:
80 """The token that tells the agent the call was cancelled."""
82 @property
83 def context_manifest_ref(self) -> str | None:
84 """The reference of the context manifest of the call, or ``None``."""
86 @property
87 def memory_context(self) -> dict[str, Any] | None:
88 """The project memory the call may read, or ``None``."""
90 @property
91 def feedback(self) -> dict[str, Any] | None:
92 """The feedback of the previous attempt, or ``None`` on the first one."""
94 @property
95 def request_extra(self) -> dict[str, Any] | None:
96 """Keys the agent-results settings add to the request (gate contract, permissions,
97 context manifest, lessons, budget, routing); ``None`` keeps the 1.0 request."""
100@dataclass(frozen=True)
101class AgentCallResult:
102 """The outcome of a ``clarify``, ``review`` or ``plan`` call: the 1.0 result fields and
103 the structured ``result`` object of the response (``None`` when the call did not pass or
104 the response carried none)."""
106 execution: AgentExecutionResult
107 response: dict[str, Any] | None = None
110class AgentProvider(Protocol):
111 provider_id: str
113 def capabilities(self) -> tuple[str, ...]:
114 """The capabilities the provider declares."""
116 def implement(self, task: Task, plan: Plan, context: AgentContext) -> AgentExecutionResult:
117 """Implement the plan of the task in the workspace and return the outcome."""
119 def call(
120 self,
121 kind: CallKind,
122 request: dict[str, Any],
123 context: AgentContext,
124 *,
125 phase_id: PhaseId,
126 ) -> AgentCallResult:
127 """Make a ``clarify``, ``review`` or ``plan`` call and return its outcome."""