flightdeckdev · Gsbreddy · May 2, 2026 · May 2, 2026 · May 2, 2026
diff --git a/.cursorrules b/.cursorrules
@@ -1,6 +1,6 @@
 # FlightDeck — Cursor
 
-Read **`AGENTS.md`** for mission, non-goals, public contracts, engineering rules, verification, and docs policy. **`CLAUDE.md`** is a short index for Claude Code / Cursor. In Cursor, **`.cursor/rules/flightdeck-ci-artifacts.mdc`** (`alwaysApply`) reminds you to commit **`src/flightdeck/server/static/`** and **`schemas/`** when CI gates apply.
+Read **`AGENTS.md`** for mission, non-goals, public contracts, engineering rules, verification, and docs policy (including optional **`flightdeck.integrations`** boundaries). **`CLAUDE.md`** is a short index for Claude Code / Cursor. In Cursor, **`.cursor/rules/flightdeck-ci-artifacts.mdc`** (`alwaysApply`) reminds you to commit **`src/flightdeck/server/static/`** and **`schemas/`** when CI gates apply.
 
 Quick verify (uv): `uv sync --frozen --extra dev`, then `uv run python -m ruff check src tests`, `uv run python -m pytest`, `uv run flightdeck-quickstart-verify`, `uv run flightdeck --help` (pip/venv equivalents in **`DEVELOPMENT.md`**; on Windows, **`py -3`** if needed). After **Pydantic / wire model** edits: `uv run python scripts/generate_schemas.py` then `git diff --exit-code schemas/`. After **`web/`** edits that affect the production bundle: `cd web && npm ci && npm run build && cd .. && git diff --exit-code src/flightdeck/server/static/` (must be clean—commit all changes under **`static/`**); when UI behavior changes, `cd web && npx playwright install chromium && npm run test:e2e` (see **`web/README.md`**).
 

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -79,6 +79,32 @@ jobs:
       - name: CLI smoke
         run: uv run flightdeck --help
 
+  integrations:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.14"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Sync with integration extras
+        run: uv sync --frozen --extra dev --extra integrations-ci
+
+      - name: Lint
+        run: uv run python -m ruff check src tests
+
+      - name: Integration tests
+        run: uv run python -m pytest tests/test_integrations.py tests/test_integrations_langchain.py
+
   test-windows:
     runs-on: windows-latest
     strategy:

diff --git a/AGENTS.md b/AGENTS.md
@@ -25,12 +25,14 @@ Economic and operational safety for AI releases.
 Do not add:
 
 - prompt IDEs
-- agent frameworks
+- in-product **agent orchestration frameworks** (FlightDeck does not execute LangGraph/CrewAI-style graphs as core product behavior or become the default runtime for user workflows)
 - dashboards before CLI workflow is proven
 - gateways/proxies by default
 - compliance scanners
 - fine-tuning ops
-- broad plugin systems
+- **broad plugin systems** (no dynamic plugin registry, no implicit third-party load-by-name in core)
+
+**Allowed (adoption glue):** optional, explicitly declared **`[project.optional-dependencies]`** extras that install thin **`flightdeck.integrations.*`** helpers. Those modules only map third-party telemetry into **`RunEvent`** / HTTP ingest and strengthen **developer onboarding** and **runtime evidence**; they do not replace the CLI ledger or ship an embedded orchestrator.
 
 ## Public contracts
 
@@ -40,6 +42,7 @@ Treat these as **stable API** unless a change explicitly marks an experimental p
 - **On-disk / wire:** `release.yaml`, run events, pricing imports, policy shape — **`schemas/`** (generated; drift caught in CI) plus compatibility notes in **`RELEASE_NOTES.md`**.
 - **v1 / GA direction** (migrations, checksums, trust boundaries, defaults): **`RELEASE_NOTES.md`** and shipped CLI/schema behavior.
 - **Backlog and milestone status:** **`ROADMAP.md`**.
+- **Optional Python `flightdeck.integrations`:** SemVer-tracked but **experimental** until **`RELEASE_NOTES.md`** / **`CHANGELOG.md`** state otherwise. Not the same stability bar as CLI + **`RunEvent`** wire JSON unless explicitly promoted; prefer **`POST /v1/events`** and **`schemas/v1/run_event.schema.json`** as the normative integration surface.
 
 ## Engineering rules
 
@@ -95,7 +98,7 @@ Fallback (activated **venv** or global tools): the same steps with **`python -m
 
 On **Windows**, use `py -3` in place of `python` if that is how your environment is set up. If pytest temp dirs fail with permissions, see **`DEVELOPMENT.md`** / **`tests/conftest.py`**.
 
-**CI bar** (mirrors **`.github/workflows/ci.yml`** on **CPython 3.14**): see the workflow for the exact sequence; includes **`uv sync --frozen --extra dev`**, **`web/`** **`npm ci`** + **`npm run build`** + **`git diff --exit-code`** on **`static/`**, Playwright **`npm run test:e2e`**, **ruff**, **pytest**, schema drift check, **`flightdeck-quickstart-verify`**, **`flightdeck --help`**.
+**CI bar** (mirrors **`.github/workflows/ci.yml`** on **CPython 3.14**): see the workflow for the exact sequence; includes **`uv sync --frozen --extra dev`**, **`web/`** **`npm ci`** + **`npm run build`** + **`git diff --exit-code`** on **`static/`**, Playwright **`npm run test:e2e`**, **ruff**, **pytest**, schema drift check, **`flightdeck-quickstart-verify`**, **`flightdeck --help`**. When you change **`pyproject.toml`** optional extras (including **`flightdeck.integrations`** extras), run **`uv lock`** and commit **`uv.lock`**. The workflow may include a separate **integrations** job that **`uv sync`**s **`dev`** plus selected integration extras and runs targeted tests.
 
 Use a repo-local temp directory if the OS temp directory is restricted.
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,10 @@ This project follows [Semantic Versioning](https://semver.org/). From **v1.0.0**
 
 ## Unreleased
 
+### Added
+
+- **Experimental `flightdeck.integrations`:** optional extras **`integrations-langchain`**, **`integrations-temporal`**, **`integrations-openai-agents`**, and meta **`integrations-ci`** (CI job); thin mappers from OpenAI chat completions, Anthropic messages, OpenAI Agents–style results, LangChain callbacks, CrewAI-style manual totals, and Temporal-oriented **`labels`**. Docs: **`docs/sdk-integrations.md`**; examples: **`examples/integration/adoption/`**. Contributor policy updates in **`AGENTS.md`** / **`CLAUDE.md`**.
+
 ### Changed
 
 - **Web Runs:** forensics — empty / offset / truncation messaging, export copy, trace band rows or **Group by trace_id**, **View** drawer (structured fields + full JSON, **session_id** / **span_id**, focus trap + return focus, **`aria-haspopup="dialog"`**), trace/status columns; **run-query** failures show a typed error card with **Retry**.

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -9,6 +9,7 @@ Canonical repository (full history and maintainer workflows): **[github.com/flig
 | Topic | Location |
 |--------|------|
 | Agent / contributor rules | `AGENTS.md` |
+| Runtime integrations / adoption hooks (optional `flightdeck.integrations`, extras, boundaries) | `AGENTS.md` (non-goals), [docs/sdk-integrations.md](docs/sdk-integrations.md), `src/flightdeck/integrations/`, [examples/integration/adoption/](examples/integration/adoption/) |
 | Cursor IDE rules (CI artifacts, web static) | `.cursor/rules/flightdeck-ci-artifacts.mdc` |
 | Setup and local demo | `DEVELOPMENT.md` |
 | CLI flags and exit codes | [README.md](https://github.com/flightdeckdev/flightdeck/blob/main/README.md) (canonical repo) |
@@ -35,6 +36,8 @@ If you changed **Pydantic / wire models** affecting **`schemas/`**: **`uv run py
 
 If you changed **`web/`** (React UI): from **`web/`**, run **`npm ci`** then **`npm run build`**, then from the repo root **`git diff --exit-code src/flightdeck/server/static/`** must be clean—commit all updates under that path (CI fails otherwise). When behavior changes, run **`npm run test:e2e`** from **`web/`**.
 
+If you changed **`pyproject.toml`** integration extras or **`src/flightdeck/integrations/`** tests: run **`uv lock`**, commit **`uv.lock`**, and **`uv sync --frozen --extra dev --extra integrations-ci`** (see **`DEVELOPMENT.md`**) to match the CI integrations job.
+
 Details: **`AGENTS.md`** (Verification), **`DEVELOPMENT.md`**, and **`.cursor/rules/flightdeck-ci-artifacts.mdc`**.
 
 With **pip** + venv: use **`python -m …`** equivalents in **`DEVELOPMENT.md`**.
@@ -43,4 +46,4 @@ With **pip** + venv: use **`python -m …`** equivalents in **`DEVELOPMENT.md`**
 
 ## Repo shape
 
-Python package under `src/flightdeck/`. Tests in `tests/`. Examples in `examples/quickstart/`. JSON Schemas under `schemas/` (regenerate with **`uv run python scripts/generate_schemas.py`** when models change). Browser UI source in **`web/`**; production bundle committed under **`src/flightdeck/server/static/`** (rebuild with **`npm run build`** in **`web/`**). After **`pyproject.toml`** dependency edits, run **`uv lock`** and commit **`uv.lock`**.
+Python package under `src/flightdeck/` (optional **`flightdeck.integrations`** under the same tree). Tests in `tests/`. Examples in `examples/quickstart/` and **`examples/integration/adoption/`**. JSON Schemas under `schemas/` (regenerate with **`uv run python scripts/generate_schemas.py`** when models change). Browser UI source in **`web/`**; production bundle committed under **`src/flightdeck/server/static/`** (rebuild with **`npm run build`** in **`web/`**). After **`pyproject.toml`** dependency edits, run **`uv lock`** and commit **`uv.lock`**.
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -18,9 +18,10 @@ uv sync --extra dev
 
 This creates **`.venv/`** (gitignored), installs **`flightdeck`** editable plus **pytest** and **ruff**, and pins versions from **`uv.lock`**.
 
-Optional extras (telemetry, SDK helpers, PostgreSQL driver): e.g.
-**`uv sync --extra dev --extra telemetry`** or **`uv sync --extra dev --extra postgres`**
-for **`database_url`** / optional **`tests/test_storage_postgres.py`** runs (**`FLIGHTDECK_TEST_POSTGRES_URL`**).
+Optional extras (telemetry, SDK helpers, PostgreSQL driver, integration test deps): e.g.
+**`uv sync --extra dev --extra telemetry`**, **`uv sync --extra dev --extra postgres`**, or
+**`uv sync --extra dev --extra integrations-ci`** (LangChain / Temporal / OpenAI Agents for
+**`tests/test_integrations_langchain.py`** and the same lock resolution CI job uses).
 Local driver test helper (Docker optional): **`scripts/run_postgres_tests.ps1`** (see script header).
 
 ### Package extras
@@ -32,9 +33,15 @@ Local driver test helper (Docker optional): **`scripts/run_postgres_tests.ps1`**
 | `anthropic` | `anthropic>=0.20` | Same, for the Anthropic Python client |
 | `telemetry` | `opentelemetry-api`, `-sdk`, `-exporter-otlp` | Forward-looking OTLP integration; FlightDeck core does **not** import OpenTelemetry at runtime |
 | `all` | `openai` + `anthropic` + `telemetry` | All optional packages in one shot |
+| `integrations-langchain` | `langchain-core` | Optional **`FlightDeckLangChainCallbackHandler`** (see **`docs/sdk-integrations.md`**) |
+| `integrations-temporal` | `temporalio` | Optional worker-side typing helpers; core does not import Temporal |
+| `integrations-openai-agents` | `openai-agents` | Optional mapping from Agents SDK run results |
+| `integrations-ci` | `langchain-core` + `temporalio` + `openai-agents` | CI / local parity for integration tests (**`uv lock`** resolves this group) |
 
 FlightDeck's core package (`flightdeck-ai`) does not import OpenAI, Anthropic, or OpenTelemetry at runtime. These extras exist so your project can declare a single dependency (`flightdeck-ai[openai]`) and get a compatible version of both without resolving conflicts manually.
 
+**`flightdeck.integrations`** (experimental — see **`AGENTS.md`** and **`docs/sdk-integrations.md`**) ships thin mappers behind the **`integrations-*`** extras above. There is **no** declared **`crewai`** extra: install CrewAI in your own environment if you use **`crewai_bridge`**, to avoid pulling a very large dependency tree into **`uv.lock`**.
+
 **Note on listed core dependencies:** `pyproject.toml` currently lists `sqlalchemy`, `aiosqlite`, and `rich` as direct (non-optional) dependencies, but `src/flightdeck/` does not import any of them — the package uses the standard-library `sqlite3` module and plain `click` output. These entries are carried over from earlier prototypes and are scheduled for removal in a future cleanup release.
 
 ## Setup (pip — fallback)

diff --git a/README.md b/README.md
@@ -148,13 +148,14 @@ flightdeck release history --agent agent_support --env local
 The static event files in `examples/quickstart` use placeholder release IDs so the repo can ship stable examples.
 Substitute them before ingestion, or run **`uv run flightdeck-quickstart-verify`** / **`python -m flightdeck.quickstart_smoke`** (venv) or **`./scripts/smoke.sh`** from Git Bash/WSL on Windows.
 
-**Examples:** [examples/quickstart/](examples/quickstart/) · [examples/ci/](examples/ci/) (policy gate + Actions) · [examples/deploy/](examples/deploy/) (`serve` via Docker/Compose) · [examples/integration/](examples/integration/) (HTTP event emitter).
+**Examples:** [examples/quickstart/](examples/quickstart/) · [examples/ci/](examples/ci/) (policy gate + Actions) · [examples/deploy/](examples/deploy/) (`serve` via Docker/Compose) · [examples/integration/](examples/integration/) (HTTP event emitter) · [examples/integration/adoption/](examples/integration/adoption/) (framework hooks).
 
 ## Documentation
 
 - [CLI reference](docs/cli.md) — all commands, flags, arguments, and exit codes
 - [HTTP API reference](docs/http-api.md) — all `/v1/*` routes, request/response shapes, auth, `RunEvent` field reference
 - [Python SDK](docs/sdk.md) — `FlightdeckClient` / `AsyncFlightdeckClient` usage guide
+- [Runtime integrations (experimental)](docs/sdk-integrations.md) — optional `flightdeck.integrations` mappers (LangChain, OpenAI Agents, Temporal, etc.)
 - [Operations and policy](docs/operations-and-policy.md) — diff, promote, rollback internals; policy model and confidence tiers
 - [Release artifacts and pricing](docs/release-artifact.md) — `release.yaml` format, bundle layout, checksum algorithm, workspace config, pricing tables
 - [Pricing catalog](docs/pricing-catalog.md) — optional `pricing_catalog_path`, catalog vs imported tables, troubleshooting

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -4,6 +4,15 @@ High-level notes for **shipping FlightDeck**. Detailed history: **[CHANGELOG.md]
 
 Narrative docs (including the CLI reference) are maintained on **[github.com/flightdeckdev/flightdeck](https://github.com/flightdeckdev/flightdeck)** `main`; this file and **`schemas/`** ship in minimal clones.
 
+## Upcoming — Optional Python integrations (experimental)
+
+Patch-line documentation: optional **`flightdeck.integrations`** mappers behind **`integrations-*`**
+extras (see **`pyproject.toml`**, **`docs/sdk-integrations.md`**, **`examples/integration/adoption/`**).
+**Stable contracts unchanged:** **`RunEvent`** JSON / **`POST /v1/events`**. **`AGENTS.md`** clarifies
+that these adapters are adoption glue, not in-product orchestration or a plugin registry. CI adds
+an **`integrations`** job (**`uv sync --frozen --extra dev --extra integrations-ci`**) for LangChain
+callback coverage.
+
 ## v1.1.2 — Forensics filters, JSONL export, productization closure slice
 
 Patch release (see **[CHANGELOG.md](CHANGELOG.md)**): optional **`trace_id`** filter on **`GET /v1/runs`**, **`flightdeck runs list --trace-id`**, and SDK **`list_runs(trace_id=…)`** (exact match on **`RunEvent.request.trace_id`**); **`flightdeck runs export`** writes the same filtered slice as JSONL (stdout or **`-o`**, **`--limit`** up to **500**, stderr warning when truncated). **Stable contracts:** additive HTTP query param and CLI command only.

diff --git a/docs/sdk-integrations.md b/docs/sdk-integrations.md
@@ -0,0 +1,45 @@
+# FlightDeck runtime integrations (experimental)
+
+Optional Python helpers under **`flightdeck.integrations`** map third-party LLM and workflow
+telemetry into **`RunEvent`** models for **`FlightdeckClient.ingest_run_events`** or JSONL ingest.
+They strengthen **developer onboarding** and **runtime evidence**; they are **not** a second
+product surface for orchestration.
+
+## Stability and contracts
+
+- **Normative wire shape:** **`schemas/v1/run_event.schema.json`** and **`POST /v1/events`**
+  (same as **`flightdeck runs ingest`**). Treat the HTTP payload as the stable contract.
+- **`flightdeck.integrations`:** SemVer-tracked but **experimental** until **`RELEASE_NOTES.md`**
+  / **`CHANGELOG.md`** state otherwise. Helpers may change between minor releases as upstream SDKs
+  evolve; pin **`flightdeck-ai`** if you depend on a specific mapper.
+- **Core import rule:** **`import flightdeck`** does **not** install or import LangChain, Temporal,
+  OpenAI Agents, etc. Import only the submodule you need (for example
+  **`flightdeck.integrations.openai_chat`**) after installing the matching extra.
+
+## Extras (see **`pyproject.toml`**)
+
+| Extra | Purpose |
+|-------|---------|
+| **`openai`** | OpenAI Python client alongside FlightDeck (also used by examples) |
+| **`anthropic`** | Anthropic Python client alongside FlightDeck |
+| **`integrations-langchain`** | **`FlightDeckLangChainCallbackHandler`** in **`langchain_callback.py`** |
+| **`integrations-temporal`** | Install **`temporalio`** next to FlightDeck when your worker shares a venv |
+| **`integrations-openai-agents`** | **`openai-agents`** for result-shape experiments |
+| **`integrations-ci`** | Meta-extra for CI: LangChain + Temporal + OpenAI Agents resolution |
+
+There is **no** **`crewai`** extra on the distribution. Use **`crewai_bridge.run_event_from_crew_token_totals`**
+with totals you collect from CrewAI (or install **`crewai`** only in your application environment).
+
+## Trust boundaries
+
+Anyone who can reach **`POST /v1/events`** can append ledger rows. Keep **`flightdeck serve`**
+on loopback or a private network unless you add your own controls. See **[SECURITY.md](../SECURITY.md)**.
+
+## Examples
+
+Copy-paste scripts: **[examples/integration/adoption/](../examples/integration/adoption/README.md)**.
+
+## Policy boundary (contributors)
+
+Contributor rules in **`AGENTS.md`** distinguish **in-product agent frameworks** (non-goals) from
+these **narrow, opt-in adoption adapters**. Do not add a dynamic plugin registry.
diff --git a/docs/sdk.md b/docs/sdk.md
@@ -18,6 +18,10 @@ pip install 'flightdeck-ai'
 uv add flightdeck-ai
 ```
 
+Optional **LangChain / Temporal / OpenAI Agents** mappers ship under **`flightdeck.integrations`**
+(experimental; separate extras). See **[sdk-integrations.md](sdk-integrations.md)** and
+**[examples/integration/adoption/](../examples/integration/adoption/README.md)**.
+
 ## Quick start
 
 ```python