agentsdiagram 0.1.0__tar.gz

agentsdiagram-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+# viewer bundle (built by pnpm, shipped via hatch `artifacts`)
+src/agentsdiagram/_static/
+# Node
+node_modules/
+packages/*/dist/
+packages/vscode/out/
+*.vsix
+# local
+.DS_Store
+CLAUDE.md
+.claude/

agentsdiagram-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 — 2026-10-22
+
+First release.
+
+- Static analysis of PydanticAI 2.x (agents, tools, toolsets, MCP, capabilities, SubAgents,
+  delegation, hand-off workflows, pydantic-graph, Agent Specs) and smolagents 1.x (CodeAgent,
+  ToolCallingAgent, tools, managed agents, MCP).
+- CLI: `scan` (Mermaid, JSON, Markdown, self-contained interactive HTML), `check`, `schema`, `lsp`.
+- Interactive viewer (React Flow) and VS Code / Open VSX extension with live diagram, code lenses
+  and diagnostics.

agentsdiagram-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Ojeda Copa
+
+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.

agentsdiagram-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: agentsdiagram
+Version: 0.1.0
+Summary: See your AI agents: static diagrams of agents, tools and flows for PydanticAI and smolagents — CLI and VS Code extension.
+Project-URL: Homepage, https://github.com/alex-roc/agentsdiagram
+Project-URL: Repository, https://github.com/alex-roc/agentsdiagram
+Project-URL: Issues, https://github.com/alex-roc/agentsdiagram/issues
+Project-URL: Changelog, https://github.com/alex-roc/agentsdiagram/blob/main/CHANGELOG.md
+Author: Alex Ojeda Copa
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,diagram,llm,mermaid,pydantic-ai,smolagents,static-analysis,visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: libcst>=1.9
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6
+Provides-Extra: lsp
+Requires-Dist: pygls>=2.1; extra == 'lsp'
+Description-Content-Type: text/markdown
+
+# agentsdiagram
+
+**See your AI agents.** `agentsdiagram` reads the code of your [PydanticAI](https://ai.pydantic.dev)
+and [smolagents](https://huggingface.co/docs/smolagents) agents and draws them: agents, tools,
+toolsets, MCP servers, capabilities, delegation between agents, hand-off workflows and
+pydantic-graph flows.
+
+It is **static analysis**: your code is parsed, never imported or executed. No API keys, no
+dependencies of your project, no network.
+
+![The interactive viewer](docs/images/viewer.png)
+
+- **CLI**: Mermaid, JSON or a self-contained interactive HTML page.
+- **VS Code extension** (also on Open VSX for Cursor, Windsurf and Positron): a live diagram next to
+  your code that follows your edits, "Show in diagram" code lenses and diagnostics.
+
+## Quick start
+
+```bash
+uvx agentsdiagram scan path/to/project                    # Mermaid to stdout
+uvx agentsdiagram scan . -f html -o agents.html           # interactive page, open it in any browser
+uvx agentsdiagram scan . -f markdown -o AGENTS-DIAGRAM.md # renders on GitHub
+uvx agentsdiagram check .                                 # diagnostics; exit 1 on errors (CI, pre-commit)
+```
+
+Or install it: `uv tool install agentsdiagram` / `pip install agentsdiagram`.
+
+```
+agentsdiagram scan [PATH] [-f mermaid|json|html|markdown] [-o FILE] [--framework pydantic_ai|smolagents]
+                   [--include GLOB] [--exclude GLOB] [--title TEXT]
+agentsdiagram check [PATH] [--strict] [--json]
+agentsdiagram schema        # JSON Schema of the IR
+agentsdiagram lsp           # language server (needs agentsdiagram[lsp]); used by the extension
+```
+
+Project-wide settings go in `pyproject.toml`:
+
+```toml
+[tool.agentsdiagram]
+include = ["src/**"]
+exclude = ["tests/**", "notebooks/**"]
+```
+
+## What it understands
+
+| | PydanticAI 2.x | smolagents 1.x |
+|---|---|---|
+| Agents | `Agent(...)`, `Agent.from_file("spec.yaml")`, factories (`make_agent()`) | `CodeAgent`, `ToolCallingAgent` |
+| Tools | `@agent.tool`, `@agent.tool_plain`, `tools=[f, Tool(...)]` | `@tool`, `Tool` subclasses, default tools, `add_base_tools` |
+| Toolsets | `FunctionToolset`, wrappers (`.prefixed()`, `.filtered()`…), `@agent.toolset` | `ToolCollection`, Hub/Space/LangChain sources |
+| MCP | `MCPToolset(...)`, `load_mcp_toolsets("mcp.json")`, `MCP(url=...)` | `ToolCollection.from_mcp`, `MCPClient` |
+| Multi-agent | agent run inside a tool, `SubAgents`, hand-off functions | `managed_agents=[...]` |
+| Flows | pydantic-graph `GraphBuilder` (steps, decisions, joins) and `BaseNode` | — |
+| Checks | v1 API still in use | managed agents without name/description, `@tool` without hints, name clashes |
+
+Anything that only exists at runtime (lists built in a loop, tools fetched from a server) shows up
+as a dashed **dynamic** node instead of silently disappearing. Full coverage matrices:
+[PydanticAI](docs/adapters/pydantic_ai.md) · [smolagents](docs/adapters/smolagents.md).
+
+## VS Code extension
+
+Install **Agents Diagram** from the Marketplace or Open VSX. It needs either
+[uv](https://docs.astral.sh/uv/) (the extension runs `uvx agentsdiagram[lsp]`) or your own command
+in `agentsdiagram.server.command`. The Python extension is not required. See
+[packages/vscode/README.md](packages/vscode/README.md).
+
+## How it works
+
+```
+your code ──LibCST──▶ adapters (pydantic_ai, smolagents) ──▶ facts ──link──▶ IR (JSON)
+                                                                         ├─▶ Mermaid
+                                                                         ├─▶ HTML viewer (React Flow)
+                                                                         └─▶ LSP ─▶ VS Code panel
+```
+
+The IR is a small, versioned JSON format ([docs/ir.md](docs/ir.md)); the viewer and the
+extension use TypeScript types generated from its JSON Schema. Architecture and design
+decisions: [docs/architecture.md](docs/architecture.md).
+
+## Roadmap
+
+- **Plan** (v0.3): draw agents and tools that do not exist yet; agentsdiagram writes the stubs.
+- **Edit** (v0.4): connect, add and remove tools and agents in the diagram; the change is written
+  to your code with LibCST, preserving formatting. The code stays the single source of truth.
+- More frameworks through adapters ([docs/adding-a-framework.md](docs/adding-a-framework.md)).
+
+## Development
+
+```bash
+uv sync                      # Python 3.11+, includes pydantic-ai and smolagents for the oracle tests
+pnpm install && pnpm build   # viewer + extension (pnpm 11, Node 22+)
+uv run pytest                # unit, snapshot, oracle, drift and LSP tests
+pnpm test                    # viewer (vitest) + extension smoke test
+```
+
+More in [docs/architecture.md](docs/architecture.md#development) and [docs/releasing.md](docs/releasing.md).
+
+## License
+
+MIT © 2026 Alex Ojeda Copa

agentsdiagram-0.1.0/README.md

@@ -0,0 +1,100 @@
+# agentsdiagram
+
+**See your AI agents.** `agentsdiagram` reads the code of your [PydanticAI](https://ai.pydantic.dev)
+and [smolagents](https://huggingface.co/docs/smolagents) agents and draws them: agents, tools,
+toolsets, MCP servers, capabilities, delegation between agents, hand-off workflows and
+pydantic-graph flows.
+
+It is **static analysis**: your code is parsed, never imported or executed. No API keys, no
+dependencies of your project, no network.
+
+![The interactive viewer](docs/images/viewer.png)
+
+- **CLI**: Mermaid, JSON or a self-contained interactive HTML page.
+- **VS Code extension** (also on Open VSX for Cursor, Windsurf and Positron): a live diagram next to
+  your code that follows your edits, "Show in diagram" code lenses and diagnostics.
+
+## Quick start
+
+```bash
+uvx agentsdiagram scan path/to/project                    # Mermaid to stdout
+uvx agentsdiagram scan . -f html -o agents.html           # interactive page, open it in any browser
+uvx agentsdiagram scan . -f markdown -o AGENTS-DIAGRAM.md # renders on GitHub
+uvx agentsdiagram check .                                 # diagnostics; exit 1 on errors (CI, pre-commit)
+```
+
+Or install it: `uv tool install agentsdiagram` / `pip install agentsdiagram`.
+
+```
+agentsdiagram scan [PATH] [-f mermaid|json|html|markdown] [-o FILE] [--framework pydantic_ai|smolagents]
+                   [--include GLOB] [--exclude GLOB] [--title TEXT]
+agentsdiagram check [PATH] [--strict] [--json]
+agentsdiagram schema        # JSON Schema of the IR
+agentsdiagram lsp           # language server (needs agentsdiagram[lsp]); used by the extension
+```
+
+Project-wide settings go in `pyproject.toml`:
+
+```toml
+[tool.agentsdiagram]
+include = ["src/**"]
+exclude = ["tests/**", "notebooks/**"]
+```
+
+## What it understands
+
+| | PydanticAI 2.x | smolagents 1.x |
+|---|---|---|
+| Agents | `Agent(...)`, `Agent.from_file("spec.yaml")`, factories (`make_agent()`) | `CodeAgent`, `ToolCallingAgent` |
+| Tools | `@agent.tool`, `@agent.tool_plain`, `tools=[f, Tool(...)]` | `@tool`, `Tool` subclasses, default tools, `add_base_tools` |
+| Toolsets | `FunctionToolset`, wrappers (`.prefixed()`, `.filtered()`…), `@agent.toolset` | `ToolCollection`, Hub/Space/LangChain sources |
+| MCP | `MCPToolset(...)`, `load_mcp_toolsets("mcp.json")`, `MCP(url=...)` | `ToolCollection.from_mcp`, `MCPClient` |
+| Multi-agent | agent run inside a tool, `SubAgents`, hand-off functions | `managed_agents=[...]` |
+| Flows | pydantic-graph `GraphBuilder` (steps, decisions, joins) and `BaseNode` | — |
+| Checks | v1 API still in use | managed agents without name/description, `@tool` without hints, name clashes |
+
+Anything that only exists at runtime (lists built in a loop, tools fetched from a server) shows up
+as a dashed **dynamic** node instead of silently disappearing. Full coverage matrices:
+[PydanticAI](docs/adapters/pydantic_ai.md) · [smolagents](docs/adapters/smolagents.md).
+
+## VS Code extension
+
+Install **Agents Diagram** from the Marketplace or Open VSX. It needs either
+[uv](https://docs.astral.sh/uv/) (the extension runs `uvx agentsdiagram[lsp]`) or your own command
+in `agentsdiagram.server.command`. The Python extension is not required. See
+[packages/vscode/README.md](packages/vscode/README.md).
+
+## How it works
+
+```
+your code ──LibCST──▶ adapters (pydantic_ai, smolagents) ──▶ facts ──link──▶ IR (JSON)
+                                                                         ├─▶ Mermaid
+                                                                         ├─▶ HTML viewer (React Flow)
+                                                                         └─▶ LSP ─▶ VS Code panel
+```
+
+The IR is a small, versioned JSON format ([docs/ir.md](docs/ir.md)); the viewer and the
+extension use TypeScript types generated from its JSON Schema. Architecture and design
+decisions: [docs/architecture.md](docs/architecture.md).
+
+## Roadmap
+
+- **Plan** (v0.3): draw agents and tools that do not exist yet; agentsdiagram writes the stubs.
+- **Edit** (v0.4): connect, add and remove tools and agents in the diagram; the change is written
+  to your code with LibCST, preserving formatting. The code stays the single source of truth.
+- More frameworks through adapters ([docs/adding-a-framework.md](docs/adding-a-framework.md)).
+
+## Development
+
+```bash
+uv sync                      # Python 3.11+, includes pydantic-ai and smolagents for the oracle tests
+pnpm install && pnpm build   # viewer + extension (pnpm 11, Node 22+)
+uv run pytest                # unit, snapshot, oracle, drift and LSP tests
+pnpm test                    # viewer (vitest) + extension smoke test
+```
+
+More in [docs/architecture.md](docs/architecture.md#development) and [docs/releasing.md](docs/releasing.md).
+
+## License
+
+MIT © 2026 Alex Ojeda Copa

agentsdiagram-0.1.0/docs/adapters/pydantic_ai.md

@@ -0,0 +1,38 @@
+# PydanticAI adapter
+
+Verified against **pydantic-ai 2.59.0**, **pydantic-ai-harness 0.59.0** and **pydantic-graph 2.59.0**
+(October 2026). Symbols: [`adapters/pydantic_ai/symbols.py`](../../src/agentsdiagram/adapters/pydantic_ai/symbols.py).
+
+| Construct | Result |
+|---|---|
+| `Agent(model, name=, instructions=/system_prompt=, deps_type=, output_type=, description=)` | `agent` node (name from `name=` or the variable) |
+| `Agent(...)` inside a function | `partial` agent; `x = factory(...)` gets its own node |
+| `Agent.from_file("x.yaml")` (literal path) | agent from the Agent Spec: model, instructions, capabilities, MCP |
+| `@agent.tool`, `@agent.tool_plain` (`name=`, `requires_approval=`) | `tool` with docstring, signature, `takes_ctx` |
+| `tools=[f, Tool(f, ...), Tool.from_schema(...)]` | `uses` → `tool` |
+| `@agent.instructions`, `@agent.system_prompt` | `attrs.dynamic_instructions` |
+| `@agent.output_validator`, `@agent.on_event` | badges |
+| `@agent.toolset` | `dynamic` toolset |
+| `FunctionToolset(tools=[...])`, `@ts.tool`, `@ts.tool_plain`, `ts.add_function(f)` | `toolset` → `provides` → tools |
+| `PrefixedToolset`, `FilteredToolset`, `RenamedToolset`, `ApprovalRequiredToolset`… / `CombinedToolset` | `toolset` → `wraps` |
+| `.prefixed()`, `.filtered()`, `.renamed()`, `.approval_required()`… | edge `wrappers` |
+| `ExternalToolset` | `partial` toolset |
+| `MCPToolset("https://…")`, `MCPToolset(StdioTransport(command, args))`, `MCPToolset(Client(...))` | `mcp_server` with url/command |
+| `load_mcp_toolsets("mcp.json")` (literal path) | toolset → one `mcp_server` per entry |
+| `capabilities=[NativeTool(WebSearchTool())]`, `WebSearch()`, `WebFetch()`… | `native_tool` |
+| `capabilities=[MCP(url=...)]` | `mcp_server` |
+| `capabilities=[Capability(id=, tools=, toolsets=)]`, `@cap.tool` | `capability` → `provides` |
+| `capabilities=[Toolset(ts)]` | `uses` → toolset |
+| `SubAgents(agents=[SubAgent(a, name=)])` (harness) | `capability` → `delegates_to` → agent |
+| `DynamicWorkflow(agents=[...])` (harness) | `dynamic` capability → `delegates_to` |
+| any other capability (`Thinking`, `Caching`, `TemporalDurability`…) | badge on the agent |
+| `other.run/run_sync/run_stream/iter(...)` inside a tool | tool → `delegates_to` → agent |
+| function running ≥ 2 agents | `workflow` → ordered `runs` |
+| `GraphBuilder`: `@g.step`, `g.join(...)`, `edge_from(...).to(...)`, `.map()`, `.label()`, `decision().branch(match(T).label().to())` | `graph` with `graph_step`s and `transitions` |
+| `BaseNode` subclasses (`run()` return annotation, `End[T]`) | `graph` with `transitions` |
+| v1: `MCPServerStdio/SSE/StreamableHTTP/HTTP`, `mcp_servers=`, `builtin_tools=`, `load_mcp_servers`, `UrlContextTool` | recognised + AD101 |
+
+Not detected (shown as `dynamic` when referenced): toolsets/tools built at runtime, agents
+passed as parameters, output functions that hand off (planned).
+
+FastMCP servers (`@server.tool()`) are deliberately **not** treated as agent tools.

agentsdiagram-0.1.0/docs/adapters/smolagents.md

@@ -0,0 +1,28 @@
+# smolagents adapter
+
+Verified against **smolagents 1.26.0** (October 2026). Symbols:
+[`adapters/smolagents/symbols.py`](../../src/agentsdiagram/adapters/smolagents/symbols.py).
+
+| Construct | Result |
+|---|---|
+| `CodeAgent(...)`, `ToolCallingAgent(...)` | `agent`: `name`, `description`, `instructions`, model (`Class('model_id')`, aliases like `OpenAIServerModel` → `OpenAIModel`), `planning_interval`, `max_steps`, `executor_type`, `additional_authorized_imports` |
+| `tools=[...]` | `uses` → tool / MCP / external source |
+| `managed_agents=[...]` | `manages` → agent |
+| `add_base_tools=True` | implicit `web_search`, `visit_webpage` (+ `python_interpreter` on `ToolCallingAgent`), as in `agents.py::_setup_tools` |
+| `@tool` functions | `tool` with docstring and signature |
+| `class X(Tool)` with `name`, `description`, `inputs`, `output_type`, `forward` | `tool` |
+| default tools (`WebSearchTool()`, `DuckDuckGoSearchTool()`, `VisitWebpageTool()`…) | `tool` with the name the library exposes |
+| `Tool.from_space/from_langchain/from_gradio/from_code` | `partial` tool |
+| `Tool.from_hub`, `load_tool`, `ToolCollection.from_hub` | `external_tool_source` |
+| `with ToolCollection.from_mcp(params) as tc: ... tools=[*tc.tools]` | `mcp_server` (command or URL) |
+| `with MCPClient(params) as tools: ... tools=tools` | `mcp_server` |
+| `managed.run(...)` inside a `@tool` | `delegates_to` |
+
+Diagnostics: AD201 (managed agent without `name`/`description`), AD202 (two tools/agents with the
+same name — several default tools are all called `web_search`), AD203 (`@tool` without type hints
+or `Args:`), AD204 (`executor_type="wasm"`, removed in 1.26).
+
+`final_answer` is added by smolagents to every agent and is not drawn.
+
+Note: in 1.26 `agent.to_dict()` returns `tools` and `managed_agents` as lists of dicts (with
+code), not names; the oracle tests use it as ground truth.

agentsdiagram-0.1.0/docs/adding-a-framework.md

@@ -0,0 +1,18 @@
+# Adding a framework
+
+1. Create `src/agentsdiagram/adapters/<framework>/` with:
+   - `symbols.py`: tables of `root.LastName` symbols, with the library version you verified
+     against, and `all_symbols()`.
+   - `extract.py`: a class with `framework`, `markers` (bytes for the prefilter),
+     `run_methods`, `extract(module, facts)` and `check(project)`.
+2. In `extract`, iterate `module.calls` (source order; reverse it for post-order) and
+   `module.bindings`. Register nodes with `facts.add(Def(...), call)` and relations with
+   `facts.edge(source_key, kind, module, target_expression)`. Let the linker resolve the
+   targets; do not resolve names yourself. Use `adapters/base.py` helpers (`arg`,
+   `string_value`, `describe_model`, `elements`, `value_of`…).
+3. Add the framework to `Framework` in `ir.py`, run `pnpm schema`, and register the adapter in
+   `adapters/__init__.py`.
+4. Add fixtures under `tests/fixtures/<short>/`, unit tests, oracle tests (import the fixtures
+   with the real library) and the symbol drift test, and add the library to the `oracle`
+   dependency group and to `.github/workflows/drift.yml`.
+5. Document coverage in `docs/adapters/<framework>.md` and the README table.

agentsdiagram-0.1.0/docs/architecture.md

@@ -0,0 +1,82 @@
+# Architecture
+
+`agentsdiagram` turns agent code into a graph without running it. One Python core feeds three
+front ends (CLI, HTML viewer, VS Code extension) through one JSON format (the IR).
+
+```
+src/agentsdiagram/
+  project.py    file discovery (git ls-files), module index, one-pass LibCST collector
+  facts.py      per-module facts recorded by adapters (Defs + pending edges)
+  adapters/     one package per framework: symbols.py (data) + extract.py (logic)
+  analyze.py    lazy loading, name resolution across modules, linking, IR build
+  ir.py         the IR (pydantic) and its JSON Schema
+  render/       mermaid.py, html.py (inlines the viewer bundle from _static/)
+  lsp.py        pygls 2 language server for the extension
+  cli.py        argparse CLI
+packages/
+  protocol/     TS types generated from the IR schema + viewer/extension messages
+  viewer/       React Flow viewer, one IIFE bundle (viewer.js + viewer.css)
+  vscode/       the extension (LanguageClient + webview panel)
+```
+
+## Pipeline
+
+1. **Collect.** `project.collect()` lists Python files (honouring `.gitignore` via
+   `git ls-files`), builds a module index for cross-module resolution and selects the *seed*
+   files to analyse (`[tool.agentsdiagram]` include/exclude apply).
+2. **Prefilter.** A seed is parsed only if its bytes mention a framework (`pydantic_ai`,
+   `smolagents`…) or an agent run method (`.run(`), so large repos stay fast.
+3. **Parse.** LibCST parses each file once. A single custom visitor computes parents,
+   scopes, bindings, qualified names and the list of calls. It replaces LibCST's
+   Scope/QualifiedName providers, which were 3–4x slower. It follows Python's LEGB
+   lookup for module, function and class scopes.
+4. **Extract.** Each adapter records `Def`s (things that may become nodes) and pending
+   edges whose target is still an expression. Plain functions and classes are registered
+   too, so they become tools only when something uses them.
+5. **Resolve and link.** `Analyzer.resolve()` follows names through assignments, imports and
+   re-exports across modules, factory functions (`return Agent(...)`), list literals, `+`
+   concatenation and method calls (`ts.prefixed("x")` becomes an edge wrapper). Modules
+   are loaded lazily. Unresolvable expressions become `dynamic` nodes. Library objects
+   with no structural meaning (e.g. `Thinking()`) become badges.
+6. **Implicit relations.** Function bodies of visible tools and graph steps are scanned for
+   `agent.run(...)` calls, which produce `delegates_to` and `runs` edges. A plain function
+   that runs two or more agents becomes a `workflow` node with ordered `runs` edges.
+7. **Build.** Visible defs (explicit ones in seed files, plus everything reachable) become
+   nodes with stable ids. Adapters then run whole-graph checks (`check()`).
+
+## Key decisions
+
+- **Static only.** It never imports user code. This keeps it safe and independent of the user's
+  environment, and makes it work on broken projects.
+- **The code is the single source of truth.** Planning and editing (roadmap) will write code
+  with LibCST. The diagram never stores state of its own.
+- **Data-driven adapters.** Library symbols live in `symbols.py` tables matched by root
+  package and last name (`pydantic_ai.Agent` also matches `pydantic_ai.agent.Agent`).
+  `tests/test_symbols_drift.py` imports every entry, and a weekly workflow runs it against the
+  latest releases.
+- **Factory instances.** `planner = make_agent(...)` creates its own node, a copy of the
+  factory's product, and the factory's template node is hidden. Without this, every agent
+  built by one factory would collapse into a single node.
+- **Tolerant to broken code.** A file with a syntax error keeps its last valid version, marked
+  `stale`, plus diagnostic AD000. Each adapter runs isolated, and a crash becomes AD900.
+- **Stable ids.** Ids are `framework:kind:module.qualname`. Unnamed constructs use an ordinal
+  within their scope, never line numbers. Every node and edge also carries a `SourceRef` (range
+  plus name range), which future edits will use as anchors.
+- **LSP for the editor.** pygls gives us unsaved buffers, lifecycle, cancellation and the
+  Problems panel. IR columns are code points and are converted to UTF-16 at the LSP boundary.
+- **The extension does not embed Python.** It runs `uvx agentsdiagram[lsp]==<its version>`, or a
+  user-configured command (machine scope, restricted in untrusted workspaces).
+
+## Development
+
+```bash
+uv sync && pnpm install
+uv run pytest                     # Python: unit, snapshots (syrupy), oracles, drift, LSP (pytest-lsp)
+uv run pytest --snapshot-update   # after an intended output change
+pnpm build                        # viewer -> src/agentsdiagram/_static and packages/vscode/media
+pnpm schema                       # after changing ir.py: regenerate the schema and TS types
+pnpm --filter agentsdiagram test:e2e   # extension + real language server (needs uv)
+```
+
+Fixtures live in `tests/fixtures` (their own project root). Oracle tests import them with the
+real libraries, so a fixture that stops importing is also a failing test.

agentsdiagram-0.1.0/docs/ir.md

@@ -0,0 +1,63 @@
+# The IR (intermediate representation)
+
+JSON produced by `agentsdiagram scan -f json` and by the language server (`agentsdiagram/graph`).
+Schema: `agentsdiagram schema` / [`packages/protocol/ir.schema.json`](../packages/protocol/ir.schema.json).
+Current version: `ir_version: "1"`.
+
+```jsonc
+{
+  "ir_version": "1", "tool_version": "0.1.0", "root": "/abs/project",
+  "frameworks": ["pydantic_ai"],
+  "files":  [{ "path": "app/agents.py", "module": "app.agents", "frameworks": ["pydantic_ai"], "status": "ok", "sha256": "…" }],
+  "nodes":  [{ "id": "pydantic_ai:agent:app.agents.lead", "kind": "agent", "framework": "pydantic_ai",
+               "name": "lead", "status": "resolved", "source": { "file": "app/agents.py", "range": {…}, "name_range": {…} },
+               "attrs": { "model": "openai:gpt-5", "instructions": "…", "badges": ["Thinking"], "extra": {} } }],
+  "edges":  [{ "id": "uses:…->…", "kind": "uses", "source": "…", "target": "…", "label": null, "order": null,
+               "wrappers": ["prefixed(\"math\")"], "ref": { … } }],
+  "diagnostics": [{ "code": "AD201", "severity": "error", "message": "…", "ref": { … }, "node_id": "…" }]
+}
+```
+
+Positions: `line` is 1-based, `column` is 0-based and counted in code points.
+
+## Node kinds
+
+| kind | meaning |
+|---|---|
+| `agent` | an agent (`Agent`, `CodeAgent`, `ToolCallingAgent`, an Agent Spec) |
+| `tool` | a function or `Tool` the model can call |
+| `toolset` | a group of tools (`FunctionToolset`, wrappers, MCP config files, dynamic toolsets) |
+| `mcp_server` | an MCP server (stdio command or URL) |
+| `native_tool` | a provider-side tool (`WebSearchTool`, `WebFetch`…) |
+| `capability` | a PydanticAI capability with structure (`Capability`, `SubAgents`, `DynamicWorkflow`) |
+| `workflow` | a plain function that runs several agents in sequence (hand-off) |
+| `external_tool_source` | tools loaded from the Hub, a Space, LangChain… |
+| `graph` / `graph_step` | pydantic-graph graphs and their steps (incl. `start`, `end`, `decision`, joins) |
+| `dynamic` | an expression that cannot be resolved statically |
+
+## Edge kinds
+
+`uses` (agent → tool/toolset/mcp/native/capability) · `provides` (toolset/capability → tool) ·
+`wraps` (wrapper toolset → inner) · `delegates_to` (tool/capability → agent) ·
+`manages` (smolagents manager → managed agent) · `runs` (workflow/graph step → agent, ordered) ·
+`contains` (graph → step) · `transitions` (step → step).
+
+## Status
+
+`resolved` · `partial` (built in a function / factory, arguments may vary) · `dynamic` ·
+`planned` (roadmap: stubs written by the planner) · `stale` (file has a syntax error; last valid version).
+
+## Diagnostic codes
+
+| code | severity | meaning |
+|---|---|---|
+| AD000 | error / warning | syntax error (warning when a previous valid version is shown) |
+| AD001 | info | expression cannot be resolved statically (dynamic node) |
+| AD002 | info | referenced config/spec file not found |
+| AD101 | warning | PydanticAI v1 API (`MCPServerStdio`, `mcp_servers=`, `builtin_tools=`…) |
+| AD201 | error | smolagents managed agent without `name` and `description` |
+| AD202 | warning | smolagents agent with two tools/agents of the same name |
+| AD203 | warning | smolagents `@tool` without type hints or `Args:` docstring |
+| AD204 | error | smolagents `executor_type` that no longer exists |
+| AD301 | info | agent created inside a function |
+| AD900 | error | an adapter crashed on a file (please report it) |

agentsdiagram-0.1.0/docs/releasing.md

@@ -0,0 +1,36 @@
+# Releasing
+
+Versions are kept in lockstep: `src/agentsdiagram/__init__.py` and `packages/vscode/package.json`
+must match the tag. The extension runs `uvx agentsdiagram[lsp]==<its version>`, so PyPI is
+published first.
+
+```bash
+# bump both versions, update CHANGELOG.md, commit
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+`.github/workflows/release.yml` builds the viewer, the wheel/sdist (checking `_static/` is inside)
+and the `.vsix`, then publishes PyPI → Open VSX + Marketplace → GitHub release.
+
+## One-time setup
+
+- **PyPI**: on pypi.org (account `alex-roc`), *Publishing → Add a pending publisher*:
+  project `agentsdiagram`, owner `alex-roc`, repo `agentsdiagram`, workflow `release.yml`,
+  environment `release`. Create the `release` environment in the GitHub repo.
+- **Open VSX**: sign in at open-vsx.org with GitHub `alex-roc`, sign the Publisher Agreement,
+  create a token, run `npx ovsx create-namespace alex-roc -p <token>`, then claim the namespace
+  (issue in EclipseFdn/open-vsx.org, "Namespace access"). Store the token as secret `OVSX_PAT`.
+- **VS Code Marketplace**: create publisher `alex-roc` at marketplace.visualstudio.com/manage.
+  Global Azure DevOps PATs are retired on **2026-12-01**, so use Microsoft Entra ID: an app
+  registration with a federated credential for `repo:alex-roc/agentsdiagram:environment:release`,
+  added as a member of the publisher; set repository variables `AZURE_CLIENT_ID` and
+  `AZURE_TENANT_ID`. (Until then a `VSCE_PAT` secret also works.)
+
+## Manual publish (fallback)
+
+```bash
+pnpm build && uv build && uv publish            # PyPI
+pnpm --filter agentsdiagram run package         # packages/vscode/agentsdiagram-X.Y.Z.vsix
+npx ovsx publish packages/vscode/*.vsix -p $OVSX_PAT
+npx @vscode/vsce publish --packagePath packages/vscode/*.vsix --azure-credential
+```

agentsdiagram-0.1.0/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "agentsdiagram-monorepo",
+  "private": true,
+  "packageManager": "pnpm@11.17.0",
+  "scripts": {
+    "build": "pnpm --filter @agentsdiagram/viewer run build && pnpm --filter agentsdiagram run build",
+    "test": "pnpm -r --if-present run test",
+    "lint": "pnpm -r --if-present run lint",
+    "schema": "uv run agentsdiagram schema > packages/protocol/ir.schema.json && pnpm --filter @agentsdiagram/protocol run generate"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}