|
| 1 | +# Project Nature, Origins, and Dormant Surfaces — Parallel-Lens Analysis |
| 2 | + |
| 3 | +> **Claim class:** Dated analysis (archive tier). Descriptive study of what TeaAgent |
| 4 | +> *is*, its origins, and its dormant/experimental/descoped surfaces. Not a capability |
| 5 | +> claim; not current-truth for roadmap/status (see `docs/roadmap-status.md`). |
| 6 | +> **Date:** 2026-07-01 · **Anchor:** `1306ca7` · branch `main` · version `0.1.0` |
| 7 | +> **Trigger:** Explicit owner request — "what kind of project is this, goals from |
| 8 | +> origins, leaked/dormant features, better ways to use, scenarios." |
| 9 | +> **Method:** Parallel-lens review packet + four adversarial read-only reviewers |
| 10 | +> (historian, capability-wiring, usage-scenario, evidence-skeptic). Every |
| 11 | +> load-bearing claim is tagged OBSERVED (a command was run / file read) or |
| 12 | +> INFERENCE. Corrections from the panel are folded in. |
| 13 | +> **Do not** treat descoped/dormant items below as shipped capability. |
| 14 | +
|
| 15 | +--- |
| 16 | + |
| 17 | +## Panel Consensus |
| 18 | + |
| 19 | +- **Decision:** AGREE WITH CHANGES (4/4 reviewers). The analysis is substantially |
| 20 | + correct; five corrections below are mandatory. |
| 21 | +- **Use-case recommendation:** `study` ✅ · `reproduce` ✅ (governance/audit claims |
| 22 | + are verifiable) · `adopt` ✅ *only* as a single-user, local, owner-operator harness · |
| 23 | + `deploy` ❌ as multi-user/hosted/team (explicitly descoped; WAN surfaces exist but |
| 24 | + need deliberate hardening). |
| 25 | +- **Framing correction (unanimous):** do **not** call these "leaked" features. No |
| 26 | + unintentional security exposure was found. Correct vocabulary: **dormant/unwired**, |
| 27 | + **experimental/Beta**, **shadow-mode**, **descoped**, or **documented-but-uncalled**. |
| 28 | + |
| 29 | +### Required wording changes (folded into this doc) |
| 30 | +1. "Leaked features" → "dormant / experimental / shadow / descoped surfaces" (EvidenceSkeptic). |
| 31 | +2. "Two phases: platform → harness" → "one governance-first harness with two |
| 32 | + *overlapping* tracks (governance + surface area) from commit 1; 2026-06-13 tightened |
| 33 | + persona and allowed claims — not a technical break" (HistorianAuditor). |
| 34 | +3. Provider count = **14** canonical; README is correct. The "15" was a dynamic |
| 35 | + `ProviderConfig()` reconstruction site, not a 15th provider (EvidenceSkeptic). |
| 36 | +4. Feature-status table corrections L1/L2/L6/L7/L8/L9/L10 (CapabilityWiringReviewer). |
| 37 | +5. Add "documented-but-uncalled functions" (D1–D6) and "invalid documented CLI/API |
| 38 | + surfaces" as first-class findings (EvidenceSkeptic, UsageScenarioReviewer). |
| 39 | + |
| 40 | +--- |
| 41 | + |
| 42 | +## 1. What kind of project is this? |
| 43 | + |
| 44 | +**TeaAgent is a governance-first, local-first, provider-agnostic harness for |
| 45 | +autonomous coding — scoped (as of 2026-06-13) to a single owner-operator who is |
| 46 | +simultaneously its maintainer, daily user, and audit reviewer.** `[OBSERVED` README.md:7, |
| 47 | +`docs/strategy/harness-first-direction-2026-06-13.md`] |
| 48 | + |
| 49 | +It is explicitly **not** a generic IDE-agent clone, an enterprise multi-user platform, |
| 50 | +or a hosted cloud delegate `[OBSERVED` README.md:9]. The distinguishing pillars are a |
| 51 | +5-level permission matrix, hash-chained append-only JSONL audit logs, bounded runs |
| 52 | +(iteration/tool/cost caps), human approval gates for destructive tools, and |
| 53 | +verify-don't-trust commands (`audit verify`, `doctor config-lint`, run receipts) |
| 54 | +`[OBSERVED` README.md:13-21]. |
| 55 | + |
| 56 | +A defining property: **its first "external users" are other agents editing the harness |
| 57 | +itself**, under `docs/agent-contribution-contract.md` (Status: Active V4-a) — deliberate |
| 58 | +dogfooding, not adoption chasing `[OBSERVED` harness-first §1; contract verified by UsageScenarioReviewer]. |
| 59 | + |
| 60 | +## 2. Goals from origins (git-substantiated) |
| 61 | + |
| 62 | +- **Commit 1** `3244321` (2026-05-08): *"Establish governance-first P0 agent harness."* |
| 63 | + Governance was the founding goal, not a later addition `[OBSERVED` git log --reverse]. |
| 64 | +- The first README (`b13ebbe`, 2026-05-09) already says "governance-first agent harness |
| 65 | + for autonomous coding tasks" `[OBSERVED` HistorianAuditor]. |
| 66 | +- Origin scope (`docs/p0-scope.md`): minimal runner, tool registry, approval gate, audit |
| 67 | + log — with MCP/A2A/multi-agent explicitly deferred, then landed within 48–72h `[OBSERVED` HistorianAuditor]. |
| 68 | +- Strategy docs consistently frame it as *"the harness is the platform, not the product"* |
| 69 | + (`malleable-governed-agent-harness-2026-06-03`, `teaagent-product-principles-2026-06-04`) `[OBSERVED` HistorianAuditor]. |
| 70 | + |
| 71 | +**Corrected arc (not two clean phases):** one harness with two *overlapping* tracks from |
| 72 | +day one — (a) governance/security hardening and (b) surface-area expansion — running in |
| 73 | +parallel throughout May–June `[OBSERVED` ~62 commits on 2026-05-08 alone mixing both; |
| 74 | +HistorianAuditor U1=confirmed]. What changed on **2026-06-13** (`ddd32f1`, |
| 75 | +`harness-first-direction-2026-06-13.md`) was the **positioning/persona and the |
| 76 | +docs-truth rule**: external adoption / enterprise / team / hosted were "descoped from |
| 77 | +current truth … may return later as goals, but no doc may state them as present-tense |
| 78 | +capability." That decision reframed the docs and persona; it did **not** rip out A2A, |
| 79 | +OAuth, the registry, or federation `[OBSERVED` HistorianAuditor]. |
| 80 | + |
| 81 | +Timeline (refined): |
| 82 | +``` |
| 83 | +2026-05-08..15 Governance-first harness + rapid surface expansion (same sprint) |
| 84 | +2026-05-16..06-12 Continued hardening + external-facing daily-driver/competitive docs |
| 85 | +2026-06-13 Owner-ratified harness-first identity; external adoption descoped |
| 86 | +2026-06-14+ Execute plan: event-spine migration (ADR 0032 M1–M7), docs tiering, UX friction log |
| 87 | +``` |
| 88 | + |
| 89 | +## 3. Dormant / experimental / shadow / descoped surfaces |
| 90 | + |
| 91 | +Package scale (drives the discoverability risk in §6): **56 top-level CLI commands**, |
| 92 | +**65 `TEAAGENT_*` env flags**, **21 optional extras**, **14 providers** `[OBSERVED`]. |
| 93 | +Status legend: *unwired* = reachable from no entry point (carries `experimental — |
| 94 | +unwired`); *shadow* = runs but never enforces; *descoped* = wired + real but product- |
| 95 | +descoped; *dormant-path* = code exists, no production caller; *documented-uncalled* = |
| 96 | +README claims a behavior whose function is never invoked. |
| 97 | + |
| 98 | +| # | Surface | CLI / flag | Status (panel-corrected) | Evidence | |
| 99 | +|---|---------|-----------|--------------------------|----------| |
| 100 | +| L1 | Consensus / multi-sig | `consensus` | **partial** — CLI + `consensus/engine.py` wired; only `consensus_validation.py` unwired (ADR-0029 defers *validation integration*, not the CLI) | validate_wiring; CapabilityWiring | |
| 101 | +| L2 | Policy engine + RBAC (H4) | `TEAAGENT_H4_POLICY_MODE`/`_RBAC_MODE` | **shadow (split)** — policy shadow-only, *never blocks* (`evaluate_approval_policy_shadow` always True); RBAC enforce only via `TEAAGENT_H4_RBAC_MODE=enforce` | CapabilityWiring | |
| 102 | +| L3 | Policy routing | — | **unwired** (`experimental — unwired`) | validate_wiring | |
| 103 | +| L4 | Scope-creep detector | — | **unwired** | validate_wiring | |
| 104 | +| L5 | Self-update mechanism | — | **unwired** (`update/*`) | validate_wiring | |
| 105 | +| L6 | Graph federation | `sync` | **partial** — `sync export/import/status` (FederatedGraphSync, file-based) wired; A2A/ANP/ACP *protocol adapters* have no CLI/runner entry → dormant | CapabilityWiring | |
| 106 | +| L7 | Managed cloud runtimes | `cloud submit`; extras `managed-google-adk/vertex` | **advanced (opt-in egress)** — wired; hits provider SDKs only with runtime + extra installed | CapabilityWiring | |
| 107 | +| L8 | OAuth 2.1/DPoP + MCP HTTP | `mcp serve --http` | **advanced (opt-in)** — OAuth only with explicit `--oauth-issuer`/`--oauth-signing-key`; default bind 127.0.0.1; non-loopback refused without auth | CapabilityWiring | |
| 108 | +| L9 | Gateway / control-plane / JIT | `gateway`, `control-plane` | **descoped + wired** — these are `ENTRY_ROOTS`; handlers run real servers. Product-descoped, not dormant | CapabilityWiring | |
| 109 | +| L10 | Tournament / swarm | `agent run --parallel N`; `experiment` | **partial** — `--parallel` uses `ParallelExperimentStack` (real); `SwarmManager.run_code_reviews`/`select_best_result` is **dormant-path** (tests only) | CapabilityWiring; U4 | |
| 110 | +| L11 | Code Mode sandbox | `sandbox`; `code_mode` | advanced — AST-validated restricted exec; subprocess/container/gVisor backends | packet E7 | |
| 111 | +| L12 | GraphRAG / code ontology / hybrid | `code-ontology`, `sync`; `TEAAGENT_HYBRID_*` | advanced (extra `graphqlite`) | packet E5 | |
| 112 | +| L13 | Distributed approval queue | `TEAAGENT_APPROVAL_COORDINATION_*`, `TEAAGENT_REDIS_*` | advanced (Redis/file/http; file-backed default) | CapabilityWiring | |
| 113 | +| L14 | Browser automation | extra `playwright` | dormant unless extra installed | packet E5 | |
| 114 | +| L15 | Feature-flag system | `TEAAGENT_FEATURE_*` | hidden runtime flags | packet E4 | |
| 115 | +| L16 | `ultrawork` workers | `ultrawork` | **deprecated** | teaagent --help | |
| 116 | +| L17 | Replay / time-travel | `replay` | advanced | teaagent --help | |
| 117 | + |
| 118 | +### 3b. Documented-but-uncalled functions (the honest "leaked features") |
| 119 | +These are README/doc behaviors whose backing function has **zero production call sites** — |
| 120 | +half-wired features that read as shipped but are not `[OBSERVED` EvidenceSkeptic]: |
| 121 | +- **D1** README §7 "future tasks automatically receive warnings" → `get_failure_warnings()` never called (README:133; chat_commands.py:213-256). |
| 122 | +- **D2** README §7 `teaagent📌2>` pin indicator → prompt has no pin count (README:141; tui/core.py:1515-1519). |
| 123 | +- **D3** README §7 CLI auto-refresh on pinned-file save → `FileWatcher` is TUI-session only (README:139; tui/core.py:603). |
| 124 | +- **D4** README §8 "LSP/static analysis integrated with `--validate`" → `--validate` runs ruff/mypy/pytest; `ValidationRunner` (LSP) unwired (README:145; validation/*). |
| 125 | +- **D5** README §8 "validates code *before committing*" → post-run validation only (README:149; _agent/config.py:184-209). |
| 126 | +- **D6** README §10 "automatic RAG archive after workflow completion" → `archive_to_rag()` has zero call sites (README:180; context_bus.py:350). |
| 127 | + |
| 128 | +### 3c. Invalid documented CLI/API surfaces (doc drift) |
| 129 | +Repo guides cite surfaces that don't exist; correct forms `[OBSERVED` UsageScenarioReviewer]: |
| 130 | +- `agent runs show --receipt` → `teaagent agent status <run_id> --evidence --human`. |
| 131 | +- `audit export --audit-log <run_id>` → `teaagent audit export <run_id> [--output PATH]`. |
| 132 | +- `@hook_registry.register('before_tool_call')` → `HookRegistry.register_pre_hook(...)` / `register_post_hook(...)` (integration-guide.md:291,295). |
| 133 | +- Stale metric: harness-first doc says "650/650 acceptance"; current is 663 (D7). |
| 134 | + |
| 135 | +## 4. Better ways to use (all verified PASS) |
| 136 | + |
| 137 | +- **BU1** Prefer `teaagent setup` (guided; `--verify --write-env --context-profile`) over legacy `init`. |
| 138 | +- **BU2** `teaagent daily … --dry-run --human`, `preflight`, `plan` — read-only, zero-model cockpit before spending. |
| 139 | +- **BU3** `teaagent doctor config` prints per-key **source + precedence** (`[cli, env, env-file, config.json, config.toml, default]`) — kills "why is it read-only" confusion. (`config-lint`, `env-order` also exist.) |
| 140 | +- **BU4** Extend via **hooks/plugins**, not forks: `HookRegistry.register_pre_hook/register_post_hook`; plugin tools via entry-point group `teaagent.tools` + `validate_plugin_tools`. |
| 141 | +- **BU5** Verify-first: `teaagent audit verify`, `tool lint`, `doctor review-institution`. |
| 142 | +- **BU6** Opt-in power: `agent run --validate --validation-profile {fast,standard,strict}` (post-run) and `--parallel N` (read-only tournament analysis). |
| 143 | + |
| 144 | +## 5. Scenarios (all verified PASS) |
| 145 | + |
| 146 | +- **S1 Owner-operator daily coding** (current truth): `setup → daily → preflight/plan → run → agent status <run> --evidence --human → undo/journal/cockpit/watch`. |
| 147 | +- **S2 Co-maintainer agents** editing the harness under `agent-contribution-contract.md` (Active) — gated by docs validator + acceptance collect + ruff + mypy. |
| 148 | +- **S3 Security reviewer** auditing runs — `audit verify/export`, `doctor config-lint/review-institution`, receipts. *(Note: some security guides use invalid flags — see §3c.)* |
| 149 | +- **S4 Tool/plugin/provider author** — `tool lint`, `plugin {list,show,verify}`, authoring guides. |
| 150 | +- **S5 MCP server for external IDE/agents** — `mcp serve` (stdio default; `--http` + OAuth). Present but adjacent to descoped external-integration territory. |
| 151 | + |
| 152 | +## 6. Chief risk: discoverability-vs-safety (not insecure-by-default) |
| 153 | + |
| 154 | +Panel U5 verdict: **no dormant surface auto-starts network I/O**; defaults are loopback, |
| 155 | +non-loopback binds are *refused* without auth, and the default approval backend is |
| 156 | +file-backed `[OBSERVED` CapabilityWiring]. The real exposure is **cognitive**: with 56 |
| 157 | +commands and 65 flags, an operator can enable WAN-exposing surfaces |
| 158 | +(`gateway start`, `cloud submit`, `sync` signature relay, `mcp serve --http --host |
| 159 | +0.0.0.0`) without realizing they opened an egress/attack surface. Supply-chain risk is |
| 160 | +low at base install and rises with optional extras (`managed-*`, `playwright`, `redis`, |
| 161 | +gateway SDKs). Recommendation: mark those four as explicit "WAN-exposure operations" in |
| 162 | +operator docs; keep the harness-first default posture. |
| 163 | + |
| 164 | +## 7. Recommendations (highest value first) |
| 165 | +1. Reconcile §3b documented-but-uncalled features: either wire them or move them to a |
| 166 | + clearly-labeled "planned/experimental" section (honesty debt the harness-first |
| 167 | + docs-truth rule targets). |
| 168 | +2. Fix §3c invalid documented surfaces in security/integration guides. |
| 169 | +3. Add a one-screen "surface safety map" flagging WAN-exposing commands (§6). |
| 170 | +4. Consider a `teaagent surfaces` extension that annotates each command's status |
| 171 | + (wired/shadow/descoped/deprecated) — turns the discoverability risk into a feature. |
| 172 | + |
| 173 | +--- |
| 174 | + |
| 175 | +## Evidence actually checked |
| 176 | +- **Executed:** `git log --reverse`; `teaagent --help` and subcommand `--help` |
| 177 | + (setup/daily/preflight/plan/doctor/agent run/mcp serve/consensus/cloud/gateway/sync); |
| 178 | + `scripts/validate_wiring.py --report`; env-flag + provider AST scans; module glob. |
| 179 | +- **Read:** README.md, `harness-first-direction-2026-06-13.md`, product-principles/ |
| 180 | + malleable-harness strategy docs, `agent-contribution-contract.md`, hooks.py, |
| 181 | + plugin_system.py, policy_engine.py/rbac.py, context_bus.py, validation/*, llm/_config.py. |
| 182 | +- **Inferred (flagged):** the origin arc interpretation; "better usage" prioritization; |
| 183 | + risk severity. Corrected by four adversarial reviewers (verdicts: 4× AGREE WITH CHANGES). |
| 184 | +- **Not executed:** no project-wide test run for this analysis; no code edited; reviewer |
| 185 | + claims about specific `file:line` call-sites were spot-checked, not exhaustively re-run. |
0 commit comments