Merge pull request 'feat: define common.proto shared types (#8)' (#101) from feature/issue-8-common-proto into main

feat: define common.proto shared types (#8)

implementation-plans/_index.md

@@ -5,6 +5,7 @@
 | Issue | Title | Milestone | Status | Language | Plan |
 |---|---|---|---|---|---|
 | #7 | Set up proto project structure and build tooling | Phase 1 | `COMPLETED` | Protobuf | [issue-007.md](issue-007.md) |
+| #8 | Define common.proto (shared types) | Phase 1 | `COMPLETED` | Protobuf | [issue-008.md](issue-008.md) |
 
 ## Status Legend
 
@@ -39,6 +40,7 @@ _(Plans affecting the orchestrator)_
 
 ### Proto Definitions
 - [issue-007.md](issue-007.md) — Proto project structure and build tooling
+- [issue-008.md](issue-008.md) — Common proto shared types (SessionContext, AgentLineage, AgentType)
 
 ### Infrastructure / DevOps
 _(Plans affecting Docker, deployment, CI/CD)_

implementation-plans/issue-008.md

@@ -0,0 +1,113 @@
+# Implementation Plan — Issue #8: Define common.proto (shared types)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Issue | [#8](https://git.shahondin1624.de/llm-multiverse/llm-multiverse/issues/8) |
+| Title | Define common.proto (shared types: SessionContext, agent_lineage) |
+| Milestone | Phase 1: Proto Definitions |
+| Labels | `type:feature`, `priority:critical`, `lang:protobuf`, `cat:cross-cutting` |
+| Status | `COMPLETED` |
+| Language | Protobuf |
+| Related Plans | [issue-007.md](issue-007.md) |
+| Blocked by | #7 (completed) |
+
+## Acceptance Criteria
+
+- [ ] `common.proto` defines `SessionContext` with session_id, user_id, agent_lineage
+- [ ] `AgentLineage` message with ordered list of agent identifiers
+- [ ] `AgentType` enum (orchestrator, researcher, coder, sysadmin, assistant)
+- [ ] Common error/status types
+- [ ] Proto compiles without errors
+
+## Architecture Analysis
+
+### Context
+
+`common.proto` is the foundational proto file. Every other service proto (#9–#15) will import it. The types defined here enforce the architecture's core invariants:
+
+1. **Every RPC request** must carry a `SessionContext` for audit trail and broker enforcement
+2. **AgentLineage** is the chain used by the Tool Broker to enforce lineage constraint inheritance (non-negotiable rule: spawned agents cannot exceed parent's tool set)
+3. **AgentType** maps to tool manifests — each type has a fixed set of allowed tools
+4. **OverrideLevel** controls per-session/per-message broker bypass
+
+### Key Architecture Constraints (from planning-agent-prompt.md)
+
+- **Agent types and their tool permissions:**
+  - `ORCHESTRATOR`: memory_read, memory_write
+  - `ASSISTANT`: web_search, memory_read, memory_write
+  - `RESEARCHER`: web_search, memory_read, memory_write, fs_read
+  - `CODER`: fs_read, fs_write, run_code, memory_read, memory_write, web_search
+  - `SYSADMIN`: fs_read, fs_write, run_shell, package_install, memory_read
+
+- **Override levels:**
+  - `NONE`: full manifest + broker enforcement (default)
+  - `RELAX`: high-risk tools unlocked, lineage still enforced
+  - `ALL`: broker passes everything through
+
+- **Max spawn depth:** 4 levels
+
+- **Subagent return schema fields:** status, summary, artifacts, result_quality, source, new_memory_candidates, failure_reason
+
+### Dependencies
+
+- `buf` CLI for lint/build validation (already configured in #7)
+- No external proto imports needed (google.protobuf.Timestamp will be used for timestamps)
+
+## Implementation Steps
+
+### 1. Types & Configuration
+
+Define the following in `proto/llm_multiverse/v1/common.proto`:
+
+**Enums:**
+- `AgentType` — AGENT_TYPE_UNSPECIFIED, ORCHESTRATOR, RESEARCHER, CODER, SYSADMIN, ASSISTANT
+- `ToolType` — TOOL_TYPE_UNSPECIFIED, MEMORY_READ, MEMORY_WRITE, WEB_SEARCH, FS_READ, FS_WRITE, RUN_CODE, RUN_SHELL, PACKAGE_INSTALL
+- `OverrideLevel` — OVERRIDE_LEVEL_UNSPECIFIED, OVERRIDE_LEVEL_NONE, OVERRIDE_LEVEL_RELAX, OVERRIDE_LEVEL_ALL
+- `ResultStatus` — RESULT_STATUS_UNSPECIFIED, SUCCESS, PARTIAL, FAILED
+- `ResultQuality` — RESULT_QUALITY_UNSPECIFIED, VERIFIED, INFERRED, UNCERTAIN
+- `ResultSource` — RESULT_SOURCE_UNSPECIFIED, TOOL_OUTPUT, MODEL_KNOWLEDGE, WEB
+
+**Messages:**
+- `AgentIdentifier` — agent_id (string), agent_type (AgentType), spawn_depth (uint32)
+- `AgentLineage` — repeated AgentIdentifier agents (ordered, index 0 = orchestrator)
+- `SessionContext` — session_id (string), user_id (string), agent_lineage (AgentLineage), override_level (OverrideLevel), created_at (google.protobuf.Timestamp)
+- `ErrorDetail` — code (string), message (string), metadata (map<string, string>)
+- `SubagentResult` — status (ResultStatus), summary (string), repeated string artifacts, result_quality (ResultQuality), source (ResultSource), repeated MemoryCandidate new_memory_candidates, optional string failure_reason
+- `MemoryCandidate` — content (string), source (ResultSource), confidence (float)
+
+### 2. Proto Naming Conventions
+
+Follow buf STANDARD lint rules:
+- Enum values must be prefixed with enum name in UPPER_SNAKE_CASE (e.g., `AGENT_TYPE_ORCHESTRATOR`)
+- First enum value must be zero/UNSPECIFIED
+- Field names in lower_snake_case
+- Message names in PascalCase
+
+### 3. Validation
+
+Run `buf lint` and `buf build` to verify:
+- All lint rules pass
+- Proto compiles without errors
+- Package naming is correct
+
+## Files to Create/Modify
+
+| File | Action | Purpose |
+|---|---|---|
+| `proto/llm_multiverse/v1/common.proto` | Modify | Define all shared types |
+
+## Risks and Edge Cases
+
+- **Enum value naming:** buf STANDARD requires enum values prefixed with the enum name. Must use `AGENT_TYPE_ORCHESTRATOR` not just `ORCHESTRATOR`
+- **Forward compatibility:** Adding fields later is safe (proto3), but removing/renaming enum values is a breaking change. Design enum values carefully
+- **google.protobuf.Timestamp import:** Requires `google/protobuf/timestamp.proto` which is a well-known type — buf handles this automatically
+- **SubagentResult scope:** This type is referenced in the orchestrator.proto plan but is a shared type. Defining it here avoids circular imports
+
+## Deviation Log
+
+_(Filled during implementation if deviations from plan occur)_
+
+| Deviation | Reason |
+|---|---|

proto/llm_multiverse/v1/common.proto

@@ -2,5 +2,114 @@ syntax = "proto3";
 
 package llm_multiverse.v1;
 
-// Shared types used across all services.
-// Full definitions added in issue #8.
+import "google/protobuf/timestamp.proto";
+
+// --- Enums ---
+
+// Agent types with distinct tool permission manifests.
+enum AgentType {
+  AGENT_TYPE_UNSPECIFIED = 0;
+  AGENT_TYPE_ORCHESTRATOR = 1;
+  AGENT_TYPE_RESEARCHER = 2;
+  AGENT_TYPE_CODER = 3;
+  AGENT_TYPE_SYSADMIN = 4;
+  AGENT_TYPE_ASSISTANT = 5;
+}
+
+// Tool categories enforced by the Tool Broker.
+enum ToolType {
+  TOOL_TYPE_UNSPECIFIED = 0;
+  TOOL_TYPE_MEMORY_READ = 1;
+  TOOL_TYPE_MEMORY_WRITE = 2;
+  TOOL_TYPE_WEB_SEARCH = 3;
+  TOOL_TYPE_FS_READ = 4;
+  TOOL_TYPE_FS_WRITE = 5;
+  TOOL_TYPE_RUN_CODE = 6;
+  TOOL_TYPE_RUN_SHELL = 7;
+  TOOL_TYPE_PACKAGE_INSTALL = 8;
+}
+
+// Session-level override for broker enforcement.
+enum OverrideLevel {
+  OVERRIDE_LEVEL_UNSPECIFIED = 0;
+  // Full manifest + broker enforcement (default).
+  OVERRIDE_LEVEL_NONE = 1;
+  // High-risk tools unlocked, lineage still enforced.
+  OVERRIDE_LEVEL_RELAX = 2;
+  // Broker passes everything through.
+  OVERRIDE_LEVEL_ALL = 3;
+}
+
+// Status of a subagent's result.
+enum ResultStatus {
+  RESULT_STATUS_UNSPECIFIED = 0;
+  RESULT_STATUS_SUCCESS = 1;
+  RESULT_STATUS_PARTIAL = 2;
+  RESULT_STATUS_FAILED = 3;
+}
+
+// Confidence level of a result.
+enum ResultQuality {
+  RESULT_QUALITY_UNSPECIFIED = 0;
+  RESULT_QUALITY_VERIFIED = 1;
+  RESULT_QUALITY_INFERRED = 2;
+  RESULT_QUALITY_UNCERTAIN = 3;
+}
+
+// Provenance of a result.
+enum ResultSource {
+  RESULT_SOURCE_UNSPECIFIED = 0;
+  RESULT_SOURCE_TOOL_OUTPUT = 1;
+  RESULT_SOURCE_MODEL_KNOWLEDGE = 2;
+  RESULT_SOURCE_WEB = 3;
+}
+
+// --- Messages ---
+
+// Identifies a single agent in the lineage chain.
+message AgentIdentifier {
+  string agent_id = 1;
+  AgentType agent_type = 2;
+  uint32 spawn_depth = 3;
+}
+
+// Ordered chain of agents from orchestrator (index 0) to current agent.
+// Used by the Tool Broker for lineage constraint enforcement.
+message AgentLineage {
+  repeated AgentIdentifier agents = 1;
+}
+
+// Carried in every gRPC request for audit trail and broker enforcement.
+message SessionContext {
+  string session_id = 1;
+  string user_id = 2;
+  AgentLineage agent_lineage = 3;
+  OverrideLevel override_level = 4;
+  google.protobuf.Timestamp created_at = 5;
+}
+
+// Structured error detail for gRPC error responses.
+message ErrorDetail {
+  string code = 1;
+  string message = 2;
+  map<string, string> metadata = 3;
+}
+
+// A candidate memory entry proposed by a subagent for persistence.
+message MemoryCandidate {
+  string content = 1;
+  ResultSource source = 2;
+  float confidence = 3;
+}
+
+// Standardized return value from any subagent to its parent.
+message SubagentResult {
+  ResultStatus status = 1;
+  // 3-sentence max summary of work performed.
+  string summary = 2;
+  repeated string artifacts = 3;
+  ResultQuality result_quality = 4;
+  ResultSource source = 5;
+  repeated MemoryCandidate new_memory_candidates = 6;
+  optional string failure_reason = 7;
+}