Merge feat/phase1-core: Phase 1 COMPLETE (15/15 tasks)

All 15 tasks implemented with TDD:

1. Project scaffolding (pyproject.toml, CI, structure)
2. Shared kernel (types, DomainEvent, EventBus)
3. Domain enums (SessionState, GraphTemplate, EmbeddingTaskType)
4. Value objects (AgentMessage, ModelConfig, ToolResult, MultimodalContent)
5. Domain entities (Session state machine, Persona, Skill, Roadmap)
6. Domain events (8 event types)
7. Domain services (EscalationService, ModelResolver, RoutingService, EvalScoring)
8. Application ports (12 ABCs: hexagonal boundaries)
9. Command/Query handlers (HandleMessage, CreateSession, ResumeHITL, GetSession, ListPersonas)
10. Middleware chain + TracingMiddleware (no-op fallback)
11. Configuration (AgenticSettings, sidecar mode, MCP, Observability, Embedding)
12. gRPC proto + codegen (6 RPCs, streaming)
13. WebSocket adapter (full protocol, heartbeat, errors, session lifecycle)
14. gRPC adapter (AgentService servicer, all RPCs)
15. AgentRuntime composition root (wires everything, starts both transports)

105 tests passing. 81% coverage. Python 3.12+.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: lapc506

Makefile

@@ -0,0 +1,18 @@
+.PHONY: proto test lint typecheck
+
+proto:
+	python -m grpc_tools.protoc \
+		-I proto \
+		--python_out=src/agentic_core/adapters/primary/grpc/generated \
+		--grpc_python_out=src/agentic_core/adapters/primary/grpc/generated \
+		--pyi_out=src/agentic_core/adapters/primary/grpc/generated \
+		proto/agentic_core.proto
+
+test:
+	pytest --cov=agentic_core --cov-report=term-missing -v
+
+lint:
+	ruff check src/ tests/
+
+typecheck:
+	mypy src/agentic_core/

proto/agentic_core.proto

@@ -0,0 +1,96 @@
+syntax = "proto3";
+
+package agentic_core;
+
+service AgentService {
+  rpc SendMessage(AgentRequest) returns (stream AgentResponse);
+  rpc CreateSession(CreateSessionRequest) returns (SessionInfo);
+  rpc GetSession(GetSessionRequest) returns (SessionInfo);
+  rpc ResumeHITL(HumanResponse) returns (stream AgentResponse);
+  rpc ListPersonas(Empty) returns (PersonaList);
+  rpc HealthCheck(Empty) returns (HealthStatus);
+}
+
+message Empty {}
+
+message AgentRequest {
+  string session_id = 1;
+  string persona_id = 2;
+  string content = 3;
+  string user_id = 4;
+  string trace_id = 5;
+}
+
+message CreateSessionRequest {
+  string persona_id = 1;
+  string user_id = 2;
+}
+
+message GetSessionRequest {
+  string session_id = 1;
+}
+
+message HumanResponse {
+  string session_id = 1;
+  string content = 2;
+}
+
+message SessionInfo {
+  string session_id = 1;
+  string persona_id = 2;
+  string user_id = 3;
+  string state = 4;
+  string created_at = 5;
+}
+
+message PersonaList {
+  repeated PersonaInfo personas = 1;
+}
+
+message PersonaInfo {
+  string name = 1;
+  string role = 2;
+  string description = 3;
+  string graph_template = 4;
+}
+
+message HealthStatus {
+  bool healthy = 1;
+  string version = 2;
+  int32 active_sessions = 3;
+}
+
+message AgentResponse {
+  oneof payload {
+    StreamToken token = 1;
+    StreamEnd end = 2;
+    HumanEscalation escalation = 3;
+    AudioChunk audio = 4;
+    ErrorDetail error = 5;
+  }
+}
+
+message StreamToken {
+  string session_id = 1;
+  string token = 2;
+}
+
+message StreamEnd {
+  string session_id = 1;
+}
+
+message HumanEscalation {
+  string session_id = 1;
+  string prompt = 2;
+}
+
+message AudioChunk {
+  string session_id = 1;
+  bytes data = 2;
+}
+
+message ErrorDetail {
+  string session_id = 1;
+  string code = 2;
+  string message = 3;
+}

src/agentic_core/adapters/primary/grpc/generated/agentic_core_pb2.py

@@ -0,0 +1,143 @@
+from google.protobuf.internal import containers as _containers
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from collections.abc import Iterable as _Iterable, Mapping as _Mapping
+from typing import ClassVar as _ClassVar, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class Empty(_message.Message):
+    __slots__ = ()
+    def __init__(self) -> None: ...
+
+class AgentRequest(_message.Message):
+    __slots__ = ("session_id", "persona_id", "content", "user_id", "trace_id")
+    SESSION_ID_FIELD_NUMBER: _ClassVar[int]
+    PERSONA_ID_FIELD_NUMBER: _ClassVar[int]
+    CONTENT_FIELD_NUMBER: _ClassVar[int]
+    USER_ID_FIELD_NUMBER: _ClassVar[int]
+    TRACE_ID_FIELD_NUMBER: _ClassVar[int]
+    session_id: str
+    persona_id: str
+    content: str
+    user_id: str
+    trace_id: str
+    def __init__(self, session_id: _Optional[str] = ..., persona_id: _Optional[str] = ..., content: _Optional[str] = ..., user_id: _Optional[str] = ..., trace_id: _Optional[str] = ...) -> None: ...
+
+class CreateSessionRequest(_message.Message):
+    __slots__ = ("persona_id", "user_id")
+    PERSONA_ID_FIELD_NUMBER: _ClassVar[int]
+    USER_ID_FIELD_NUMBER: _ClassVar[int]
+    persona_id: str
+    user_id: str
+    def __init__(self, persona_id: _Optional[str] = ..., user_id: _Optional[str] = ...) -> None: ...
+
+class GetSessionRequest(_message.Message):
+    __slots__ = ("session_id",)
+    SESSION_ID_FIELD_NUMBER: _ClassVar[int]
+    session_id: str
+    def __init__(self, session_id: _Optional[str] = ...) -> None: ...
+
+class HumanResponse(_message.Message):
+    __slots__ = ("session_id", "content")
+    SESSION_ID_FIELD_NUMBER: _ClassVar[int]
+    CONTENT_FIELD_NUMBER: _ClassVar[int]
+    session_id: str
+    content: str
+    def __init__(self, session_id: _Optional[str] = ..., content: _Optional[str] = ...) -> None: ...
+
+class SessionInfo(_message.Message):
+    __slots__ = ("session_id", "persona_id", "user_id", "state", "created_at")
+    SESSION_ID_FIELD_NUMBER: _ClassVar[int]
+    PERSONA_ID_FIELD_NUMBER: _ClassVar[int]
+    USER_ID_FIELD_NUMBER: _ClassVar[int]
+    STATE_FIELD_NUMBER: _ClassVar[int]
+    CREATED_AT_FIELD_NUMBER: _ClassVar[int]
+    session_id: str
+    persona_id: str
+    user_id: str
+    state: str
+    created_at: str
+    def __init__(self, session_id: _Optional[str] = ..., persona_id: _Optional[str] = ..., user_id: _Optional[str] = ..., state: _Optional[str] = ..., created_at: _Optional[str] = ...) -> None: ...
+
+class PersonaList(_message.Message):
+    __slots__ = ("personas",)
+    PERSONAS_FIELD_NUMBER: _ClassVar[int]
+    personas: _containers.RepeatedCompositeFieldContainer[PersonaInfo]
+    def __init__(self, personas: _Optional[_Iterable[_Union[PersonaInfo, _Mapping]]] = ...) -> None: ...
+
+class PersonaInfo(_message.Message):
+    __slots__ = ("name", "role", "description", "graph_template")
+    NAME_FIELD_NUMBER: _ClassVar[int]
+    ROLE_FIELD_NUMBER: _ClassVar[int]
+    DESCRIPTION_FIELD_NUMBER: _ClassVar[int]
+    GRAPH_TEMPLATE_FIELD_NUMBER: _ClassVar[int]
+    name: str
+    role: str
+    description: str
+    graph_template: str
+    def __init__(self, name: _Optional[str] = ..., role: _Optional[str] = ..., description: _Optional[str] = ..., graph_template: _Optional[str] = ...) -> None: ...
+
+class HealthStatus(_message.Message):
+    __slots__ = ("healthy", "version", "active_sessions")
+    HEALTHY_FIELD_NUMBER: _ClassVar[int]
+    VERSION_FIELD_NUMBER: _ClassVar[int]
+    ACTIVE_SESSIONS_FIELD_NUMBER: _ClassVar[int]
+    healthy: bool
+    version: str
+    active_sessions: int
+    def __init__(self, healthy: bool = ..., version: _Optional[str] = ..., active_sessions: _Optional[int] = ...) -> None: ...
+
+class AgentResponse(_message.Message):
+    __slots__ = ("token", "end", "escalation", "audio", "error")
+    TOKEN_FIELD_NUMBER: _ClassVar[int]
+    END_FIELD_NUMBER: _ClassVar[int]
+    ESCALATION_FIELD_NUMBER: _ClassVar[int]
+    AUDIO_FIELD_NUMBER: _ClassVar[int]
+    ERROR_FIELD_NUMBER: _ClassVar[int]
+    token: StreamToken
+    end: StreamEnd
+    escalation: HumanEscalation
+    audio: AudioChunk
+    error: ErrorDetail
+    def __init__(self, token: _Optional[_Union[StreamToken, _Mapping]] = ..., end: _Optional[_Union[StreamEnd, _Mapping]] = ..., escalation: _Optional[_Union[HumanEscalation, _Mapping]] = ..., audio: _Optional[_Union[AudioChunk, _Mapping]] = ..., error: _Optional[_Union[ErrorDetail, _Mapping]] = ...) -> None: ...
+
+class StreamToken(_message.Message):
+    __slots__ = ("session_id", "token")
+    SESSION_ID_FIELD_NUMBER: _ClassVar[int]
+    TOKEN_FIELD_NUMBER: _ClassVar[int]
+    session_id: str
+    token: str
+    def __init__(self, session_id: _Optional[str] = ..., token: _Optional[str] = ...) -> None: ...
+
+class StreamEnd(_message.Message):
+    __slots__ = ("session_id",)
+    SESSION_ID_FIELD_NUMBER: _ClassVar[int]
+    session_id: str
+    def __init__(self, session_id: _Optional[str] = ...) -> None: ...
+
+class HumanEscalation(_message.Message):
+    __slots__ = ("session_id", "prompt")
+    SESSION_ID_FIELD_NUMBER: _ClassVar[int]
+    PROMPT_FIELD_NUMBER: _ClassVar[int]
+    session_id: str
+    prompt: str
+    def __init__(self, session_id: _Optional[str] = ..., prompt: _Optional[str] = ...) -> None: ...
+
+class AudioChunk(_message.Message):
+    __slots__ = ("session_id", "data")
+    SESSION_ID_FIELD_NUMBER: _ClassVar[int]
+    DATA_FIELD_NUMBER: _ClassVar[int]
+    session_id: str
+    data: bytes
+    def __init__(self, session_id: _Optional[str] = ..., data: _Optional[bytes] = ...) -> None: ...
+
+class ErrorDetail(_message.Message):
+    __slots__ = ("session_id", "code", "message")
+    SESSION_ID_FIELD_NUMBER: _ClassVar[int]
+    CODE_FIELD_NUMBER: _ClassVar[int]
+    MESSAGE_FIELD_NUMBER: _ClassVar[int]
+    session_id: str
+    code: str
+    message: str
+    def __init__(self, session_id: _Optional[str] = ..., code: _Optional[str] = ..., message: _Optional[str] = ...) -> None: ...