llm-multiverse/implementation-plans/issue-008.md

Implementation Plan — Issue #8: Define common.proto (shared types)

Metadata

Field	Value
Issue	#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
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