Metadata-Version: 2.4
Name: sharedagents
Version: 0.0.1
Summary: Sovereign-inference TUI chat against an OpenAI-compatible vLLM endpoint.
Author-email: sharedagents <admin@sharedcode.ai>
License-Expression: MIT
Project-URL: Homepage, https://sharedcode.ai
Project-URL: Documentation, https://sharedcode.ai/docs/
Keywords: llm,tui,vllm,agent,acp,sovereign-inference
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=0.85
Requires-Dist: httpx>=0.27
Requires-Dist: aiohttp>=3.9
Requires-Dist: rich>=13.0
Requires-Dist: requests>=2.32
Requires-Dist: openai>=1.0
Requires-Dist: sqlite-vec>=0.1.6
Requires-Dist: mcp>=1.0
Requires-Dist: agent-client-protocol>=0.9
Requires-Dist: hypercorn>=0.17
Requires-Dist: starlette>=0.40
Requires-Dist: sse-starlette>=2.1
Requires-Dist: tokenizers>=0.20
Provides-Extra: realtime
Requires-Dist: numpy>=1.26; extra == "realtime"
Provides-Extra: full
Requires-Dist: trafilatura>=2.0; extra == "full"
Requires-Dist: markitdown[pdf]>=0.0.1a3; extra == "full"
Requires-Dist: markitdown-mcp>=0.0.1a3; extra == "full"
Requires-Dist: imageio-ffmpeg>=0.5.1; extra == "full"
Requires-Dist: yt-dlp>=2024.10.7; extra == "full"
Requires-Dist: youtube-transcript-api>=1.0; extra == "full"
Provides-Extra: web
Requires-Dist: flask>=3.1.3; extra == "web"
Requires-Dist: gunicorn>=23.0; sys_platform != "win32" and extra == "web"
Requires-Dist: waitress>=3; extra == "web"
Provides-Extra: stt
Requires-Dist: faster-whisper<2,>=1.0; extra == "stt"
Provides-Extra: bedrock
Requires-Dist: boto3<2,>=1.43.101; extra == "bedrock"
Provides-Extra: whatsapp
Requires-Dist: neonize==0.5.2; extra == "whatsapp"
Provides-Extra: vllm-router
Requires-Dist: fastapi>=0.115; extra == "vllm-router"
Requires-Dist: uvicorn[standard]>=0.30; extra == "vllm-router"
Requires-Dist: httpx>=0.27; extra == "vllm-router"
Requires-Dist: pyyaml>=6.0; extra == "vllm-router"
Requires-Dist: python-multipart>=0.0.9; extra == "vllm-router"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-xdist>=3.5; extra == "dev"
Requires-Dist: pytest-timeout>=2.3; extra == "dev"
Requires-Dist: numpy>=1.26; extra == "dev"
Requires-Dist: pymongo>=4; extra == "dev"
Requires-Dist: lz4>=4; extra == "dev"
Requires-Dist: playwright>=1.40; extra == "dev"
Requires-Dist: basedpyright>=1.23; extra == "dev"
Requires-Dist: import-linter>=2.0; extra == "dev"
Requires-Dist: jsonschema>=4; extra == "dev"
Requires-Dist: telethon>=1.36; extra == "dev"
Requires-Dist: gTTS>=2.4; extra == "dev"
Requires-Dist: neonize==0.5.2; extra == "dev"
Dynamic: license-file

# SharedCode

> **Run it now:** `git clone … && cd sharedcode && ./sharedcode` —
> the launcher creates `.venv/`, installs dependencies, and starts
> the TUI. Or `pip install sharedcode && sharedcode` — the first-run
> wizard walks you through the LLM endpoint and model choice.

## Install

```bash
pip install sharedcode
```

That puts a `sharedcode` command on your `PATH`. Run it once with no
arguments — the first-run wizard walks you through the LLM endpoint,
model, and (optionally) Telegram, then brings the gateway up itself.
Three steps and you're in the TUI:

> **`pip install sharedcode` → `sharedcode` → answer the wizard → done.**

Optional extras:

| Install command | What you get |
|---|---|
| `pip install sharedcode` | Lean core — TUI + orchestrator + gateway + MCP client + SQLite storage |
| `pip install sharedcode[full]` | Add PDF/DOCX/YouTube/web-extraction tools |
| `pip install sharedcode[web]` | Add the browser chat frontend (Flask; waitress on Windows, gunicorn on POSIX) |
| `pip install sharedcode[stt]` | Add local Fast Whisper speech-to-text (CPU) |

### From a clone (for development)

`git clone … && cd sharedcode && ./sharedcode` — the launcher creates
`.venv/`, runs an editable `pip install -e .`, and starts the TUI.

## Run the gateway, orchestrator and WebUI together

```bash
pip install "sharedcode[web]"     # the WebUI lives in the [web] extra
python -m sharedcode.serve        # foreground: Ctrl+C stops the whole stack
```

`serve` brings all three components up and prints one line per component:

```text
START orchestrator 8099 pid=1234 http=200
START gateway 8100 pid=1235 http=200
START web 8110 pid=1236 http=200
WebUI http://127.0.0.1:8110  (Ctrl+C stops the stack; --detach keeps it running after this shell exits)
```

| Component | Default address |
|---|---|
| orchestrator | `http://127.0.0.1:8099` |
| gateway | `http://127.0.0.1:8100` |
| WebUI | `http://127.0.0.1:8110` |

```bash
python -m sharedcode.serve --detach   # background; survives the shell closing
python -m sharedcode.serve status     # one PASS/FAIL line per component
python -m sharedcode.serve stop       # shut the stack down
python -m sharedcode.serve --no-web   # backend roles only (no [web] extra needed)
```

The same entry point is installed as the `sharedcode-serve` console script, and
`python -m sharedcode` is an alias. There is deliberately no service supervisor and
no restart loop: a component that dies is reported by name, never respawned.

Inside a source checkout, `sharedcode.bat` / `sharedcode-stop.bat` /
`sharedcode-status.bat` wrap these same three commands for Windows.

## Core Packages

Modular packages under `src/` — installed as `pip install sharedcode`:

| Package | Role |
|---|---|
| `sharedcode_session` | **Storage Engine**: Single-file `<sid>.jsonl` ledger + instant SQLite cache (`sessions.db`) |
| `sharedcode_orchestrator` | **Execution Core**: Turn loop, multi-modal engine adapters (CLI, ACP, A2A), tool dispatch |
| `sharedcode_a2a` | **Agent-to-Agent Protocol**: Structured `a2a/v1` message envelopes (spawn, progress, task_completed) |
| `sharedcode_acp` | **Agent Client Protocol**: JSON-RPC 2.0 IDE server/client (Cursor, Zed, JetBrains) |
| `sharedcode_gateway` | **Edge Membrane**: Auth, Ingress Queue (<5ms ACK), fast REST cache (<2ms), SSE streaming |
| `sharedcode_tui` | **Terminal TUI**: Textual-based interactive terminal interface |
| `sharedcode_web` | **Browser WebUI**: Multi-tab interface (Sessions, Usage, Agent Monitor, Tasks, Loops, Topics, Dev, Goals, Voice, Agent Builder) |
| `sharedcode_realtime` | **Realtime Voice**: WebRTC full-duplex bidirectional audio streaming |
| `sharedcode_telegram` | **Telegram Bot**: Group chat, voice notes, images and documents in, agent files out, remote execution |
| `sharedcode_whatsapp` | **WhatsApp**: Self-chat channel via a linked device — text, voice notes, images, PDF/Markdown/Office documents, agent files out, agent questions |
| `sharedcode_mcp` | **MCP Servers**: Bundled MCP tools (memory, search, filesystem, terminal) |

## Extras

- **`[full]`** — trafilatura (web-fetch), markitdown (PDF/DOCX), yt-dlp + youtube-transcript-api (YouTube), imageio-ffmpeg (voice-note transcode)
- **`[web]`** — Flask for the browser chat frontend (waitress on Windows, gunicorn on POSIX)
- **`[stt]`** — faster-whisper (CPU-only STT for Telegram voice)
- **`[bedrock]`** — boto3/botocore for the **native Amazon Bedrock Converse** transport. The tested SDK minimum is 1.43.101; older SDKs fail before client construction. Optional: a non-Bedrock install must never need the AWS SDK.
- **`[whatsapp]`** — neonize (Go whatsmeow) linked-device transport for `sharedcode_whatsapp`. Needs the system `libmagic1` library.

## WhatsApp (self-chat channel)

Talk to your agent from WhatsApp: sharedcode links to your account as a companion device
(like WhatsApp Web, shown as "sharedcode" under *Linked devices*). You write in your own
"Message yourself" chat and the agent answers in the same chat, including turns that
finish later in the background.

```bash
pip install 'sharedcode[whatsapp]'           # plus: apt install libmagic1
sharedcode whatsapp link                     # scan the QR (also saved as ~/.sharedcode/whatsapp/link-qr.png)
sharedcode whatsapp link --phone +5511...    # or get an 8-character pairing code instead
sharedcode whatsapp install-service          # systemd user unit sharedcode-whatsapp.service
sharedcode whatsapp status
```

In the chat, `/new` starts a fresh session, `/stop` stops a turn, `/agent <name>` switches
agents and `/status` shows the link. Every other `/command` runs in the agent runtime.
Voice notes are transcribed through the `stt` service, and agent questions or permission
prompts are answered by replying with a number.

**Files.** Send an image (as a photo or as a file) and the agent sees it; send a PDF,
Markdown/text or Office document and the agent reads its text (converted with `markitdown`
from the `[full]` extra; up to `max_media_mb`, default 16 MB). When the agent links a file
it made (`[Report](</abs/path/report.pdf>)`, the same contract the web UI uses), the file
follows its answer: PNG/JPEG/WebP as a photo, anything else as a document. Agents can also
queue files with the `whatsapp` skill: `send --file </abs/path/report.pdf> [text]`.
Telegram does the same: images and documents in, the agent's linked files out.

- **Privacy.** The service only reads and writes your self-chat. Other chats are ignored
  and never logged.
- **Credentials.** `~/.sharedcode/whatsapp/neonize.sqlite3` is a live WhatsApp login, stored
  with permissions 0600. `sharedcode whatsapp logout` revokes it.
- **Terms of service.** This is an unofficial client, the same approach as WhatsApp Web
  automation tools. Keep it to your own self-chat. Settings live in
  `~/.sharedcode/whatsapp/config.json` (design:
  `docs/2026-09-24-whatsapp-channel-design.md`).

## Amazon Bedrock (native Converse)

sharedcode talks to Bedrock through the **native Converse / ConverseStream API**
(not the OpenAI-compatible endpoint). Install the optional SDK:

```bash
pip install 'sharedcode[bedrock]'          # release
pip install -e '.[bedrock]'             # editable clone
```

With AWS credentials already in the service environment, native agents discover
Bedrock models automatically; no provider entry or setup wizard is required.
Discovery uses `AWS_REGION`, then `AWS_DEFAULT_REGION`, then the AWS profile's
region, and defaults to **`sa-east-1`** when none is set. Environment IAM keys
(including temporary session tokens), Bedrock bearer tokens, explicit AWS
profiles, shared credentials, and container/web-identity credentials are supported.
It does not probe EC2 instance metadata just to populate the picker.

At model load, sharedcode lists active streaming text foundation models and inference
profiles. Results are cached for five minutes within each process; the model
picker's refresh bypasses that cache. Catalogue reads make no inference calls.
Removing credentials removes automatic rows on the next config reload. Other
engines and the selected default model are unchanged. AWS model access and
Converse/tool support still depend on the model and account.

For custom aliases, credentials or context limits, add a model row with
`api: "bedrock-converse"` (the explicit marker that
selects the transport) or run `sharedcode configure` and choose
`b. Amazon Bedrock`. Example row (illustrative — **no credentials**):

```json
{
  "alias": "bedrock-primary",
  "api": "bedrock-converse",
  "backend": "bedrock",
  "provider": "bedrock",
  "baseUrl": "bedrock://us-east-1",
  "region": "us-east-1",
  "id": "<operators-supply-a-real-foundation-id-or-inference-profile-arn>",
  "auth": "aws-iam",
  "contextWindow": 200000,
  "maxTokens": 8192
}
```

- Manual rows take precedence over discovered rows for the same region/model.
  AWS catalogue responses omit context limits, so automatic rows use a conservative
  4,096-token context budget and 1,024-token output limit. Set a manual row to use
  the model's verified larger limits. Discovery never saves credentials in rows.
- `baseUrl` is a `bedrock://REGION` display URL only; the SDK derives the real
  HTTPS endpoint from `region`. A `bedrock://` URL is never parsed as HTTP.

### Authentication

Both modes are supported; there is **no silent fallback** between them.

- **`auth: "aws-iam"`** (recommended): the normal boto3 chain — IAM role,
  instance/container credentials, shared config or `AWS_PROFILE` (`profile` on
  the row overrides `AWS_PROFILE` in that child worker only). AWS recommends
  short-lived role credentials over long-term keys.
- **`auth: "bedrock-api-key"`**: a Bedrock bearer token, resolved per-agent
  first (`secrets.env` / `api_keys`) then inherited environment, under
  `apiKeyEnv` (default `AWS_BEARER_TOKEN_BEDROCK`). An explicit empty value
  means "no key" and blocks the environment fallback. The value is set only in
  the child worker's environment at request time and is **never** written to
  `config.json`, sessions, logs or the request JSON.

### Permissions and pricing

- Least privilege: `bedrock:InvokeModelWithResponseStream` for normal turns,
  plus `bedrock:InvokeModel` if a one-shot path (vision transcription,
  compaction, distillation) is used.
- Automatic discovery also needs `bedrock:ListFoundationModels` and
  `bedrock:ListInferenceProfiles`. A profile-list denial still allows direct
  foundation models; discovery failure leaves manual rows available.
- Enable model access and any cross-region inference profile in the AWS
  console for the target account/region.
- Costs come from the metrics the worker reports (provider `bedrock`) plus the
  operator's `~/.sharedcode/pricing.json`. Bedrock model/region prices vary; set
  exact model or alias overrides from the AWS price sheet rather than a blanket
  rate.

### Compatibility and limitations

- Streaming text, client-side tool calls/results and image blocks are
  supported where the chosen model supports them.
- **Extended reasoning is off in v1**: no `additionalModelRequestFields`
  thinking, the picker/`/effort` marks depth unsupported, and signed
  `reasoningContent` during a tool turn fails closed rather than replaying an
  unsigned assistant turn.
- `sharedcode doctor --health` checks a Bedrock route **offline** (region/auth and
  credential presence). `sharedcode doctor --bedrock-smoke` makes an explicit,
  opt-in, billable live call; it is never run by `--health`.

## Sampling configuration

Sampling is minimal by default: no temperature, top_p, top_k, min_p,
repetition_penalty, presence_penalty, frequency_penalty or seed is sent unless
configured or strictly required by the provider (currently kimi-k3 requires
temperature 1.0). Providers apply their own defaults. Token budgets, thinking
settings, tools and local loop-protection extras retain their existing behavior.

Add these blocks to the global config, merging with your existing settings:

```json
{
  "sampling": {"temperature": 0.3, "top_p": 0.9},
  "side_sampling": {
    "title": {"temperature": 0.5},
    "distill": {"temperature": 0.2, "presence_penalty": 1.0},
    "compaction": {"temperature": 0.1}
  }
}
```

Precedence, lowest to highest: legacy top-level `temperature` → `sampling`
for main turns, or `side_sampling[purpose]` for side calls → the selected
`models[]` row's `sampling` → per-turn `sampling` → provider-required values.
Side calls do not inherit global `sampling`. A higher-layer `null` removes
an inherited value; for example, `"sampling": {"temperature": null}` on one
model row opts that row out of a global temperature. Zero is an explicit value.
Unknown keys, booleans and invalid numeric values are ignored.

The side-call purposes are `distill`, `compaction`, `title`, `teacher`,
`goal_review`, `command_validator`, `vision`, `memory_synth`, `intake` and
`x_search`. Bedrock only sends supported temperature/top_p values; the Codex
Responses transport strips unsupported sampling fields. Explicit hosted-row
settings (including top_k) are sent, so choose fields your provider supports.

To opt a Gemma deployment into its former profile, add this property to that
existing model row:

```json
{
  "sampling": {
    "temperature": 0.4,
    "top_p": 0.9,
    "top_k": 20,
    "min_p": 0.0,
    "frequency_penalty": 0.4,
    "presence_penalty": 0.3,
    "repetition_penalty": 1.05
  }
}
```

For local Qwen deployments, the built-in DRY sampler and repetition detector
are retained automatically. These existing extras remain unchanged; they are
not new configurable sampling keys:

```json
{
  "dry_multiplier": 0.8,
  "dry_base": 1.75,
  "dry_allowed_length": 4,
  "dry_sequence_breakers": ["\n", ".", "!", "?", ":", "—", "```"],
  "repetition_detection": {
    "max_pattern_size": 80,
    "min_pattern_size": 4,
    "min_count": 5
  }
}
```

Optional Qwen tuning belongs in its model row's `sampling`, for example
`{"presence_penalty": 1.0, "min_p": 0.05}` when supported by the deployment.
This replaces the old `SHAREDCODE_AUTO_PRESENCE_PENALTY`,
`SHAREDCODE_AUTO_MIN_P` and `SHAREDCODE_DISTILL_PRESENCE_PENALTY` tuning knobs
(use `side_sampling.distill.presence_penalty` for the latter).

The `/temperature` command, Agent Builder and setup wizard continue writing
the legacy top-level temperature alias; clear it with `null` to use upstream
defaults. A value in `sampling.temperature` takes precedence over that alias.
Raw realtime chat separately accepts `realtime.temperature` as a number or
`null`, and omits it by default.

Deploy note: remove an existing live top-level default temperature separately
when adopting minimal defaults. This code change does not edit live config.

## Memory index maintenance

Normal maintenance is automatic: `remember` indexes immediately after a
successful write, memory search lazily indexes detected drift before querying,
and the gateway heartbeat asks the persistent memory service to reindex only
when needed. The Markdown files remain the source of truth; `memory.db` is a
rebuildable search index.

Use the operator CLI when checking or repairing an agent explicitly:

```bash
# Show file/chunk/vector counts, index scope, and whether drift is pending.
sharedcode memory status --agent codex

# Safe incremental pass: changed files and missing vectors only.
sharedcode memory index --agent codex

# Rebuild chunks/FTS/vectors, retaining reusable embedding-cache rows.
sharedcode memory index --agent codex --force

# Also discard the cache and call the configured embedding provider again.
sharedcode memory index --agent codex --reembed
```

Start with the incremental command. `--force` rebuilds only the derived index;
it does not delete the Markdown memories. `--reembed` is the expensive recovery
path for a changed model or poisoned cache and requires a working embedding
provider.

---

## sharedcode is the cypherpunk version of inference.

It exists to empower the user to have total control over their data and ideas, without the hassle of endless configuration or requiring deep open-source model knowledge just to get useful work done.

This project starts from a hard truth: the AI industry is underinvesting in infrastructure and degrading model quality to keep up with demand. Decisions like blocking OpenClaw from the Max plan and forcing heavy API costs on users reinforce the view that AI companies are sucking people and companies' ideas like the Matrix uses human crops for creativity and for studying human thought processes.

That is the opposite of sovereignty.

The current model asks users and companies to pour their private context, internal reasoning, product ideas, and operational intelligence into centralized AI systems they do not control. In return, they get rising costs, shrinking access, degraded quality under load, and dependence on infrastructure decisions made by someone else.

And the risk is not theoretical.

The imminent Taiwan conflict will create heavy shocks to current business. Any company relying on AI will have no option but to pay the price of neoclouds if supply chains seize up and centralized inference tightens further. Businesses that chose not to build on-prem infrastructure, or at least retain the option, will be trapped into paying whatever the market demands.

sharedcode is the answer to that trap.

sharedcode is a custom-built agent system that adapts to the available inference capacity by creating tailored agents for each hardware profile, from a modest RTX 3060 to RTX 3090, RTX 4090, RTX 5090, A6000-class workstations, and up to advanced rented neocloud GPUs on platforms like Vast.ai.

Instead of forcing every task through one oversized, expensive, centralized stack, sharedcode rightsizes inference to the real job:

- small agents on cheap local hardware
- stronger agents on workstations
- burst agents on rented neocloud GPUs
- flexible routing based on actual available capacity
- model selection based on task value, latency, and hardware envelope
- agent behavior shaped around the realities of the machine it runs on

Agents can be spawned in seconds using the right-sizing capacity for each task, reducing the cost of AI while increasing resilience, performance, and control.

---

## Why sharedcode exists

Most AI products are built around a hidden assumption: the user should adapt to the vendor.

The vendor chooses the models.  
The vendor chooses the pricing.  
The vendor chooses when quality gets degraded.  
The vendor chooses which products get blocked.  
The vendor chooses which workloads are too expensive.  
The vendor chooses whether your use case is welcome.  

sharedcode rejects that model.

The intelligence layer of a company is too important to outsource blindly. Your prompts are not just prompts. They are product direction, customer knowledge, internal process, strategy, failure modes, experimentation, and judgment in raw form. If your AI stack is not sovereign, your cognition stack is not sovereign.

---

## Core Principles

- **Own the data**: Single-file session logs stored locally on your machine.
- **Own the ideas**: No outbound telemetry leaks.
- **Own the inference path**: Seamless fallback between local vLLM, private workstations, and cloud models.
- **Instant Responsiveness**: `< 5ms` submission ACKs on all inputs, `< 2ms` UI cache reads from SQLite.
- **Zero Configuration Sprawl**: Single `.jsonl` session files, extensible JSON tool containers, zero sidecars.
- **Clean Protocol Boundaries**: **ACP** for IDE control (North-South), **A2A** for multi-agent swarms (East-West).
- **Cancel Scopes You Can Reason About**: Abort one turn and only that turn dies; abort a subagent and only that subagent terminates.

---

## Architecture Overview

The canonical system architecture is documented in detail in the [Technical Specifications](spec/README.md).

**Runtime:** `sharedcode gateway start` brings up the south orchestrator (`:8099`) then the north gateway (`:8100`). `sharedcode gateway stop` stops both.

```mermaid
flowchart TD
    Clients["Multi-Interface Clients<br/><b>WebUI • Telegram • TUI • IDE (via ACP)</b>"]
    
    Gateway["sharedcode_gateway (North)<br/>• Ingress Auth & Multi-Source Queue (<5ms ACK)<br/>• Fast SQLite Cache Server (<2ms)<br/>• Multi-Subscriber SSE Streamer"]
    
    Orchestrator["sharedcode_orchestrator (South)<br/>• Turn & Round State Machine<br/>• Multi-Modal Engine Adapters (CLI, ACP, A2A)<br/>• Tool Dispatch & AI Model Telemetry"]
    
    Storage["sharedcode_session (Storage Engine)<br/>• Single-File Ledger (<session_id>.jsonl)<br/>• Instant SQLite Cache (sessions.db)"]
    
    Clients -->|"1. Submit Prompts & Subscribe Stream"| Gateway
    Gateway -->|"2. Priority Ingress Queue (FIFO)"| Orchestrator
    Orchestrator -->|"3. Append Events, Row Markers, & Project Cache"| Storage
    Gateway -.->|"4. Fast REST Reads & SSE Tails"| Storage
```

### 1. Storage Tier (`sharedcode_session`)
- **Single-File Ledger (`<session_id>.jsonl`)**: Exactly 1 immutable, append-only file per session. Zero loose sidecars.
- **Materialized SQLite Cache (`sessions.db`)**: Atomic single-row reads for instant UI loading (`< 2ms`).
- **Extensible JSON Containers (`tools_state_json`)**: Dynamic tool state updates (Kanban, Todos, Canvas) via `json_set()` with zero database schema migrations.
- **Row Range Markers**: Exact `[start_row_idx, end_row_idx]` recorded for every turn and every AI model call.

### 2. Multi-Modal Execution (`sharedcode_orchestrator`)
- **CLI Adapter**: Invokes subprocess CLI tools (`agy`, `claude`, `codex`) and wraps them into standard message envelopes.
- **ACP Adapter**: Interacts with external IDEs (Cursor, Zed) via JSON-RPC 2.0.
- **A2A Adapter**: Coordinates autonomous subagents via native `a2a/v1` message envelopes.
- **AI Telemetry Collector**: Captures TTFT, generation speed (tokens/sec), routing overhead, token volume, and cost ($) into the `ai_generations` table.

### 3. Edge Membrane (`sharedcode_gateway`)
- **Session Ingress Queue**: Immediate `< 5ms` submission ACK for WebUI, Telegram, TUI, A2A subagents, and schedulers.
- **Priority Intake**: `Priority 0 (Control)` $\rightarrow$ `Priority 1 (Subagent Returns)` $\rightarrow$ `Priority 2 (User Prompts)` $\rightarrow$ `Priority 3 (System Nudges)`.
- **Row-Indexed SSE Streaming**: Clients seek directly to any row (`GET /stream?from=<row_idx>`) with zero token loss and zero duplicate frames.

---

## Documentation Roadmap

The full system documentation is organized into 10 domain directories matching the WebUI tabs:

- **[Requirements (WHAT)](requirements/README.md)**: Product specifications, functional requirements (FR-01 to FR-11), and quality SLAs.
- **[Technical Specifications (HOW)](spec/README.md)**: Authoritative architecture contracts, Mermaid diagrams, event wire schemas, and SQLite table definitions.
- **[Implementation Plans (WHEN)](plan/README.md)**: Phase-by-phase engineering execution roadmaps and automated test verification suites.

Project homepage and maintainer contact are defined together in the `[project]` section of `pyproject.toml` and included in installed package metadata.
