imran-siddique · imran-siddique · Apr 15, 2026 · Apr 12, 2026 · Apr 12, 2026 · Apr 12, 2026
diff --git a/.cspell-repo-terms.txt b/.cspell-repo-terms.txt
@@ -55,3 +55,16 @@ syscall
 vnet
 workflow
 workflows
+AKIA
+asyncio
+aymenhmaidiwastaken
+carloshvp
+dataclass
+DOTALL
+findall
+hashlib
+hexdigest
+httpx
+lawcontinue
+Permissioned
+ufeff
diff --git a/.lychee.toml b/.lychee.toml
@@ -34,6 +34,9 @@ exclude = [
     # NIST (intermittent 404s from CI runners)
     "nist\\.gov",
 
+    # Stack Overflow (returns 404 to automated crawlers)
+    "stackoverflow\\.com",
+
     # Microsoft login / auth endpoints (require authentication)
     "login\\.microsoftonline\\.com",
     "portal\\.azure\\.com",

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -196,7 +196,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **TypeScript SDK full parity** (— PolicyEngine + AgentIdentity) — rich policy evaluation with 4 conflict resolution strategies, expression evaluator, rate limiting, YAML/JSON policy documents, Ed25519 identity with lifecycle/delegation/JWK/JWKS/DID export, IdentityRegistry with cascade revocation. 136 tests passing. (#269)
-- **@agentmesh/sdk 1.0.0** — TypeScript package now publish-ready with `exports` field, `prepublishOnly` build hook, correct `repository.directory`, MIT license.
+- **@microsoft/agentmesh-sdk 1.0.0** — TypeScript package now publish-ready with `exports` field, `prepublishOnly` build hook, correct `repository.directory`, MIT license.
 - **Multi-language README** — root README now surfaces Python (PyPI), TypeScript (npm), and .NET (NuGet) install sections, badges, quickstart code, and a multi-SDK packages table.
 - **Multi-language QUICKSTART** — getting started guide now covers all three SDKs with code examples.
 - **Semantic Kernel + Azure AI Foundry** added to framework integration table.
@@ -254,7 +254,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 pip install agent-governance-toolkit[full]
 
 # TypeScript
-npm install @agentmesh/sdk
+npm install @microsoft/agentmesh-sdk
 
 # .NET
 dotnet add package Microsoft.AgentGovernance

diff --git a/COMMUNITY.md b/COMMUNITY.md
@@ -20,6 +20,7 @@ Community-written content about agent governance, security, and the toolkit.
 | [Decentralized Identity in Multi-Agent Systems — From Theory to Production](https://dev.to/moltycel/decentralized-identity-in-multi-agent-systems-from-theory-to-production-1oe3) | [@MoltyCel](https://github.com/MoltyCel) | Dev.to |
 | [OWASP Agentic Top 10 — What Every AI Developer Should Know in 2026](https://dev.to/zhangzeyu/owasp-agentic-top-10-what-every-ai-developer-should-know-in-2026-55hi) | [@lawcontinue](https://github.com/lawcontinue) | Dev.to |
 | [EU AI Act for AI Agent Developers: A Practical Compliance Checklist](https://eu-ai-act.ai-mvp.com/2026/04/10/eu-ai-act-compliance-checklist-for-ai-agent-developers/) | [@carloshvp](https://github.com/carloshvp) | ai-mvp.com |
+| [MCP Security: Why Your AI Agents Need a Firewall for Tool Calls](https://dev.to/aymenhmaidi/mcp-security-why-your-ai-agents-tool-calls-need-a-firewall-3h48) | [@aymenhmaidiwastaken](https://github.com/aymenhmaidiwastaken) | Dev.to |
 
 ---
 

diff --git a/INDEPENDENCE.md b/INDEPENDENCE.md
@@ -24,7 +24,7 @@ Core paths (`agent_os/`, `agentmesh/`, `agent_hypervisor/`, `agent_sre/`) must f
 | **agentmesh** (Rust) | None — pure crypto + serde | ✅ Independent |
 | **agentmesh-mcp** (Rust) | None — pure crypto + serde | ✅ Independent |
 | **agentmesh** (Go) | None — yaml.v3 only | ✅ Independent |
-| **@agentmesh/sdk** (TypeScript) | None — zero runtime deps | ✅ Independent |
+| **@microsoft/agentmesh-sdk** (TypeScript) | None — zero runtime deps | ✅ Independent |
 | **Microsoft.AgentGovernance** (.NET) | None — YamlDotNet only | ✅ Independent |
 
 ## Adapter Pattern

diff --git a/QUICKSTART.ja.md b/QUICKSTART.ja.md
@@ -42,7 +42,7 @@ pip install agentmesh-lightning        # RL training governance
 ### TypeScript / Node.js
 
 ```bash
-npm install @agentmesh/sdk
+npm install @microsoft/agentmesh-sdk
 ```
 
 ### .NET
@@ -107,7 +107,7 @@ python governed_agent.py
 `governed_agent.ts` というファイルを作成します。
 
 ```typescript
-import { PolicyEngine, AgentIdentity, AuditLogger } from "@agentmesh/sdk";
+import { PolicyEngine, AgentIdentity, AuditLogger } from "@microsoft/agentmesh-sdk";
 
 const identity = AgentIdentity.generate("my-agent", ["web_search", "read_file"]);
 

diff --git a/QUICKSTART.md b/QUICKSTART.md
@@ -42,7 +42,7 @@ pip install agentmesh-lightning        # RL training governance
 ### TypeScript / Node.js
 
 ```bash
-npm install @agentmesh/sdk
+npm install @microsoft/agentmesh-sdk
 ```
 
 ### .NET
@@ -145,7 +145,7 @@ python governed_agent.py
 Create a file called `governed_agent.ts`:
 
 ```typescript
-import { PolicyEngine, AgentIdentity, AuditLogger } from "@agentmesh/sdk";
+import { PolicyEngine, AgentIdentity, AuditLogger } from "@microsoft/agentmesh-sdk";
 
 const identity = AgentIdentity.generate("my-agent", ["web_search", "read_file"]);
 

diff --git a/README.md b/README.md
@@ -30,7 +30,7 @@
 Agent Action ──► Policy Check ──► Allow / Deny ──► Audit Log    (< 0.1 ms)
 ```
 
-**Why it matters:** Prompt-based safety ("please follow the rules") has a [26.67% policy violation rate](BENCHMARKS.md) in red-team testing. AGT's kernel-level enforcement: **0.00%**.
+**Why it matters:** Prompt-based safety ("please follow the rules") has a [26.67% policy violation rate](BENCHMARKS.md) in red-team testing. AGT's policy-layer enforcement: **0.00%**.
 
 ---
 
@@ -70,7 +70,7 @@ result = evaluator.evaluate({"tool_name": "delete_file"})   # ❌ Blocked determ
 <summary><b>TypeScript</b></summary>
 
 ```typescript
-import { PolicyEngine } from "@agentmesh/sdk";
+import { PolicyEngine } from "@microsoft/agentmesh-sdk";
 
 const engine = new PolicyEngine([
   { action: "web_search", effect: "allow" },
@@ -200,9 +200,13 @@ Governance adds **< 0.1 ms per action** — roughly 10,000× faster than an LLM
 |---|---|---|
 | Policy evaluation (1 rule) | 0.012 ms | 72K ops/sec |
 | Policy evaluation (100 rules) | 0.029 ms | 31K ops/sec |
-| Kernel enforcement | 0.091 ms | 9.3K ops/sec |
+| Policy enforcement | 0.091 ms | 9.3K ops/sec |
 | Concurrent (50 agents) | — | 35,481 ops/sec |
 
+> **Note:** These numbers measure policy evaluation only. In distributed multi-agent
+> deployments, add ~5–50ms for cryptographic verification and mesh handshake on
+> inter-agent messages. See [Limitations — Performance](docs/LIMITATIONS.md#3-performance-policy-eval-vs-end-to-end) for full breakdown.
+
 Full methodology: [BENCHMARKS.md](BENCHMARKS.md)
 
 ---
@@ -212,7 +216,7 @@ Full methodology: [BENCHMARKS.md](BENCHMARKS.md)
 | Language | Package | Command |
 |----------|---------|---------|
 | **Python** | [`agent-governance-toolkit`](https://pypi.org/project/agent-governance-toolkit/) | `pip install agent-governance-toolkit[full]` |
-| **TypeScript** | [`@agentmesh/sdk`](packages/agent-mesh/sdks/typescript/) | `npm install @agentmesh/sdk` |
+| **TypeScript** | [`@microsoft/agentmesh-sdk`](packages/agent-mesh/sdks/typescript/) | `npm install @microsoft/agentmesh-sdk` |
 | **.NET** | [`Microsoft.AgentGovernance`](https://www.nuget.org/packages/Microsoft.AgentGovernance) | `dotnet add package Microsoft.AgentGovernance` |
 | **Rust** | [`agentmesh`](https://crates.io/crates/agentmesh) | `cargo add agentmesh` |
 | **Go** | [`agentmesh`](packages/agent-mesh/sdks/go/) | `go get github.com/microsoft/agent-governance-toolkit/sdks/go` |
@@ -253,6 +257,7 @@ See **[SDK Feature Matrix](docs/SDK-FEATURE-MATRIX.md)** for detailed per-langua
 - [API: Agent OS](packages/agent-os/README.md) · [AgentMesh](packages/agent-mesh/README.md) · [Agent SRE](packages/agent-sre/README.md)
 
 **Compliance & Deployment**
+- [Known Limitations](docs/LIMITATIONS.md) — Honest design boundaries and recommended layered defense
 - [OWASP Compliance](docs/OWASP-COMPLIANCE.md) — Full ASI-01 through ASI-10 mapping
 - [Azure Deployment](docs/deployment/README.md) — AKS, AI Foundry, Container Apps
 - [NIST AI RMF Alignment](docs/compliance/nist-ai-rmf-alignment.md) · [EU AI Act](docs/compliance/) · [SOC 2 Mapping](docs/compliance/soc2-mapping.md)
@@ -268,6 +273,8 @@ This toolkit provides **application-level governance** (Python middleware), not
 
 **Production recommendation:** Run each agent in a separate container for OS-level isolation. See [Architecture — Security Boundaries](docs/ARCHITECTURE.md).
 
+> **📖 [Known Limitations & Design Boundaries](docs/LIMITATIONS.md)** — what AGT does *not* do, honest performance numbers for distributed deployments, and the recommended layered defense architecture.
+
 | Tool | Coverage |
 |------|----------|
 | CodeQL | Python + TypeScript SAST |

diff --git a/RELEASE_NOTES_v2.1.0.md b/RELEASE_NOTES_v2.1.0.md
@@ -18,7 +18,7 @@ The toolkit is now a **polyglot governance layer**. All three SDKs have first-cl
 | Language | Package | Install |
 |----------|---------|---------|
 | **Python** | [`agent-governance-toolkit[full]`](https://pypi.org/project/agent-governance-toolkit/) | `pip install agent-governance-toolkit[full]` |
-| **TypeScript** | [`@agentmesh/sdk`](https://www.npmjs.com/package/@agentmesh/sdk) | `npm install @agentmesh/sdk` |
+| **TypeScript** | [`@microsoft/agentmesh-sdk`](https://www.npmjs.com/package/@microsoft/agentmesh-sdk) | `npm install @microsoft/agentmesh-sdk` |
 | **.NET** | [`Microsoft.AgentGovernance`](https://www.nuget.org/packages/Microsoft.AgentGovernance) | `dotnet add package Microsoft.AgentGovernance` |
 
 ### TypeScript SDK Full Parity (1.0.0)
@@ -99,7 +99,7 @@ Full methodology: [BENCHMARKS.md](BENCHMARKS.md)
 pip install agent-governance-toolkit[full]
 
 # TypeScript
-npm install @agentmesh/sdk
+npm install @microsoft/agentmesh-sdk
 
 # .NET
 dotnet add package Microsoft.AgentGovernance

diff --git a/docs/COMPARISON.md b/docs/COMPARISON.md
@@ -31,12 +31,14 @@ When evaluating agent security tooling, developers often encounter [NeMo Guardra
 | **Least-privilege capability model** | ✅ | ❌ | ❌ | ❌ | ❌ |
 | **Deterministic pre-execution enforcement** | ✅ < 0.1 ms | ❌ | ❌ | ❌ | ❌ |
 | **Chaos / replay testing** | ✅ | ❌ | ❌ | ❌ | ❌ |
-| **OWASP Agentic Top 10 coverage** | **10 / 10** | ~2 / 10 ¹ | ~1 / 10 ¹ | ~0 / 10 ¹ | ~1 / 10 ¹ |
+| **OWASP Agentic Top 10 coverage** | **10 / 10** ² | ~2 / 10 ¹ | ~1 / 10 ¹ | ~0 / 10 ¹ | ~1 / 10 ¹ |
 | **Framework integrations** | **12+** | 3 (LangChain, NeMo-based, custom) | 2 (LangChain, custom) | N/A (gateway) | N/A (gateway) |
 | **LLM provider routing / caching** | ❌ | ❌ | ❌ | ✅ | ✅ |
 | **Works alongside existing tools** | ✅ | ✅ | ✅ | ✅ | ✅ |
 
 > ¹ **OWASP scoring methodology:** Each tool was assessed against the ten [OWASP Agentic Top 10 (2026)](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/) risk categories. A risk is counted as "covered" only when the tool provides a mitigation that addresses the root cause of that risk category (not merely partial or indirect coverage). Scores for NeMo, Guardrails AI, LiteLLM, and Portkey are approximate because none of those tools publish explicit OWASP Agentic Top 10 mappings; they are based on a good-faith review of each tool's documented capabilities as of early 2026.
+>
+> ² **10/10 means mitigation components exist for each risk category**, not that each risk is fully eliminated. AGT provides application-layer governance — see [Known Limitations](LIMITATIONS.md) for documented gaps including hallucination detection, indirect prompt injection into reasoning, and multi-step workflow correlation.
 
 ---
 

diff --git a/docs/LIMITATIONS.md b/docs/LIMITATIONS.md
@@ -0,0 +1,148 @@
+# Known Limitations & Design Boundaries
+
+> **Transparency is a feature.** This document describes what AGT does *not* do
+> so you can make informed architecture decisions.
+
+## 1. Action Governance, Not Reasoning Governance
+
+AGT governs **what agents do** (tool calls, resource access, inter-agent messages).
+It does **not** govern what agents *think* or *say*.
+
+**What this means in practice:**
+
+- ✅ AGT blocks an agent from calling `delete_file` if policy forbids it
+- ❌ AGT does **not** detect if the *content* passed to an allowed tool is a hallucination
+- ❌ AGT does **not** detect indirect prompt injection that corrupts the agent's reasoning
+- ❌ AGT does **not** correlate sequences of individually-allowed actions that form a malicious workflow
+
+**Example gap:** If policy allows both `read_database` and `send_slack_message`,
+an agent could read your customer list and post it to a public channel — both
+actions are individually permitted.
+
+**Mitigations available today:**
+- Use **content policies** with blocked patterns (regex) to catch PII in outputs
+- Use **PromptDefenseEvaluator** to test for prompt injection vulnerabilities
+- Combine AGT with a model-level safety layer like [Azure AI Content Safety](https://learn.microsoft.com/azure/ai-services/content-safety/)
+- Use **max_tool_calls** limits to cap action sequences
+
+**What we're building:**
+- **Workflow-level policies** that evaluate action *sequences*, not just individual actions
+- **Intent declaration** where agents declare what they plan to do before doing it,
+  and the policy engine validates the plan
+
+## 2. Audit Logs Record Attempts, Not Outcomes
+
+AGT's audit trail records **what the agent attempted** and whether the governance
+layer allowed or denied it. It does **not** verify whether the action actually
+succeeded in the external world.
+
+**Example gap:** An agent calls a web API that returns `200 OK` but the data
+was stale. AGT logs "action allowed, executed" — but the agent's goal was not
+actually achieved.
+
+**Mitigations available today:**
+- Use the **SRE module** with SLOs to track action success rates over time
+- Use **saga orchestration** with compensating actions for multi-step workflows
+- Implement application-level result validation in your agent code
+
+**What we're building:**
+- **Post-action verification hooks** where users register validators that check
+  world-state after action execution
+- **Outcome attestation** in audit logs (succeeded/failed/unknown)
+
+## 3. Performance: Policy Eval vs. End-to-End
+
+Our published benchmark (<0.1ms policy evaluation) measures the **policy engine
+only** — the deterministic rule evaluation step. This is accurate and reproducible.
+
+In a **distributed multi-agent deployment**, the full governance overhead includes:
+
+| Component | Typical Latency | When It Applies |
+|-----------|-----------------|-----------------|
+| Policy evaluation | <0.1 ms | Every action |
+| Ed25519 signature verification | 1–3 ms | Inter-agent messages |
+| Trust score lookup | <1 ms | Inter-agent messages |
+| IATP handshake (first contact) | 10–50 ms | First message between two agents |
+| Network round-trip (mesh) | 1–10 ms | Distributed deployments only |
+
+**For single-agent, single-process deployments:** the <0.1ms number is the full overhead.
+
+**For multi-agent mesh deployments:** expect 5–50ms per governed inter-agent
+interaction, dominated by cryptographic verification and network latency — not
+the policy engine itself.
+
+## 4. Complexity Spectrum
+
+AGT is designed for enterprise governance. For simple use cases, the full stack
+(mesh identity, execution rings, SRE) may be overkill.
+
+**Minimal path (no mesh, no identity):**
+```python
+from agent_os.policies import PolicyEvaluator
+evaluator = PolicyEvaluator()
+evaluator.load_policies("policies/")
+# That's it — just policy evaluation, no crypto, no mesh
+```
+
+**Full path (everything):**
+```bash
+pip install agent-governance-toolkit[full]
+```
+
+You do **not** need to adopt the entire stack. Each package is independently
+installable and useful on its own.
+
+## 5. Vendor Independence
+
+AGT is MIT-licensed with **zero Azure/Microsoft dependencies** in the core packages.
+The policy engine, identity system, trust scoring, and execution rings work
+entirely offline with no cloud services required.
+
+**Cloud integrations exist** (Azure AI Foundry deployment guide, Entra ID adapter)
+but they are optional and in separate packages. You can run AGT on AWS, GCP,
+on-premises, or air-gapped environments.
+
+**To verify:** run `agt doctor` — it shows all installed packages and none require
+cloud connectivity.
+
+**Migration path:** All governance state (policies, audit logs, identity keys)
+is stored in standard formats (YAML, JSON, Ed25519 keys). There is no proprietary
+format or cloud-locked state.
+
+## 6. What AGT Is Not
+
+| AGT Is | AGT Is Not |
+|--------|------------|
+| Runtime action governance | Model safety / content moderation |
+| Deterministic policy enforcement | Probabilistic guardrails |
+| Application-layer middleware | OS kernel / hardware isolation |
+| Framework-agnostic library | A managed cloud service |
+| Audit trail of actions | Audit trail of outcomes |
+| Permission layer (L3/L4) | Application logic security (L7) |
+
+## Recommended Architecture
+
+For production deployments, we recommend a **layered defense**:
+
+```
+┌─────────────────────────────────┐
+│   Model Safety Layer            │  Azure AI Content Safety, Llama Guard
+│   (input/output filtering)      │  ← catches hallucinations, toxic content
+├─────────────────────────────────┤
+│   AGT Governance Layer          │  Policy engine, identity, trust, audit
+│   (action enforcement)          │  ← catches unauthorized actions
+├─────────────────────────────────┤
+│   Application Layer             │  Your agent code, framework adapters
+│   (business logic validation)   │  ← catches domain-specific errors
+├─────────────────────────────────┤
+│   Infrastructure Layer          │  Containers, network policies, IAM
+│   (OS/network isolation)        │  ← catches escape attempts
+└─────────────────────────────────┘
+```
+
+AGT is one layer in a defense-in-depth strategy, not the entire strategy.
+
+---
+
+*This document is maintained alongside the codebase. If you find a limitation
+not listed here, please [open an issue](https://github.com/microsoft/agent-governance-toolkit/issues).*
diff --git a/docs/OWASP-COMPLIANCE.md b/docs/OWASP-COMPLIANCE.md
@@ -33,10 +33,10 @@
 
 > *Attackers manipulate the agent's objectives via indirect prompt injection or poisoned inputs.*
 
-**Mitigation:** Agent OS enforces **policy-based action interception** at the kernel level. Every agent action passes through the policy engine before execution. Unauthorized goal changes are blocked before they reach the agent's tools.
+**Mitigation:** Agent OS enforces **policy-based action interception** at the application layer. Every agent action passes through the policy engine before execution. Unauthorized goal changes are blocked before they reach the agent's tools.
 
 - **Policy Engine** — declarative rules controlling what agents can and cannot do
-- **Action Interception** — kernel-level syscall abstraction intercepts all agent actions
+- **Action Interception** — application-layer action interception intercepts all agent actions
 - **Policy Modes** — `strict` (deny by default), `permissive` (allow by default), `audit` (log only)
 - **MCP Governance Proxy** — policy enforcement for MCP tool calls