feat(examples): add A2A design review demo

docs/get-started/tutorials/a2a-design-review.mdx

@@ -0,0 +1,122 @@
+---
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+title: "Run an A2A Agent Design Review"
+sidebar-title: "A2A Design Review"
+slug: "get-started/tutorials/a2a-design-review"
+description: "Run multiple A2A-compatible agents in isolated OpenShell sandboxes and use them to review a GitHub issue from different perspectives."
+keywords: "Generative AI, Cybersecurity, Tutorial, A2A, Agent2Agent, Multi-Agent, Sandbox, Policy"
+---
+
+This tutorial runs a small Agent2Agent (A2A) design-review mesh. Four remote agents review a GitHub issue from different perspectives, stream task updates, and return markdown artifacts. OpenShell runs each remote agent in its own sandbox so the agents can collaborate without sharing files, credentials, or unrelated network access.
+
+After completing this tutorial, you understand:
+
+- How A2A Agent Cards let a client agent discover remote agent capabilities.
+- How A2A message and streaming endpoints support iterative collaboration.
+- How OpenShell isolates each remote agent while still exposing its service through the gateway.
+- Why A2A's HTTP+JSON shape maps cleanly to OpenShell REST path enforcement.
+
+## Prerequisites
+
+- A working OpenShell installation. Complete the [Quickstart](/get-started/quickstart) before proceeding.
+- A running OpenShell gateway.
+- Node.js 18 or newer on your host machine.
+
+<Tip>
+You can run the protocol smoke without a gateway:
+
+```shell
+DEMO_LOCAL_ONLY=1 bash examples/a2a-design-review/demo.sh
+```
+
+The local smoke starts the same A2A agents on loopback and writes the same review artifact.
+</Tip>
+
+<Steps toc={true}>
+
+## Start the Gateway
+
+For local development, start the Docker-backed gateway:
+
+```shell
+mise run gateway:docker
+```
+
+Verify that the CLI can reach it:
+
+```shell
+openshell status
+```
+
+## Run the Demo
+
+From the repository root, run:
+
+```shell
+bash examples/a2a-design-review/demo.sh
+```
+
+The script creates one sandbox per remote A2A agent, uploads the agent server, and starts the HTTP service inside each sandbox. It then exposes each service through the gateway and runs the host-side orchestrator.
+
+The orchestrator fetches each Agent Card from:
+
+```text
+/.well-known/agent-card.json
+```
+
+Then it sends review work to:
+
+```text
+/message:stream
+```
+
+Each agent streams task state updates and returns a markdown artifact. Later agents receive the artifacts that earlier agents produced, so the review evolves over multiple rounds.
+
+## Review a Real Issue
+
+By default the demo uses an offline sample issue so it can run without GitHub API access. Point it at any public GitHub issue with `DEMO_ISSUE_URL`:
+
+```shell
+DEMO_ISSUE_URL=https://github.com/NVIDIA/OpenShell/issues/123 \
+  bash examples/a2a-design-review/demo.sh
+```
+
+To use the latest open issue from a repository:
+
+```shell
+DEMO_USE_SAMPLE_ISSUE=0 DEMO_REPO=NVIDIA/OpenShell \
+  bash examples/a2a-design-review/demo.sh
+```
+
+Set `GITHUB_TOKEN` or `GH_TOKEN` if you need higher API rate limits or private repository access. The token is used by the host-side orchestrator to fetch issue text; the remote worker agents do not receive it.
+
+## Inspect the Artifact
+
+The demo writes a markdown review under `examples/a2a-design-review/` by default. Set `DEMO_OUTPUT` to choose a different path:
+
+```shell
+DEMO_OUTPUT=/tmp/a2a-design-review.md \
+  bash examples/a2a-design-review/demo.sh
+```
+
+The artifact includes:
+
+- The issue title and URL.
+- The discovered A2A agents and their skills.
+- A round-by-round transcript of planner, security, implementation, and critic artifacts.
+
+## Understand the Boundary
+
+The worker sandbox policy grants no outbound network access. The workers receive A2A messages through OpenShell service routing and return artifacts on the same request path.
+
+For a production version, keep the A2A communication policy separate from tool and storage policies:
+
+- Allow only the A2A discovery, message, stream, and task paths between agents.
+- Attach GitHub or other tool providers only to agents that need them.
+- Scope write access to one repository path or API operation.
+- Treat Agent Cards, messages, artifacts, and task status as untrusted input before placing them into model context.
+
+A2A handles collaboration. OpenShell defines what each collaborator can actually call, know, and change.
+
+</Steps>

docs/get-started/tutorials/index.mdx

@@ -22,6 +22,11 @@ Create a sandbox, observe default-deny networking, apply a read-only L7 policy,
 Launch Claude Code in a sandbox, diagnose a policy denial, and iterate on a custom GitHub policy from outside the sandbox.
 </Card>
 
+<Card title="A2A Design Review" href="/get-started/tutorials/a2a-design-review">
+
+Run multiple A2A-compatible agents in isolated sandboxes and have them review a GitHub issue together.
+</Card>
+
 <Card title="Inference with Ollama" href="/get-started/tutorials/inference-ollama">
 
 Route inference through Ollama using cloud-hosted or local models, and verify it from a sandbox.

examples/a2a-design-review/README.md

@@ -0,0 +1,132 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# A2A Design Review Demo
+
+Run a small mesh of A2A-compatible agents that collaborate on a GitHub issue
+from different perspectives. Each remote agent exposes an Agent Card, streams
+task updates, and returns a markdown artifact. The orchestrator builds a
+round-by-round design review from those artifacts.
+
+This is the next step after the multi-agent GitHub notepad example:
+
+- The notepad demo uses GitHub files as durable shared coordination state.
+- This demo uses A2A messages, tasks, streams, and artifacts as the live
+  coordination layer.
+- OpenShell keeps each remote agent isolated and gives each agent only the
+  policy and credentials it needs.
+
+## What This Demo Shows
+
+The demo starts four A2A agents:
+
+| Agent | Role |
+|---|---|
+| Planner | Frames the issue and turns critique into the next plan. |
+| Security | Reviews credential flow, sandbox policy, prompt injection, and data exfiltration risk. |
+| Implementation | Maps the review into concrete implementation and validation steps. |
+| Critic | Challenges weak claims and synthesizes the strongest next artifact. |
+
+The agents run multiple rounds. Each agent receives the GitHub issue and the
+artifacts already produced by earlier agents, then streams its own task status
+and artifact back to the orchestrator.
+
+```text
+planner -> security -> implementation -> critic
+   ^                                      |
+   |------------- next round -------------|
+```
+
+## Why A2A Fits OpenShell
+
+A2A provides the collaboration protocol. OpenShell provides the boundary.
+
+The first version of this demo uses A2A's HTTP+JSON binding because it maps
+cleanly to OpenShell policy. A future sandboxed orchestrator can be allowed to
+fetch only:
+
+- `GET /.well-known/agent-card.json`
+- `POST /message:send`
+- `POST /message:stream`
+- selected task paths such as `GET /tasks/**`
+
+That gives users an understandable policy story: agents can talk to each other
+through A2A, but they do not inherit each other's filesystem, provider
+credentials, model credentials, or unrelated network access.
+
+## Files
+
+| File | Description |
+|---|---|
+| `demo.sh` | Starts the local smoke or OpenShell sandbox demo. |
+| `a2a-agent.mjs` | Minimal A2A HTTP+JSON remote agent with Agent Card discovery and SSE streaming. |
+| `orchestrator.mjs` | Host-side A2A client agent that drives multiple review rounds. |
+| `policy.yaml` | Restrictive OpenShell policy for remote worker agents. |
+| `sample-issue.json` | Offline issue fixture for the default smoke run. |
+
+## Quick Smoke Test
+
+Prerequisite: Node.js 18 or newer.
+
+Run the protocol flow locally without a gateway:
+
+```shell
+DEMO_LOCAL_ONLY=1 bash examples/a2a-design-review/demo.sh
+```
+
+The smoke test starts four local A2A servers, runs two collaboration rounds,
+and writes a markdown review artifact under `examples/a2a-design-review/`.
+
+## Run With OpenShell
+
+Start a gateway, then run the sandboxed version:
+
+```shell
+mise run gateway:docker
+bash examples/a2a-design-review/demo.sh
+```
+
+The script creates one OpenShell sandbox per remote A2A agent, exposes each
+agent's HTTP service through the gateway, discovers each Agent Card, and runs
+the design-review loop from the host.
+
+By default the demo uses `sample-issue.json` so it can run without GitHub API
+access. Point it at a real open issue by setting `DEMO_ISSUE_URL`:
+
+```shell
+DEMO_ISSUE_URL=https://github.com/NVIDIA/OpenShell/issues/123 \
+  bash examples/a2a-design-review/demo.sh
+```
+
+If you do not provide `DEMO_ISSUE_URL` and want the script to use the latest
+open issue from a repository, disable the sample fixture:
+
+```shell
+DEMO_USE_SAMPLE_ISSUE=0 DEMO_REPO=NVIDIA/OpenShell \
+  bash examples/a2a-design-review/demo.sh
+```
+
+Optional settings:
+
+```shell
+export DEMO_ROUNDS=3
+export DEMO_OUTPUT=/tmp/a2a-design-review.md
+export DEMO_KEEP_SANDBOXES=1
+```
+
+## Security Model
+
+The worker policy grants no outbound network access. The workers receive A2A
+messages through OpenShell service routing and return artifacts through the
+same request path.
+
+For a fuller version where the orchestrator also runs inside a sandbox, give
+the orchestrator a separate policy that allows only the remote A2A service
+URLs and the specific A2A REST paths it needs. If the final artifact should be
+written to GitHub, attach a separate GitHub provider and scope the policy to
+one repository path, as in the multi-agent notepad demo.
+
+Treat all A2A inputs as untrusted: Agent Cards, messages, artifacts, and task
+status can carry prompt-injection content. The orchestrator should summarize
+or sanitize remote artifacts before using them as model context in a
+production workflow.