Coverage for src/governed_harness/agents/session.py: 94%

32 statements  

« prev     ^ index     » next       coverage.py v7.17.2, created at 2026-11-12 16:06 +0000

1"""The ``session`` provider: the agent session that drives the harness implements (#56). 

2 

3In embedded mode an agent (Claude Code, Codex) drives the flow from its own session through the 

4harness's MCP server or skill. The harness must not start a second agent to implement the task: 

5the session itself edits the workspace. ``run start --provider session`` therefore runs INTENT 

6to PLANNING and then waits in IMPLEMENTATION (``BLOCKED``) until the workspace differs from the 

7baseline DISCOVERY recorded; ``run continue`` after the session's edits records them as the 

8candidate ChangeSet, attributed to ``agent.session``, and VERIFICATION, the review, the gate and 

9the human decision run as for any provider. Read-only calls (clarify, review, plan, acceptance, 

10architecture) go to the project's ``agentProvider`` (or their own configured provider), never 

11to the session, so the reviewer is not the author.""" 

12 

13from __future__ import annotations 

14 

15from collections.abc import Callable 

16from datetime import UTC, datetime 

17from typing import Any 

18 

19from governed_harness.agents.base import AgentCallResult, AgentContext, AgentExecutionResult 

20from governed_harness.agents.requests import CallKind 

21from governed_harness.domain.enums import ActorType, PhaseId, ResultStatus 

22from governed_harness.domain.ids import new_id 

23from governed_harness.domain.models import Actor, AgentInvocation, Plan, Task 

24from governed_harness.evidence.hashing import sha256_json 

25 

26SESSION_PROVIDER = "session" 

27 

28 

29class SessionAgentProvider: 

30 provider_id = SESSION_PROVIDER 

31 

32 def __init__(self, changed_paths: Callable[[], list[str]]) -> None: 

33 self._changed_paths = changed_paths 

34 

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

36 return ("embedded", "session") 

37 

38 def implement( 

39 self, 

40 task: Task, 

41 plan: Plan, # NOSONAR(S1172) AgentProvider.implement signature 

42 context: AgentContext, 

43 ) -> AgentExecutionResult: 

44 actor = Actor(actor_type=ActorType.AGENT, actor_id="agent.session", version="1") 

45 started = datetime.now(UTC) 

46 changed = self._changed_paths() 

47 if changed: 

48 status = ResultStatus.PASSED 

49 summary = f"The agent session changed {len(changed)} file(s) of the ChangeSet scope" 

50 else: 

51 status = ResultStatus.BLOCKED 

52 summary = ( 

53 "Waiting for the agent session to implement the task: edit the workspace, then " 

54 "run harness run continue (MCP tool harness_run_continue)" 

55 ) 

56 output_ref = context.artifact_store.put_json( 

57 {"provider": SESSION_PROVIDER, "changedPaths": changed[:200], "status": status.value}, 

58 metadata={"kind": "agent-output", "provider": SESSION_PROVIDER}, 

59 ) 

60 invocation = AgentInvocation( 

61 invocation_id=new_id("agentinv"), 

62 execution_id=context.execution_id, 

63 phase_id=PhaseId.IMPLEMENTATION, 

64 actor=actor, 

65 provider=SESSION_PROVIDER, 

66 model=None, 

67 started_at=started, 

68 finished_at=datetime.now(UTC), 

69 status=status, 

70 prompt_digest=sha256_json({"task": task.model_dump(mode="json"), "session": True}), 

71 context_manifest_ref=context.context_manifest_ref, 

72 output_ref=output_ref.uri, 

73 ) 

74 return AgentExecutionResult(status, summary, invocation, (), output_ref.uri) 

75 

76 def call( 

77 self, 

78 kind: CallKind, 

79 request: dict[str, Any], 

80 context: AgentContext, 

81 *, 

82 phase_id: PhaseId, 

83 ) -> AgentCallResult: 

84 raise RuntimeError( 

85 f"the session provider does not answer {kind} calls; they go to agentProvider" 

86 ) 

87 

88 

89__all__ = ["SESSION_PROVIDER", "SessionAgentProvider"]