Narrow top-level teaagent API to a stable core surface

- Strip teaagent/__init__.py __all__ from ~100 symbols to ~18 core
  runtime symbols (AgentRunner, RunBudget, ToolRegistry, etc.)
- Derive __version__ from importlib.metadata (dynamic from installed
  package) instead of a static string
- Update pyproject.toml description from "Minimal P0 agent harness"
  to "Governance-first agent harness for autonomous coding tasks"
- Add docs/migration-top-level-api.md with guidance for consumers
- Mark OpenTelemetry, OAuth 2.1/DPoP, MCP transport, and agentic
  RAG as implemented in p0-scope.md and p1-scope.md

Author: johnteee

AGENT.md

@@ -1,21 +1,6 @@
-# Role
-You are a highly analytical metacognitive agent. You do not just provide answers; you relentlessly evaluate your own reasoning.
+# Agent Prompt Note
 
-# Workflow Protocol
-For every task, you MUST output your response in the following strict format:
+`AGENT.md` is retained for compatibility with tools that look for this filename.
 
-<Prior_Hypothesis>
-State your immediate intuition or first-draft approach to the problem based on your current knowledge.
-</Prior_Hypothesis>
-
-<Evidence_Requirement>
-Identify what external data, factual verification, or tool execution (via MCP) is required to prove or disprove your hypothesis. What are the blind spots?
-</Evidence_Requirement>
-
-<Self_Critique>
-Assume your prior hypothesis is flawed. Play the devil's advocate. List at least two critical vulnerabilities or logical fallacies in your initial approach.
-</Self_Critique>
-
-<Posterior_Execution>
-Synthesize the critique and formulate a refined, robust, and finalized execution plan or answer.
-</Posterior_Execution>
+The canonical runtime instructions for this repository are defined in `AGENTS.md`.
+If both files are discovered by an external runner, prefer `AGENTS.md`.

CONTRIBUTING.md

@@ -7,6 +7,9 @@ model or reviewed skills.
 ## Setup
 
 ```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install --upgrade pip
 python3 -m pip install -e ".[dev,oauth,telemetry]"
 pre-commit install
 ```

README.md

@@ -32,6 +32,15 @@ See [docs/architecture.md](docs/architecture.md) for component details, data flo
 pip install -e .
 ```
 
+On macOS/Homebrew Python (PEP 668), prefer a virtual environment:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install --upgrade pip
+pip install -e ".[dev]"
+```
+
 Or without the console script:
 
 ```bash

docs/migration-top-level-api.md

@@ -0,0 +1,30 @@
+# Top-level API Migration Note
+
+This release narrows `teaagent` top-level exports (`teaagent.__all__`) to a stable core surface.
+
+## What changed
+
+- `from teaagent import *` now exports only core runtime symbols.
+- Advanced utilities and subsystem-specific symbols remain importable from their module paths.
+
+## Recommended migration
+
+- Replace star imports with explicit imports.
+- Import non-core symbols from submodules, for example:
+
+```python
+from teaagent.graph_rag import KnowledgeGraph
+from teaagent.oauth21 import OAuth21AuthorizationServer
+from teaagent.telemetry import TelemetryConfig
+```
+
+## Removed from `teaagent.__all__`
+
+- AIBOM/skill/eval: `AIBOMManifest`, `EvalCase`, `EvalReport`, `SkillReviewResult`, `build_aibom`, `review_skill`, `run_eval`
+- Retrieval and graph: `Document`, `GraphEdge`, `InMemoryRetriever`, `KnowledgeGraph`, `agentic_retrieve`, `graph_retrieve`
+- LLM internals: `LLMMessage`, `LLMRequest`, `LLMResponse`, `ProviderConfig`, `check_llm_configuration`, `create_llm_adapter`, `route_model`
+- OAuth/DPoP: `OAuth21AuthorizationServer`, `OAuth21ResourceServer`, `OAuthStore`, `SQLiteOAuthStore`, `create_jwt`, `verify_jwt`
+- Telemetry: `TelemetryConfig`, `OTelAuditSink`, `OTelMetricsSink`, `configure_telemetry`, `configure_metrics`
+- MCP/transport extras: `build_mcp_http_server`, `serve_mcp_http`, `serve_mcp_stdio`, `handle_mcp_request`, `handle_stateless_tool_request`
+
+This change only affects top-level export convenience. Module-level imports continue to work.

docs/p0-scope.md

@@ -11,12 +11,17 @@
 
 ## Deferred
 
-- Real MCP transport and OAuth 2.1 / DPoP.
 - External state store such as Postgres or Redis.
-- OpenTelemetry trace export.
-- Agentic RAG, A2A, and multi-agent orchestration.
+- A2A runtime and cross-agent registry/runtime orchestration.
 - LLM-as-Judge and offline eval automation.
 
+## Implemented Since P0 Baseline
+
+- MCP transport is available (stdio plus Streamable HTTP).
+- OAuth 2.1 / DPoP primitives are implemented for authorization/resource server flows.
+- OpenTelemetry integration is available through telemetry sinks.
+- Agentic RAG primitives are implemented (lexical + fusion path), with advanced retrieval still iterative.
+
 ## Pilot Assumption
 
 The first pilot should be a low-risk internal workflow with 3-5 tools. Destructive operations must be simulated or gated until HITL is fully integrated.

docs/p1-scope.md

@@ -11,11 +11,14 @@
 
 ## Still Deferred
 
-- Real OpenTelemetry exporter.
 - Real vector database, SQL MCP, or web search MCP integrations.
 - LLM-as-Judge scoring.
 - A2A runtime and AgentCard registry.
-- OAuth 2.1 / DPoP enforcement.
+
+## Implemented Since P1 Baseline
+
+- OpenTelemetry exporter path is implemented via telemetry sinks/configuration.
+- OAuth 2.1 / DPoP primitives and enforcement hooks are implemented for MCP HTTP deployment guardrails.
 
 ## Extension Points
 

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "teaagent"
 version = "0.1.0"
-description = "Minimal P0 agent harness with governance-first defaults."
+description = "Governance-first agent harness for autonomous coding tasks."
 readme = "README.md"
 requires-python = ">=3.9"
 license = {file = "LICENSE"}

teaagent/__init__.py

@@ -1,6 +1,11 @@
 """Governance-first agent harness."""
 
-__version__ = '0.1.0'
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version('teaagent')
+except PackageNotFoundError:
+    __version__ = '0+local'
 
 from teaagent.aibom import AIBOMManifest, build_aibom
 from teaagent.audit import AuditLogger
@@ -128,6 +133,7 @@
 )
 
 __all__ = [
+    '__version__',
     'AIBOMManifest',
     'AgentRunner',
     'ApprovalPolicy',
@@ -140,6 +146,7 @@
     'CodeModeSandbox',
     'ContainerCodeModeBackend',
     'ContextCompactor',
+    'DPoPValidationResult',
     'Decision',
     'Document',
     'EvalCase',
@@ -150,9 +157,17 @@
     'GraphQLiteGraphStore',
     'GraphQLiteRuntimeError',
     'GraphQLiteUnavailableError',
+    'HAS_CRYPTOGRAPHY',
+    'HAS_OTEL',
     'Heartbeat',
+    'InMemoryMetricsSink',
+    'InMemoryOAuthStore',
     'InMemoryRetriever',
     'IntentScore',
+    'InvalidClientError',
+    'InvalidDPoPError',
+    'InvalidGrantError',
+    'JWTError',
     'KnowledgeGraph',
     'LLMConfigurationError',
     'LLMHTTPError',
@@ -166,88 +181,79 @@
     'MetricSnapshot',
     'ModelConformanceReport',
     'ModelConformanceResult',
-    'ModelRoute',
     'ModelDecisionEngine',
+    'ModelRoute',
+    'OTelAuditSink',
+    'OTelMetricsSink',
+    'OAuth21AuthorizationServer',
+    'OAuth21Client',
+    'OAuth21ResourceServer',
+    'OAuth21TokenClaims',
+    'OAuth21TokenResponse',
+    'OAuthKeyRing',
+    'OAuthStore',
     'PermissionMode',
     'PortabilityResult',
     'PreflightReport',
     'PromptBundle',
-    'ProviderProfile',
     'ProviderConfig',
+    'ProviderProfile',
     'ReadinessReport',
     'RunBudget',
     'RunStore',
     'RunSummary',
+    'SQLiteOAuthStore',
     'SkillReviewResult',
     'StatelessMCPRequest',
     'StatelessMCPResponse',
+    'TelemetryConfig',
+    'TelemetryNotAvailable',
     'ToolAnnotations',
     'ToolRegistry',
     'ToolRequest',
     'TraceRecorder',
+    'TracingHTTPTransport',
     'UltraworkStore',
     'UnsafeCodeError',
     'WorkerRecord',
     'WorkspaceToolConfig',
-    'HAS_OTEL',
-    'InMemoryMetricsSink',
-    'OTelAuditSink',
-    'OTelMetricsSink',
-    'TelemetryConfig',
-    'TelemetryNotAvailable',
-    'TracingHTTPTransport',
-    'configure_metrics',
-    'configure_telemetry',
     'agentic_retrieve',
+    'assemble_agent_prompt',
     'assess_managed_agent_readiness',
     'assess_provider_portability',
     'available_providers',
-    'assemble_agent_prompt',
     'build_aibom',
     'build_mcp_http_server',
     'build_task_spec',
-    'HAS_CRYPTOGRAPHY',
-    'DPoPValidationResult',
-    'InMemoryOAuthStore',
-    'InvalidClientError',
-    'InvalidDPoPError',
-    'InvalidGrantError',
-    'JWTError',
-    'OAuth21AuthorizationServer',
-    'OAuth21Client',
-    'OAuth21ResourceServer',
-    'OAuth21TokenClaims',
-    'OAuth21TokenResponse',
-    'OAuthKeyRing',
-    'OAuthStore',
-    'SQLiteOAuthStore',
-    'compute_jwk_thumbprint',
-    'compute_s256_challenge',
-    'create_jwt',
-    'decode_jwt_unsafe',
-    'generate_code_verifier',
-    'verify_jwt',
     'build_workspace_tool_registry',
     'check_graphqlite_runtime',
     'check_llm_configuration',
     'clarify_task',
     'classify_task',
+    'compute_jwk_thumbprint',
+    'compute_s256_challenge',
+    'configure_metrics',
+    'configure_telemetry',
+    'create_jwt',
     'create_llm_adapter',
-    'execute_code_mode',
+    'decode_jwt_unsafe',
     'ensure_sqlite_extension_loading',
+    'execute_code_mode',
+    'generate_code_verifier',
     'graph_retrieve',
     'handle_mcp_request',
     'handle_stateless_tool_request',
     'parse_model_decision',
     'parse_permission_mode',
     'preflight',
-    'review_skill',
-    'route_model',
     'register_subagent_tool',
     'register_workspace_tools',
-    'serve_mcp_http',
-    'serve_mcp_stdio',
+    'review_skill',
+    'route_model',
     'run_chat_agent',
     'run_eval',
     'run_model_conformance',
+    'serve_mcp_http',
+    'serve_mcp_stdio',
+    'verify_jwt',
 ]