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

1from __future__ import annotations 

2 

3from dataclasses import dataclass 

4from typing import TYPE_CHECKING, Any, Protocol 

5 

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) 

15 

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 

22 

23 

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.""" 

37 

38 

39class AgentContext(Protocol): 

40 """Read-only execution context the engine hands to every agent provider.""" 

41 

42 @property 

43 def execution_id(self) -> str: 

44 """The identifier of the execution the agent works for.""" 

45 

46 @property 

47 def workspace(self) -> Any: 

48 """The workspace the agent works in.""" 

49 

50 @property 

51 def grants(self) -> list[CapabilityGrant]: 

52 """The capability grants the agent holds for this execution.""" 

53 

54 @property 

55 def artifact_store(self) -> LocalArtifactStore: 

56 """The store where the agent records its artifacts.""" 

57 

58 @property 

59 def process_runner(self) -> SafeProcessRunner: 

60 """The runner that executes the commands the agent is allowed to launch.""" 

61 

62 @property 

63 def patch_applier(self) -> PatchApplier: 

64 """The applier that writes the changes of the agent into the workspace.""" 

65 

66 @property 

67 def provenance(self) -> Provenance: 

68 """The provenance recorded for everything the agent produces.""" 

69 

70 @property 

71 def timeout_seconds(self) -> int: 

72 """The time limit of the call, in seconds.""" 

73 

74 @property 

75 def max_output_bytes(self) -> int: 

76 """The largest output the call may produce, in bytes.""" 

77 

78 @property 

79 def cancellation(self) -> CancellationToken: 

80 """The token that tells the agent the call was cancelled.""" 

81 

82 @property 

83 def context_manifest_ref(self) -> str | None: 

84 """The reference of the context manifest of the call, or ``None``.""" 

85 

86 @property 

87 def memory_context(self) -> dict[str, Any] | None: 

88 """The project memory the call may read, or ``None``.""" 

89 

90 @property 

91 def feedback(self) -> dict[str, Any] | None: 

92 """The feedback of the previous attempt, or ``None`` on the first one.""" 

93 

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.""" 

98 

99 

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).""" 

105 

106 execution: AgentExecutionResult 

107 response: dict[str, Any] | None = None 

108 

109 

110class AgentProvider(Protocol): 

111 provider_id: str 

112 

113 def capabilities(self) -> tuple[str, ...]: 

114 """The capabilities the provider declares.""" 

115 

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.""" 

118 

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."""