babelagent 0.1.0__tar.gz

babelagent-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install (with serve + mcp + dev extras)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[serve,mcp,dev]"
+      - name: Lint
+        run: ruff check src tests
+      - name: Type check
+        run: mypy src
+      - name: Test
+        run: pytest -q
+      - name: Smoke (key-free demo)
+        run: babelagent demo

babelagent-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "src/**"
+      - "mkdocs.yml"
+      - "CHANGELOG.md"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deploy; don't cancel an in-progress production deploy.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install (package for autodoc + mkdocs)
+        run: pip install -e . mkdocs-material "mkdocstrings[python]"
+      - run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

babelagent-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish
+
+# Releases to PyPI via OIDC Trusted Publishing (no token secrets in the repo).
+# Configured pending publisher: repo amitpatole/babelagent, workflow publish.yml.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # mint the OIDC token PyPI verifies against the publisher
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install --upgrade pip build
+      - run: python -m build
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

babelagent-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Docs build
+site/
+
+# OS
+.DS_Store
+
+# Security cadence — NEVER commit residuals / red-team notes / PoCs (local only)
+.security-local/
+docs/SECURITY_RESIDUALS.md
+
+# Local env / secrets (creds live in ~/.config, never here)
+.env
+*.local.toml

babelagent-0.1.0/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to Babelagent are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/); this project uses semantic versioning.
+
+## [Unreleased]
+
+### Security
+- Completed the full security cadence over the REST / MCP / A2A / HTTP surface: a 3-surface audit and
+  **four adversarial red-team rounds** (final round found nothing new). Fixed and regression-pinned:
+  attacker-controlled `deadline_s` (DoS), SSRF (allowlist + NAT64/6to4/Teredo normalization, no
+  redirects, response caps, connect-time re-guard), keyword/positional argument injection from
+  untrusted upstream output, `_safe` depth+width DoS, trace exception-message leakage, REST DNS-rebind
+  (Host pinning), slowloris (body + connection limits), and a hard wall-clock guillotine defeating
+  cancellation-swallowing agents. See `docs/SECURITY.md` for the posture, deployment guidance, and the
+  documented residuals. 22 security regression tests in `tests/security/`.
+
+### Renamed
+- Project renamed from the working title **BYOA** to **Babelagent** (import + distribution name
+  `babelagent`). The framing is now a neutral communication layer that lets heterogeneous agents talk
+  to each other (agent-to-agent), not a factory/assembly line.
+- API vocabulary re-themed: `Factory` → `Graph`, `Line` → `CompiledGraph`, `Blueprint` → `Topology`,
+  `Station` → `Node` (merged with the old graph-node wrapper), `Part` → `Message`, `Product` →
+  `Result`, check outcome `Result` → `Grade`; `.station()` → `.node()`.
+
+### Added — core graph engine
+- `Graph` builder with **linear chaining** (`.node(...).node(...)`) that compiles to a **DAG core**
+  supporting `after=` dependencies, fan-out, parallel branches, and fan-in `join`.
+- Barrier policies for fan-in: `all`, `k_of_n` (with `k`), and `optional`.
+- Async scheduler with bounded concurrency, per-node + per-run timeouts, reactive readiness, and
+  failure propagation (unsatisfiable barriers skip downstream nodes).
+- Native, dependency-free quality types: `Verdict` (pass/warn/fail), `Grade`, `Check`, and `GateMode`
+  (off/warn/strict) for optional per-node gating.
+- `Message` / `Result` envelopes; `Topology` validation (cycle + dangling-dep detection).
+
+### Added — adapters + `adapt()`
+- **`adapt()`** on-the-fly adapter creator: normalizes callables, HTTP/OpenAPI endpoints, MCP tools,
+  framework agents (LangChain / CrewAI / AutoGen), and LLM providers into the uniform `Agent` interface.
+- `CallableAgent`, `HttpAgent` (+ `from_openapi`, basic SSRF guard), `LLM` provider adapter (lazy,
+  behind extras, defaults to the latest Claude model).
+- Extensible registry: `register_adapter(...)` and the `babelagent.adapters` entry-point group.
+
+### Added — A2A adapter
+- **`A2AAgent` / `A2ARef`**: consume a remote Agent2Agent (A2A) agent as a node via the
+  `message/send` JSON-RPC method, with Agent Card discovery. Built on httpx (base wheel, no extra),
+  SSRF-guarded. `adapt(A2ARef(url))` wires a remote agent into the graph. This is the "consume the
+  protocols, don't compete with them" position: a remote A2A agent becomes just another `Agent`.
+
+### Added — interfaces
+- `babelagent` CLI (Typer): `demo`, `doctor`, `inspect`, `serve`, `mcp`, `version`.
+- **REST service** (`babelagent.io.rest`, `serve` extra): serve a graph over HTTP. Hardened from
+  birth — constant-time bearer auth, zero-config on loopback but fail-closed (refuses to bind a
+  non-loopback host without a token), request-body size cap enforced before buffering, a concurrency
+  semaphore, deadline-bounded runs, and sanitized errors. Endpoints: `GET /health`, `GET /graph`,
+  `POST /run`.
+- **MCP server** (`babelagent.io.mcp`, `mcp` extra): expose a graph as MCP tools (`run_graph`,
+  `graph_topology`) so any MCP client can run a whole graph. Works across MCP SDK 2.x (`MCPServer`)
+  and 1.x (`FastMCP`).
+- Key-free `babelagent demo`: a broken agent gated to FAIL, then a fixed one producing a PASS result.
+
+[Unreleased]: https://example.invalid/babelagent/compare

babelagent-0.1.0/CITATION.cff

@@ -0,0 +1,22 @@
+cff-version: 1.2.0
+title: Babelagent
+message: "If you use Babelagent, please cite it as below."
+type: software
+authors:
+  - family-names: Patole
+    given-names: Amit
+    email: amit.patole@gmail.com
+repository-code: "https://github.com/amitpatole/babelagent"
+url: "https://amitpatole.github.io/babelagent/"
+abstract: >-
+  The Babel that lets AI agents understand each other: a neutral, framework-agnostic
+  layer where heterogeneous agents (callables, HTTP/OpenAPI, MCP, framework agents,
+  LLMs) share one interface, collaborate agent-to-agent, and are graded at each hop.
+keywords:
+  - ai
+  - agents
+  - a2a
+  - interoperability
+  - multi-agent
+license: MIT
+version: 0.1.0

babelagent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amit Patole
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

babelagent-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.5
+Name: babelagent
+Version: 0.1.0
+Summary: The Babel that lets AI agents understand each other: a neutral layer where heterogeneous agents (callables, HTTP/OpenAPI, MCP, framework agents, LLMs) share one interface, collaborate (A2A), and get graded at each hop.
+Author-email: Amit Patole <amit.patole@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: a2a,adapters,agents,ai,dag,interoperability,multi-agent,orchestration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: pydantic>=2.6
+Requires-Dist: typer>=0.12
+Provides-Extra: agentsensory
+Requires-Dist: agentsensory>=0.1; extra == 'agentsensory'
+Provides-Extra: all
+Requires-Dist: anthropic>=0.40; extra == 'all'
+Requires-Dist: fastapi>=0.110; extra == 'all'
+Requires-Dist: langchain-core>=0.3; extra == 'all'
+Requires-Dist: mcp>=1.2; extra == 'all'
+Requires-Dist: ollama>=0.3; extra == 'all'
+Requires-Dist: openai>=1.0; extra == 'all'
+Requires-Dist: python-multipart>=0.0.9; extra == 'all'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'all'
+Provides-Extra: cloud
+Requires-Dist: anthropic>=0.40; extra == 'cloud'
+Requires-Dist: openai>=1.0; extra == 'cloud'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: frameworks
+Requires-Dist: langchain-core>=0.3; extra == 'frameworks'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Provides-Extra: ollama
+Requires-Dist: ollama>=0.3; extra == 'ollama'
+Provides-Extra: serve
+Requires-Dist: fastapi>=0.110; extra == 'serve'
+Requires-Dist: python-multipart>=0.0.9; extra == 'serve'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'serve'
+Description-Content-Type: text/markdown
+
+# Babelagent
+
+> The Babel that lets AI agents understand each other. One shared tongue for agents that were never meant to talk.
+
+Every agent framework has its own idea of what an agent is. LangChain has Runnables with `.invoke`,
+CrewAI has Crews with `.kickoff`, AutoGen has agents with `.generate_reply`, an LLM has
+`messages.create`, a microservice has an HTTP route. None of them agree on a shape, so connecting any
+two means writing glue.
+
+Babelagent is the neutral layer in between. You bring your own agents, whatever they are (a callable,
+an HTTP/OpenAPI endpoint, an MCP tool, a framework agent, or an LLM), and it wraps each one in a single
+shared interface so they can exchange messages and collaborate on a task, **agent-to-agent (A2A)**.
+The value is not any single adapter. It is that once something is adapted, it works with everything
+else you have adapted.
+
+The headline is **`adapt()`**: hand Babelagent almost anything and it builds the connector on the fly.
+
+```python
+import asyncio
+from babelagent import Graph
+
+async def main():
+    graph = (
+        Graph()
+        .node("clean",   str.strip)
+        .node("shout",   str.upper)
+        .node("exclaim", lambda s: s + "!")
+    )
+    result = await graph.run("  hello  ")
+    print(result.output)   # "HELLO!"
+
+asyncio.run(main())
+```
+
+Let different agents work in parallel and hand their results to each other, with barrier policies on
+the join:
+
+```python
+g = Graph()
+g.node("src",     lambda text: text)
+g.node("summary", adapt(langchain_agent), after=["src"])   # a LangChain agent
+g.node("labels",  adapt("https://api.example.com/classify"), after=["src"])  # an HTTP service
+g.join("merge", after=["summary", "labels"], agent=combine, barrier="all")
+result = await g.run(document)
+```
+
+## Concepts
+
+| Concept | What it is |
+|---|---|
+| **Graph** | Builds the network of agents (linear chaining **and** a DAG API) |
+| **CompiledGraph** | The validated, runnable graph; `await graph.run(payload)` |
+| **Node** | One participant: an agent plus an optional quality check/gate |
+| **Agent** | The uniform `async run(message, ctx) -> message` interface |
+| **`adapt()`** | Turns any brought object into an Agent, inferring the adapter |
+| **Message / Result** | The envelope agents exchange / the final output + run trace |
+| **Barrier** | Fan-in join policy: `all` · `k_of_n` · `optional` |
+
+## Install
+
+```bash
+pip install babelagent                 # light base (callables + HTTP)
+pip install "babelagent[mcp]"          # MCP tools
+pip install "babelagent[cloud]"        # Anthropic / OpenAI
+pip install "babelagent[ollama]"       # local models
+pip install "babelagent[frameworks]"   # LangChain / CrewAI / AutoGen
+pip install "babelagent[serve]"        # REST service
+pip install "babelagent[all]"
+```
+
+## Try it (no API key)
+
+```bash
+babelagent demo      # a broken agent (gated FAIL) then a fixed one (PASS)
+babelagent doctor    # which adapter families are available
+babelagent inspect   # print a graph's topology as JSON
+```
+
+## Status
+
+Alpha, in active development. Local-only for now. MIT licensed.
+
+— amitpatole

babelagent-0.1.0/README.md

@@ -0,0 +1,83 @@
+# Babelagent
+
+> The Babel that lets AI agents understand each other. One shared tongue for agents that were never meant to talk.
+
+Every agent framework has its own idea of what an agent is. LangChain has Runnables with `.invoke`,
+CrewAI has Crews with `.kickoff`, AutoGen has agents with `.generate_reply`, an LLM has
+`messages.create`, a microservice has an HTTP route. None of them agree on a shape, so connecting any
+two means writing glue.
+
+Babelagent is the neutral layer in between. You bring your own agents, whatever they are (a callable,
+an HTTP/OpenAPI endpoint, an MCP tool, a framework agent, or an LLM), and it wraps each one in a single
+shared interface so they can exchange messages and collaborate on a task, **agent-to-agent (A2A)**.
+The value is not any single adapter. It is that once something is adapted, it works with everything
+else you have adapted.
+
+The headline is **`adapt()`**: hand Babelagent almost anything and it builds the connector on the fly.
+
+```python
+import asyncio
+from babelagent import Graph
+
+async def main():
+    graph = (
+        Graph()
+        .node("clean",   str.strip)
+        .node("shout",   str.upper)
+        .node("exclaim", lambda s: s + "!")
+    )
+    result = await graph.run("  hello  ")
+    print(result.output)   # "HELLO!"
+
+asyncio.run(main())
+```
+
+Let different agents work in parallel and hand their results to each other, with barrier policies on
+the join:
+
+```python
+g = Graph()
+g.node("src",     lambda text: text)
+g.node("summary", adapt(langchain_agent), after=["src"])   # a LangChain agent
+g.node("labels",  adapt("https://api.example.com/classify"), after=["src"])  # an HTTP service
+g.join("merge", after=["summary", "labels"], agent=combine, barrier="all")
+result = await g.run(document)
+```
+
+## Concepts
+
+| Concept | What it is |
+|---|---|
+| **Graph** | Builds the network of agents (linear chaining **and** a DAG API) |
+| **CompiledGraph** | The validated, runnable graph; `await graph.run(payload)` |
+| **Node** | One participant: an agent plus an optional quality check/gate |
+| **Agent** | The uniform `async run(message, ctx) -> message` interface |
+| **`adapt()`** | Turns any brought object into an Agent, inferring the adapter |
+| **Message / Result** | The envelope agents exchange / the final output + run trace |
+| **Barrier** | Fan-in join policy: `all` · `k_of_n` · `optional` |
+
+## Install
+
+```bash
+pip install babelagent                 # light base (callables + HTTP)
+pip install "babelagent[mcp]"          # MCP tools
+pip install "babelagent[cloud]"        # Anthropic / OpenAI
+pip install "babelagent[ollama]"       # local models
+pip install "babelagent[frameworks]"   # LangChain / CrewAI / AutoGen
+pip install "babelagent[serve]"        # REST service
+pip install "babelagent[all]"
+```
+
+## Try it (no API key)
+
+```bash
+babelagent demo      # a broken agent (gated FAIL) then a fixed one (PASS)
+babelagent doctor    # which adapter families are available
+babelagent inspect   # print a graph's topology as JSON
+```
+
+## Status
+
+Alpha, in active development. Local-only for now. MIT licensed.
+
+— amitpatole

babelagent-0.1.0/brand/extra.css

@@ -0,0 +1,135 @@
+/* ============================================================================
+   Trio Design System — "Warm Paper" · MkDocs Material override
+   Light-first, printed-document calm. No gradients, no glows. One accent.
+   CANONICAL FILE — copied into each repo's docs/stylesheets/extra.css.
+   Per-repo accent: Babelagent (bridge) desaturated teal.
+   ============================================================================ */
+@import url('https://fonts.googleapis.com/css2?family=Source+Serif+4:opsz,wght@8..60,400;8..60,500;8..60,600;8..60,700&display=swap');
+
+:root {
+  /* ---- Warm Paper tokens ---- */
+  --wp-bg:        #f7f5f1;
+  --wp-surface:   #fffdf9;
+  --wp-panel:     #efece4;
+  --wp-ink:       #1b1a17;
+  --wp-ink-muted: #6b6862;
+  --wp-ink-faint: #918d84;
+  --wp-rule:      #e3ded4;
+
+  /* ---- Accent — Babelagent (bridge) ---- */
+  --wp-accent:     #3f8a86;
+  --wp-accent-ink: #2a615d;
+
+  --wp-serif: "Source Serif 4", Georgia, "Times New Roman", serif;
+}
+
+/* ---- Map tokens onto Material's light scheme ---- */
+[data-md-color-scheme="default"] {
+  --md-default-bg-color:            var(--wp-bg);
+  --md-default-fg-color:            var(--wp-ink);
+  --md-default-fg-color--light:     var(--wp-ink-muted);
+  --md-default-fg-color--lighter:   var(--wp-ink-faint);
+  --md-default-fg-color--lightest:  var(--wp-rule);
+
+  --md-primary-fg-color:            var(--wp-bg);   /* header = paper, not a color bar */
+  --md-primary-fg-color--light:     var(--wp-bg);
+  --md-primary-fg-color--dark:      var(--wp-bg);
+  --md-primary-bg-color:            var(--wp-ink);  /* header text = ink */
+  --md-primary-bg-color--light:     var(--wp-ink-muted);
+
+  --md-accent-fg-color:             var(--wp-accent-ink);
+  --md-accent-fg-color--transparent: color-mix(in srgb, var(--wp-accent) 12%, transparent);
+
+  --md-typeset-color:               var(--wp-ink);
+  --md-typeset-a-color:             var(--wp-accent-ink);
+
+  --md-code-bg-color:               var(--wp-panel);
+  --md-code-fg-color:               var(--wp-ink);
+  --md-footer-bg-color:             var(--wp-surface);
+  --md-footer-bg-color--dark:       var(--wp-surface);
+  --md-footer-fg-color:             var(--wp-ink-muted);
+  --md-footer-fg-color--light:      var(--wp-ink-faint);
+
+  color-scheme: light;
+}
+
+/* ---- Header: paper with a hairline, no heavy bar ---- */
+.md-header {
+  color: var(--wp-ink);
+  border-bottom: 1px solid var(--wp-rule);
+  box-shadow: none;
+}
+.md-header--shadow { box-shadow: none; }
+.md-tabs {
+  background: var(--wp-bg);
+  color: var(--wp-ink);
+  border-bottom: 1px solid var(--wp-rule);
+}
+
+/* ---- Serif display for headings; tight, never heavy ---- */
+.md-typeset h1, .md-typeset h2, .md-typeset h3,
+.md-content__inner > h1, .md-nav__title {
+  font-family: var(--wp-serif);
+  letter-spacing: -.01em;
+  font-weight: 600;
+  color: var(--wp-ink);
+}
+.md-typeset h1 { font-weight: 600; }
+
+/* The page H1 gets a quiet accent hairline underneath — the single accent gesture */
+.md-typeset h1 {
+  padding-bottom: .35rem;
+  border-bottom: 1px solid var(--wp-rule);
+  position: relative;
+}
+.md-typeset h1::after {
+  content: ""; position: absolute; left: 0; bottom: -1px;
+  width: 2.2rem; height: 1px; background: var(--wp-accent);
+}
+
+/* ---- Links: accent-ink, underline on hover only ---- */
+.md-typeset a { color: var(--wp-accent-ink); text-decoration: none; }
+.md-typeset a:hover { text-decoration: underline; text-underline-offset: 3px; }
+
+/* ---- Code: quiet panel, hairline, no neon ---- */
+.md-typeset pre > code,
+.md-typeset .highlight { border-radius: 8px; }
+.md-typeset pre { border: 1px solid var(--wp-rule); border-radius: 8px; }
+.md-typeset code { background: var(--wp-panel); }
+
+/* ---- Tables & admonitions: hairlines, soft fills ---- */
+.md-typeset table:not([class]) {
+  border: 1px solid var(--wp-rule); border-radius: 8px; overflow: hidden;
+}
+.md-typeset table:not([class]) th {
+  background: var(--wp-panel); color: var(--wp-ink); font-weight: 600;
+}
+.md-typeset .admonition, .md-typeset details {
+  border: 1px solid var(--wp-rule); border-left-width: 2px;
+  border-left-color: var(--wp-accent); box-shadow: none; background: var(--wp-surface);
+}
+
+/* ---- Buttons / primary CTA ---- */
+.md-typeset .md-button--primary {
+  background: var(--wp-accent-ink); border-color: var(--wp-accent-ink); color: var(--wp-surface);
+}
+.md-typeset .md-button--primary:hover {
+  background: var(--wp-ink); border-color: var(--wp-ink);
+}
+
+/* ---- Search ---- */
+.md-search__form { background: var(--wp-surface); border: 1px solid var(--wp-rule); }
+.md-search__input::placeholder { color: var(--wp-ink-faint); }
+
+/* ---- Maker's mark: quiet "— amitpatole" signature in the footer ---- */
+.md-footer-meta { border-top: 1px solid var(--wp-rule); }
+.md-footer-meta__inner::after {
+  content: "— amitpatole";
+  font-family: var(--wp-serif); font-style: italic; font-size: .8rem;
+  color: var(--wp-accent-ink); margin-left: auto; padding: 0 .6rem;
+  align-self: center; white-space: nowrap;
+}
+
+/* ---- Tighten the overall feel ---- */
+.md-grid { max-width: 64rem; }      /* comfortable measure */
+.md-typeset { line-height: 1.62; }

babelagent-0.1.0/docs/SECURITY.md

@@ -0,0 +1,62 @@
+# Security posture
+
+Babelagent runs code and calls services you bring, and its REST/MCP interfaces accept untrusted input,
+so security is treated as part of "done." The current surface has been through a full audit and four
+adversarial red-team rounds (the last found nothing new). This page states what is hardened, how to
+deploy safely, and the residual risks no audit removes.
+
+## What is hardened
+
+**Network input (REST service, `babelagent[serve]`).**
+- Bearer-token auth compared in constant time (`hmac.compare_digest`). Zero-config on loopback;
+  **fail-closed** on any non-loopback bind without a token (`serve()` refuses to start).
+- Anti-DNS-rebind **Host-header pinning** on loopback binds (a browser cannot rebind `attacker.com`
+  to `127.0.0.1` and drive `/run`). Fails closed on a missing Host.
+- Request-body size cap enforced **before** buffering; a body-phase idle/slowloris timeout; a
+  concurrency semaphore; `limit_concurrency` + `timeout_keep_alive` on uvicorn.
+- Caller-supplied `deadline_s` is validated (finite, positive) and **clamped** to the server ceiling
+  (it can only lower the run budget, never raise it), backed by a hard wall-clock guillotine on the run.
+- Errors are sanitized: internal exception messages are redacted from the returned trace.
+
+**Outbound requests (HTTP / OpenAPI / A2A adapters).**
+- SSRF allowlist: only public global-unicast targets. Blocks loopback/private/link-local/reserved/
+  multicast/unspecified, and normalizes IPv4-mapped, IPv4-compatible, NAT64, 6to4, and Teredo IPv6
+  so an internal IPv4 cannot be smuggled through an IPv6 literal.
+- Redirects are never followed; the guard is re-run at connect time; upstream responses are streamed
+  with a size cap so a hostile agent cannot exhaust memory.
+- Secrets: API keys and tokens come only from the environment; never hard-coded, never serialized into
+  a topology or returned in a response.
+
+**Execution / resources.**
+- No `eval`/`exec`/`pickle`/`shell=True` on untrusted input. The OpenAPI path only reads a schema.
+- The scheduler bounds concurrency; response serialization is bounded by depth **and** a total-node
+  budget (so a wide or shared-reference structure cannot fan out to exponential work).
+- Untrusted upstream output cannot inject keyword/positional "flag" arguments into a callable node
+  (payload spreads into a callable only when it exactly matches the callable's required parameters).
+- Entry-point adapter discovery can be disabled with `BABELAGENT_NO_PLUGINS=1`.
+
+## Deploying safely
+
+- **Front a routable deployment with a reverse proxy** (nginx `client_header_timeout`, an ALB idle
+  timeout, etc.). uvicorn has no header-receive timeout, so a slow-headers Slowloris is only fully
+  mitigated by a fronting proxy. Always set a token (`BABELAGENT_API_TOKEN`) for non-loopback binds.
+- **Front untrusted outbound targets with an egress allowlist / proxy.** The SSRF guard blocks internal
+  targets, but a host under attacker DNS control can still rebind between validation and connect; an
+  egress allowlist closes that residual.
+- **Do not run untrusted, blocking, or CPU-bound *sync* callables on a shared server.** A blocked
+  worker thread cannot be force-killed (a Python limitation); use an async agent or an out-of-process
+  agent for such work.
+
+## Documented residuals (not eliminated by any audit)
+
+- A blocked/CPU-bound **sync** callable's worker thread cannot be interrupted; the run still reports the
+  timeout, but the thread lingers.
+- **DNS-rebinding** of an outbound target is not fully closed without an egress allowlist/proxy.
+- **Header-phase Slowloris** requires a fronting reverse proxy.
+- **Brought agents and entry-point plugins run code** by design; trust your dependency set and the
+  agents you plug in. LLM provider SDKs dial trusted first-party endpoints.
+- The usual unknowns: third-party dependencies and the kernel/OS.
+
+## Reporting
+
+This project is in local development. Once public, report vulnerabilities privately to the maintainer.