dome-langchain 0.1.0__tar.gz

dome_langchain-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.coverage
+coverage.xml
+coverage.html
+htmlcov/
+.pytest_cache/
+
+# Type checking
+.mypy_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+.env.*.local
+.dome-demo.env
+
+# Claude
+.claude/settings.local.json
+
+# Build artifacts
+tmp/

dome_langchain-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: dome-langchain
+Version: 0.1.0
+Summary: Dome Platform LangChain adapter — govern LangChain tools with Dome authorization
+Project-URL: Homepage, https://domesystems.ai
+Project-URL: Documentation, https://docs.domesystems.ai
+Project-URL: Repository, https://github.com/dome-systems/sdk-dome-python
+Project-URL: Issues, https://github.com/dome-systems/sdk-dome-python/issues
+Author-email: Dome Systems <eng@domesystems.ai>
+License: Proprietary
+Keywords: agent-governance,ai-agents,authorization,dome,langchain,langgraph,llm,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: dome-sdk>=0.1.0
+Requires-Dist: langchain-core>=0.3
+Provides-Extra: anthropic
+Requires-Dist: langchain-anthropic>=0.2; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: langchain-anthropic>=0.2; extra == 'dev'
+Requires-Dist: langchain-openai>=0.2; extra == 'dev'
+Requires-Dist: langgraph>=0.2; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2; extra == 'langgraph'
+Provides-Extra: openai
+Requires-Dist: langchain-openai>=0.2; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# Dome LangChain Adapter
+
+LangChain / LangGraph integration for the [Dome Platform](https://domesystems.ai).
+It injects Dome **identity** and **authorization** into the seams of an
+existing LangChain app — it is *additive*, not a replacement for LangChain.
+
+There are three surfaces, each opt-in:
+
+| Surface | What it governs | Key symbols |
+|---------|-----------------|-------------|
+| Governed tools | tool calls | `DomeGovernedTool`, `govern_tools` |
+| Governed chat models | LLM calls | `DomeChatOpenAI`, `DomeChatAnthropic`, `broker_chat`, `broker_chat_for` |
+| Compose primitives | agent-to-agent handoffs & spawned fleets | `Gate`, `gate_edge`, `gate_command`, `session`, `mint_ephemeral`, `fleet_send`, `causal` |
+
+## Install
+
+```bash
+pip install dome-langchain                 # core adapter: tools + gates + spawn
+pip install 'dome-langchain[openai]'       # + DomeChatOpenAI (langchain-openai)
+pip install 'dome-langchain[anthropic]'    # + DomeChatAnthropic (langchain-anthropic)
+pip install 'dome-langchain[langgraph]'    # + the LangGraph shims
+```
+
+The core install needs only `langchain-core`. The chat-model surfaces pull in a
+provider client; importing `DomeChatOpenAI` / `DomeChatAnthropic` without the
+matching extra raises an `ImportError` with the install hint.
+
+## 1. Governed tools
+
+`DomeGovernedTool` wraps any LangChain `BaseTool`. Before each execution it
+calls `dome.DomeClient.check()`; on deny it returns a denial message instead of
+running, and audit events are emitted automatically.
+
+```python
+import dome
+from dome_langchain import DomeGovernedTool, govern_tools
+
+client = dome.DomeClient(dome.DomeConfig(base_url="https://api.domesystems.ai", token="dome_..."))
+client.start()
+
+governed = DomeGovernedTool(tool=search_tool, dome_client=client)
+# or wrap several at once:
+tools = govern_tools(client, [search_tool, db_tool, email_tool])
+
+client.close()
+```
+
+## 2. Governed chat models
+
+`DomeChatOpenAI` (the name mirrors its `ChatOpenAI` base; the older name
+`DomeChatModel` still works as an alias) is a `ChatOpenAI` subclass whose
+requests flow through the Dome Broker (the LLM gateway) under a specific
+agent's identity. The Broker
+authenticates the call as that agent, evaluates Cedar for the model action,
+audits it, then forwards to the upstream provider. Because it *is* a
+`ChatOpenAI`, streaming, tool-calling, and structured output work unchanged.
+
+```python
+from dome_langchain import AgentIdentity, DomeChatOpenAI
+
+# `for_agent` accepts any agent identity (anything with `token` +
+# `gateway_endpoint`) — an `EphemeralAgent` from the spawn API, or an
+# `AgentIdentity` for an ordinary long-lived agent:
+llm = DomeChatOpenAI.for_agent(
+    AgentIdentity(token="dome_...", gateway_endpoint="https://gw.example.com")
+)
+llm.invoke("Summarise this ticket.")          # called as that agent
+
+# End-user delegation (act-as) — per call, or bound once:
+llm.invoke("Summarise this ticket.", act_as=user)   # ActAs or OIDC-JWT string
+per_user = llm.with_act_as(user)
+per_user.invoke("Summarise this ticket.")
+```
+
+`act_as` is encoded into an `X-Dome-Act-As` header on that request only; the
+Broker exposes it to Cedar as `principal.act_as` and does not forward it
+upstream. `broker_chat` / `broker_chat_for` are factory shims that return a
+`DomeChatOpenAI` (with a construction-time act-as default).
+
+For Claude-native features (prompt caching, extended thinking, citations) use
+the Anthropic ingress instead:
+
+```python
+from dome_langchain import DomeChatAnthropic
+llm = DomeChatAnthropic.for_agent(agent, model="claude-haiku-4-5")
+```
+
+## 3. Compose primitives (chains & spawn)
+
+### Gated handoffs
+
+A `Gate` turns a Dome authorization check into a routing decision. `gate_edge`
+adapts it to a LangGraph conditional edge (`(state) -> next_node`); `gate_command`
+is the newer node-returns-`Command` idiom. `Gate` is also a `Runnable` **guard**:
+in an LCEL chain, `gate | next` forwards the payload on allow and raises
+`GateDenied` on deny. (Use `gate.evaluate()` when you want the `GateDecision`
+value instead.)
+
+> **What a gate checks — and what it doesn't.** A gate evaluates Cedar with the
+> agent backing `dome_client` (typically the orchestrator/parent) as the
+> **principal** — *not* the downstream node. The `from_node`/`to_node` labels
+> and any extra context are **application-asserted, not verified**: a gate is a
+> client-side routing decision, not a cryptographic boundary, so it governs hops
+> only insofar as your nodes assert that context honestly. Verified call-chain
+> identity is a planned platform feature (S.PRP.008).
+
+```python
+from dome_langchain import gate_edge
+
+g.add_conditional_edges(
+    "classifier",
+    gate_edge(dome_client=client, from_node="classifier",
+              to_node="retriever", resource="chain.hop_allowed"),
+    {"retriever": "retriever"},
+)
+```
+
+On allow the hop proceeds; on deny it routes to an `on_deny` node or raises
+`GateDenied`.
+
+### Spawned ephemeral fleets
+
+`session` + `mint_ephemeral` register real, short-lived child agents (each with
+its own Dome identity and token) and tear them down on exit. `fleet_send` fans
+them out across a LangGraph node via `Send`.
+
+```python
+from dome_langchain import session, fleet_send, DomeChatOpenAI
+
+with session(platform, parent_agent_id=parent.agent_id, gateway_endpoint=gw) as s:
+    fleet = s.spawn(count=4, template="researcher")
+    sends = fleet_send(node="research", fleet=fleet,
+                       payload_fn=lambda agent, i: {"agent": agent, "task": tasks[i]})
+    # inside the "research" node, each worker calls the LLM as itself:
+    #   llm = DomeChatOpenAI.for_agent(state["agent"])
+# session exit revokes + hard-deletes the whole fleet
+```
+
+`mint_ephemeral` / `session` require a `dome.DomeAdminClient` (a workspace-admin
+client), not the per-agent `DomeClient`.
+
+## Examples
+
+Runnable end-to-end demos live in [`examples/`](./examples) (chain, spawn,
+broker). They require a provisioned Dome workspace — see
+[`examples/README.md`](./examples/README.md).
+
+## Documentation
+
+- [Dome Platform Docs](https://docs.domesystems.ai)
+- [Core Python SDK](https://github.com/dome-systems/sdk-dome-python)
+
+## License
+
+Proprietary. See LICENSE for details.

dome_langchain-0.1.0/README.md

@@ -0,0 +1,155 @@
+# Dome LangChain Adapter
+
+LangChain / LangGraph integration for the [Dome Platform](https://domesystems.ai).
+It injects Dome **identity** and **authorization** into the seams of an
+existing LangChain app — it is *additive*, not a replacement for LangChain.
+
+There are three surfaces, each opt-in:
+
+| Surface | What it governs | Key symbols |
+|---------|-----------------|-------------|
+| Governed tools | tool calls | `DomeGovernedTool`, `govern_tools` |
+| Governed chat models | LLM calls | `DomeChatOpenAI`, `DomeChatAnthropic`, `broker_chat`, `broker_chat_for` |
+| Compose primitives | agent-to-agent handoffs & spawned fleets | `Gate`, `gate_edge`, `gate_command`, `session`, `mint_ephemeral`, `fleet_send`, `causal` |
+
+## Install
+
+```bash
+pip install dome-langchain                 # core adapter: tools + gates + spawn
+pip install 'dome-langchain[openai]'       # + DomeChatOpenAI (langchain-openai)
+pip install 'dome-langchain[anthropic]'    # + DomeChatAnthropic (langchain-anthropic)
+pip install 'dome-langchain[langgraph]'    # + the LangGraph shims
+```
+
+The core install needs only `langchain-core`. The chat-model surfaces pull in a
+provider client; importing `DomeChatOpenAI` / `DomeChatAnthropic` without the
+matching extra raises an `ImportError` with the install hint.
+
+## 1. Governed tools
+
+`DomeGovernedTool` wraps any LangChain `BaseTool`. Before each execution it
+calls `dome.DomeClient.check()`; on deny it returns a denial message instead of
+running, and audit events are emitted automatically.
+
+```python
+import dome
+from dome_langchain import DomeGovernedTool, govern_tools
+
+client = dome.DomeClient(dome.DomeConfig(base_url="https://api.domesystems.ai", token="dome_..."))
+client.start()
+
+governed = DomeGovernedTool(tool=search_tool, dome_client=client)
+# or wrap several at once:
+tools = govern_tools(client, [search_tool, db_tool, email_tool])
+
+client.close()
+```
+
+## 2. Governed chat models
+
+`DomeChatOpenAI` (the name mirrors its `ChatOpenAI` base; the older name
+`DomeChatModel` still works as an alias) is a `ChatOpenAI` subclass whose
+requests flow through the Dome Broker (the LLM gateway) under a specific
+agent's identity. The Broker
+authenticates the call as that agent, evaluates Cedar for the model action,
+audits it, then forwards to the upstream provider. Because it *is* a
+`ChatOpenAI`, streaming, tool-calling, and structured output work unchanged.
+
+```python
+from dome_langchain import AgentIdentity, DomeChatOpenAI
+
+# `for_agent` accepts any agent identity (anything with `token` +
+# `gateway_endpoint`) — an `EphemeralAgent` from the spawn API, or an
+# `AgentIdentity` for an ordinary long-lived agent:
+llm = DomeChatOpenAI.for_agent(
+    AgentIdentity(token="dome_...", gateway_endpoint="https://gw.example.com")
+)
+llm.invoke("Summarise this ticket.")          # called as that agent
+
+# End-user delegation (act-as) — per call, or bound once:
+llm.invoke("Summarise this ticket.", act_as=user)   # ActAs or OIDC-JWT string
+per_user = llm.with_act_as(user)
+per_user.invoke("Summarise this ticket.")
+```
+
+`act_as` is encoded into an `X-Dome-Act-As` header on that request only; the
+Broker exposes it to Cedar as `principal.act_as` and does not forward it
+upstream. `broker_chat` / `broker_chat_for` are factory shims that return a
+`DomeChatOpenAI` (with a construction-time act-as default).
+
+For Claude-native features (prompt caching, extended thinking, citations) use
+the Anthropic ingress instead:
+
+```python
+from dome_langchain import DomeChatAnthropic
+llm = DomeChatAnthropic.for_agent(agent, model="claude-haiku-4-5")
+```
+
+## 3. Compose primitives (chains & spawn)
+
+### Gated handoffs
+
+A `Gate` turns a Dome authorization check into a routing decision. `gate_edge`
+adapts it to a LangGraph conditional edge (`(state) -> next_node`); `gate_command`
+is the newer node-returns-`Command` idiom. `Gate` is also a `Runnable` **guard**:
+in an LCEL chain, `gate | next` forwards the payload on allow and raises
+`GateDenied` on deny. (Use `gate.evaluate()` when you want the `GateDecision`
+value instead.)
+
+> **What a gate checks — and what it doesn't.** A gate evaluates Cedar with the
+> agent backing `dome_client` (typically the orchestrator/parent) as the
+> **principal** — *not* the downstream node. The `from_node`/`to_node` labels
+> and any extra context are **application-asserted, not verified**: a gate is a
+> client-side routing decision, not a cryptographic boundary, so it governs hops
+> only insofar as your nodes assert that context honestly. Verified call-chain
+> identity is a planned platform feature (S.PRP.008).
+
+```python
+from dome_langchain import gate_edge
+
+g.add_conditional_edges(
+    "classifier",
+    gate_edge(dome_client=client, from_node="classifier",
+              to_node="retriever", resource="chain.hop_allowed"),
+    {"retriever": "retriever"},
+)
+```
+
+On allow the hop proceeds; on deny it routes to an `on_deny` node or raises
+`GateDenied`.
+
+### Spawned ephemeral fleets
+
+`session` + `mint_ephemeral` register real, short-lived child agents (each with
+its own Dome identity and token) and tear them down on exit. `fleet_send` fans
+them out across a LangGraph node via `Send`.
+
+```python
+from dome_langchain import session, fleet_send, DomeChatOpenAI
+
+with session(platform, parent_agent_id=parent.agent_id, gateway_endpoint=gw) as s:
+    fleet = s.spawn(count=4, template="researcher")
+    sends = fleet_send(node="research", fleet=fleet,
+                       payload_fn=lambda agent, i: {"agent": agent, "task": tasks[i]})
+    # inside the "research" node, each worker calls the LLM as itself:
+    #   llm = DomeChatOpenAI.for_agent(state["agent"])
+# session exit revokes + hard-deletes the whole fleet
+```
+
+`mint_ephemeral` / `session` require a `dome.DomeAdminClient` (a workspace-admin
+client), not the per-agent `DomeClient`.
+
+## Examples
+
+Runnable end-to-end demos live in [`examples/`](./examples) (chain, spawn,
+broker). They require a provisioned Dome workspace — see
+[`examples/README.md`](./examples/README.md).
+
+## Documentation
+
+- [Dome Platform Docs](https://docs.domesystems.ai)
+- [Core Python SDK](https://github.com/dome-systems/sdk-dome-python)
+
+## License
+
+Proprietary. See LICENSE for details.

dome_langchain-0.1.0/examples/README.md

@@ -0,0 +1,231 @@
+# dome-langchain end-to-end demos
+
+Runnable demos that show LangChain + Dome composing real multi-agent topologies against a live workspace. Each demo registers agents in Dome, runs them through the Broker for real LLM calls (Anthropic via OpenAI-compatible ingress), evaluates Cedar at every chain hop and every model call, and tears the agents down on exit.
+
+Two patterns are demonstrated:
+
+- **Chain** (`chain_e2e.py`) — three sequential agents with a Dome-evaluated gate between every hop.
+- **Spawn** (`spawn_e2e.py`) — a parent agent mints N ephemeral children at runtime and fans work out via LangGraph `Send`.
+
+Both run against staging (`api.staging.domesystems.ai`) by default and use the SDK Demo workspace.
+
+## Prerequisites
+
+| Need | Why |
+|---|---|
+| Access to the SDK Demo workspace on staging | Where the agents register, the Cedar bundle lands, and the Broker routes |
+| A workspace platform API key (`dome_pk_...`) with the permissions in step 2 | Bootstrap and the demos use this to provision children, deploy rules, and configure the Broker |
+| The workspace's UUID | Required in every Connect RPC body (see step 3 for how to find it) |
+| `ANTHROPIC_API_KEY` in your shell | Bootstrap writes it into the workspace's Broker (server-side Vault); the SDK never reads it back |
+| Python 3.13 + `uv` | The repo's tooling |
+
+## 1 · Install (one-time)
+
+From the SDK repo root:
+
+```sh
+uv venv --python 3.13 .venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+uv pip install -e "packages/dome-langchain[dev]"
+```
+
+## 2 · Create a workspace platform API key
+
+In the staging dashboard, generate a workspace-scoped platform API key (`dome_pk_...`) with these permissions:
+
+- `workspace:agent:register`
+- `workspace:agent:revoke`
+- `workspace:agent:delete`
+- `workspace:agent:key:manage`
+- `workspace:rules:deploy`
+- `workspace:gateway:manage`
+
+Copy the secret — staging only shows it once.
+
+## 3 · Find the workspace UUID
+
+The dashboard URL may use a slug rather than the UUID, in which case:
+
+1. Open DevTools → Network tab.
+2. Click anything in the SDK Demo workspace that loads data (Agents, Audit, anything).
+3. Click any request to `api.staging.domesystems.ai`, inspect the request payload — `workspaceId` will be present. Copy it.
+
+## 4 · Set environment variables
+
+```sh
+export DOME_BASE_URL=https://api.staging.domesystems.ai
+export DOME_DASHBOARD_URL=https://app.staging.domesystems.ai
+export DOME_PLATFORM_KEY=dome_pk_...        # from step 2
+export DOME_WORKSPACE_ID=<uuid>             # from step 3
+# ANTHROPIC_API_KEY already in your shell — used by bootstrap only
+```
+
+## 5 · Provision the workspace
+
+```sh
+cd packages/dome-langchain/examples
+./bootstrap.sh provision
+```
+
+Idempotent — re-running is safe. The script:
+
+1. Registers `sdk-demo-parent` (the audit-hierarchy root for everything).
+2. Issues / rotates its API key.
+3. Creates an Anthropic LLM connection in the Broker (your `ANTHROPIC_API_KEY` is stored server-side in Vault).
+4. Creates the default LLM pool and binds the Anthropic connection to it.
+5. Deploys a workspace-scoped Cedar bundle containing the chain gate rule.
+
+State is written to `.dome-demo.env` at the package root; the demos source it automatically.
+
+Sanity-check what landed:
+
+```sh
+./bootstrap.sh status
+```
+
+## 6 · Run the chain demo
+
+```sh
+python chain_e2e.py                                           # happy path
+python chain_e2e.py --deny                                    # context-driven deny
+python chain_e2e.py --act-as alice@example.com                # attach end-user identity
+python chain_e2e.py --act-as alice@deny.example.com           # identity-driven deny
+python chain_e2e.py --act-as alice@deny.example.com --act-as-roles admin
+python chain_e2e.py --keep                                    # skip teardown
+```
+
+What happens, observable in the terminal and the dashboard:
+
+| Step | Terminal | Dashboard |
+|---|---|---|
+| Three children register | `agents registered:` with three UUIDs | Three new agents appear under `sdk-demo-parent` |
+| Wait for gateway sync | `mint_ephemeral: waiting up to 20.0s for gateway sync` | (nothing — internal poll on `/v1/models`) |
+| Classify | `[classifier] <output>` | `llm.called` event attributed to the classifier agent |
+| Gate hop 1 | (no error means allowed) | `tool.called`, `action=chain:gate`, `from_node=classifier` |
+| Retrieve | `[retriever] <output>` | `llm.called` attributed to the retriever agent |
+| Gate hop 2 | (no error → allowed; `--deny` → `[CHAIN HALTED]`) | `tool.called` or `tool.denied` |
+| Summarize (skipped on `--deny`) | `[summarizer] <output>` | `llm.called` attributed to the summarizer agent |
+| Teardown | `tore down: revoked=3 deleted=3` | The three agents disappear |
+
+### End-user identity (`--act-as`)
+
+`--act-as <email>` attaches an end-user identity to every gate evaluation and every LLM call as `X-Dome-Act-As`. Cedar sees it as `principal.act_as.email` / `.roles` / `.groups` during evaluation, so policies can gate on *who the agent is acting for*, not just which agent is calling.
+
+The deployed Cedar bundle ships with one identity-keyed rule:
+
+```cedar
+forbid (
+    principal,
+    action == Dome::Action::"chain:gate",
+    resource
+) when {
+    principal has act_as
+    && principal.act_as has email
+    && principal.act_as.email like "*@deny.example.com"
+};
+```
+
+So:
+
+| Command | Outcome |
+|---|---|
+| `chain_e2e.py --act-as alice@example.com` | All gates allow; X-Dome-Act-As decorated audit events |
+| `chain_e2e.py --act-as alice@deny.example.com` | First gate denies; `[CHAIN HALTED]`; one `tool.denied` event with act-as attached |
+| `chain_e2e.py --act-as alice@example.com --act-as-roles admin,billing` | Roles flow through; visible in Cedar context and audit |
+
+The demo uses `method=none` act-as (plaintext base64-JSON). For production, switch the workspace's act-as policy to `method=oidc` and pass a verified OIDC JWT instead of an `ActAs` instance — the SDK accepts both. See the security section below.
+
+**One subtlety the platform enforces and you should know about**: the Broker explicitly does *not* propagate `X-Dome-Act-As` to the upstream LLM provider (`internal/gateway/egress/llm/headers.go`). Anthropic never sees the user identity. The header is only used for Dome's own Cedar evaluation of the model call. That's the intentional contract — per-user identity isn't part of the LLM provider's interface.
+
+## 7 · Run the spawn demo
+
+```sh
+python spawn_e2e.py --count 4
+python spawn_e2e.py --count 8 --topic "..."
+python spawn_e2e.py --keep
+```
+
+What happens:
+
+| Step | Terminal | Dashboard |
+|---|---|---|
+| Mint N ephemeral researchers | `spawned 4 researchers: <ids>` | Four new agents under `sdk-demo-parent`, each with `template=researcher` and `spawn_run_id=<id>` in metadata |
+| Gateway sync wait | `waiting up to 20.0s for gateway sync` | — |
+| Fan-out via LangGraph `Send` | Four `[<agent-id>] <output>` lines, interleaved | Four parallel `llm.called` events |
+| Aggregate findings | `[1] …  [2] …` etc. | — |
+| Teardown | `tore down: revoked=4 deleted=4` | All four agents disappear |
+
+## 8 · Reset (when you're done)
+
+```sh
+./bootstrap.sh reset
+```
+
+Revokes + hard-deletes every demo agent, deactivates the Cedar bundle, removes `.dome-demo.env`. The Broker connection + pool are left in place (workspace-level state you don't want to churn between runs).
+
+## Gateway sync window
+
+Newly-registered agents become callable on the workspace gateway **after the gateway's next sync tick**, not instantly. Default sync interval is **10 seconds**. During that window any gateway request from the new agent — `/v1/chat/completions`, `/v1/models`, anything — returns:
+
+```
+HTTP 403  agent act-as configuration unavailable
+```
+
+This is fail-closed behaviour by design (`internal/authorization/actas/middleware.go:65`). `mint_ephemeral` handles this transparently: after registering and issuing keys, it polls `GET /v1/models` (Cedar-filtered model listing, same auth path as the LLM call, no LLM tokens spent) until the gateway returns 200. Default timeout is 20s. Pass `wait_for_gateway_ready=False` to manage the wait yourself.
+
+You'll see this log line on every spawn:
+
+```
+INFO dome_langchain.compose: mint_ephemeral: waiting up to 20.0s for gateway sync (probing /v1/models)
+```
+
+If the probe times out you'll get a `TimeoutError` with the last status/body — that's a real signal something is wrong (sync loop stuck, wrong workspace, gateway misconfigured), not a normal flake.
+
+## Common failure modes
+
+| Symptom | Probable cause | Fix |
+|---|---|---|
+| `CreateAgentKey -> 409 key name "sdk-demo" already exists` | A previous partial run left the parent's key behind | `ensure_agent_key` now create-or-rotates — should be transparent. If it still appears, `./bootstrap.sh reset` and retry. |
+| `CreateLLMModelConnection -> 400 unknown auth_method` | You're on an older SDK — `auth_method` must be `api-key` (hyphen), `credential_type` must be `shared` | Pull the branch fresh |
+| `CreateLLMPool -> 400 unknown cache_scope` | Same — must be `workspace`, `caller`, or omitted | Pull the branch fresh |
+| `Request URL is missing an 'http://' or 'https://' protocol` | Child's `CreateAgentKey` response omitted `gateway_endpoint` | `mint_ephemeral`/`session.spawn` now accept a `gateway_endpoint` fallback that the demos pass through from the parent |
+| `401 invalid or expired token` from Broker | Bearer is a raw API key, not a JWT | `mint_ephemeral` now exchanges API keys → JWTs internally |
+| `403 agent act-as configuration unavailable` | Gateway hasn't synced the new agent yet | The 20s probe should handle this; if it times out, gateway sync may be stuck |
+| `KeyError` in a LangGraph node | Demo bug (state schema), not Dome | See `chain_e2e.py` / `spawn_e2e.py` for the `TypedDict` pattern |
+
+## Security posture — what the demos demonstrate, and what they don't
+
+Honest evaluation of these patterns against a "production security best practice" bar.
+
+### What's correctly modelled
+
+| Property | How |
+|---|---|
+| **Identity per agent** | Every chain agent and every spawned worker is a distinct registry record with its own bearer token. No shared identities. |
+| **Per-call audit attribution** | Every LLM call is audited under the calling agent's `agent_id`; you can reconstruct who did what when. |
+| **Fail-closed authorization** | Cedar evaluates *both* at chain hops (gates) and at every model call (Broker, `S.AUT.011`). Unknown agents → 403. Missing rules → deny. |
+| **Short-lived bearer tokens** | Agent API keys are exchanged for JWTs (default TTL ≈1h); the bearer presented to the Broker is the JWT, not the long-lived key. |
+| **Provider-secret centralization** | The Anthropic API key lives in Vault behind the Broker. Children never see it. A compromised child cannot exfiltrate it. |
+| **Lifecycle bookkeeping** | Ephemeral fleets are revoked *and* hard-deleted at session exit, even on exception. The revoked JWT is rejected immediately (`S.PRP.006`). |
+| **Workspace isolation** | All agents, rules, audit, and provider config are scoped to the workspace (`M.ORG.003`). |
+| **End-user identity via `X-Dome-Act-As`** | `--act-as <email>` attaches the user identity to every gate and every model call. Cedar can reason about it (`principal.act_as.email`, `.roles`, `.groups`). The deployed bundle includes a `*@deny.example.com` rule to demonstrate identity-driven deny. Uses `method=none` for the demo; production should configure `method=oidc` with a verified JWT. |
+
+### Where these demos fall short of production best practice
+
+| Gap | Why it matters | What closes it |
+|---|---|---|
+| **No delegation chain in identity** | The chain gate evaluates as the parent's principal, and downstream model calls carry the child's identity but not the chain (B → A → user). Cedar can't write rules that depend on the upstream chain. | `S.PRP.008` Agent-to-Agent Delegation (planned, not in code) — once landed, the SDK can swap the `caller_chain` context bag for a verified delegation claim with no public-API change. |
+| **Act-as is `method=none` in the demo** | The demo uses plaintext base64-JSON for `X-Dome-Act-As`, which the workspace's gateway accepts as the agent's `actas_config.method=none`. A malicious caller could fabricate any user identity — Cedar would believe it. | Switch the workspace's act-as policy to `method=oidc` and require a verified OIDC JWT (the SDK already accepts JWTs through the same `act_as=` parameter). Or `method=hmac` and a workspace HMAC secret. Both verify the user identity cryptographically before Cedar sees it. |
+| **Orchestrator holds a broad workspace key** | The script's `DOME_PLATFORM_KEY` has every permission needed to mint and tear down children. If the orchestrator process is compromised, an attacker can register or revoke arbitrary agents in the workspace. | Standard trade-off for an orchestrator service. Mitigations: scope the key to *just* the permissions needed; rotate often; store in a real secret manager (not `.dome-demo.env`); audit `agent.registered` events with alerting. |
+| **No server-side scope clamp** | An orchestrator could mint children with capabilities or tier *higher than its own*. Today the SDK enforces "child ⊆ parent" client-side only. | Future: server-side Cedar rule on the `RegisterAgent` action that constrains child capabilities by the caller's tier. |
+| **No classification firewall between chain steps** | A compromised middle agent could mislabel its output and slip data past a downstream gate. The demo treats every step's output as trusted input to the next. | The Atrium reference customer demonstrates the classification-firewall pattern: each step outputs a typed claim that's verified before becoming input. Worth borrowing for a chain that handles sensitive data. |
+| **JWT refresh not modelled** | Long-running spawns (>1h) would see worker JWTs expire mid-run. Demos run in seconds, so it doesn't surface. | Production session manager that refreshes via `ExchangeToken` before the JWT's `exp`. |
+| **`.dome-demo.env` is file-stored secrets** | OK for a local demo. Never production. | Production posture: read `DOME_PLATFORM_KEY` from a secret manager, never persist it on disk. |
+| **Ephemeral identities are durable registry rows** | Every spawned worker creates a registry row that exists for the lifetime of the run. At high fan-out scale this means registry churn and audit-table growth. | Acceptable for governed scenarios — the audit trail is the whole point. For *truly* transient identities (no registry footprint) Dome doesn't currently have a primitive; that's a deliberate platform choice, not an oversight. |
+
+### Net read
+
+These patterns implement the **structural** security model Dome was built for — identity, authorization, audit per agent, fail-closed. That's the load-bearing 80%. The remaining 20% is application-level discipline (act-as for users, classification firewall for sensitive data, secret management) plus one genuine platform gap (`S.PRP.008` for verifiable delegation chains).
+
+For a v0 "show me the platform works in my workspace" demo: it's correct. For a v1 production-shaped reference customer: switch act-as from `method=none` to `method=oidc`, swap `.dome-demo.env` for a secret manager, and consider the classification firewall pattern from Atrium.