feat: add SDK examples workspace

Author: nficano

.env.example

@@ -0,0 +1,43 @@
+# =============================================================================
+# arcp sdk-examples — canonical configuration
+# =============================================================================
+# This is the master list of knobs shared across every language example.
+# Each language directory has its own `.env.example` with the same defaults
+# plus language-specific additions.
+#
+# Usage:
+#   cp .env.example .env
+#   # edit .env as needed
+#   make up
+# -----------------------------------------------------------------------------
+
+# --- LLM (Ollama) ------------------------------------------------------------
+# Small + decent reasoning + tool calling. Alternatives:
+#   qwen2.5:0.5b           ~400MB  fastest, weakest reasoning
+#   qwen2.5:1.5b-instruct  ~1GB    DEFAULT — balanced
+#   qwen3:0.6b             ~520MB  native thinking mode
+#   llama3.2:1b            ~1.3GB  strong instruction following
+#   phi3:mini              ~2.2GB  stronger reasoning, slower
+OLLAMA_MODEL=qwen2.5:1.5b-instruct
+OLLAMA_URL=http://ollama:11434
+OLLAMA_KEEP_ALIVE=5m
+OLLAMA_NUM_CTX=4096
+
+# --- ARCP runtime ------------------------------------------------------------
+ARCP_RUNTIME_HOST=0.0.0.0
+ARCP_RUNTIME_PORT=8080
+ARCP_RUNTIME_PATH=/arcp
+ARCP_AUTH_TOKEN=dev-token-change-me
+
+# Pin a specific SDK release for reproducible builds, or leave `latest`.
+ARCP_SDK_VERSION=latest
+
+# --- ARCP client -------------------------------------------------------------
+ARCP_CLIENT_NAME=sdk-examples-client
+ARCP_CLIENT_VERSION=1.0.0
+ARCP_CLIENT_TIMEOUT_MS=30000
+ARCP_AGENT_NAME=demo
+
+# --- Observability -----------------------------------------------------------
+# trace | debug | info | warn | error
+LOG_LEVEL=info

.github/workflows/verify.yml

@@ -0,0 +1,26 @@
+name: verify examples
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  verify:
+    name: verify ${{ matrix.language }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [fsharp, java, php, ruby]
+
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build ${{ matrix.language }} example
+        run: make verify-${{ matrix.language }}

.gitignore

@@ -0,0 +1,88 @@
+# env files
+.env
+.env.local
+**/.env
+!**/.env.example
+SOUL.md
+**/PROMPT.md
+
+# OS
+.DS_Store
+Thumbs.db
+
+# editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# logs
+*.log
+logs/
+out/
+**/out/
+reports/
+**/reports/
+loot/
+**/loot/
+work/
+**/work/
+
+# language: node
+node_modules/
+*.tsbuildinfo
+dist/
+.npm/
+.pnpm-store/
+
+# language: python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+env/
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# language: go
+bin/
+*.test
+*.out
+
+# language: rust
+target/
+Cargo.lock.bak
+
+# language: java/kotlin
+*.class
+*.jar
+*.war
+build/
+.gradle/
+target/
+
+# language: csharp/fsharp
+obj/
+bin/
+
+# language: ruby
+.bundle/
+vendor/bundle/
+*.gem
+
+# language: php
+vendor/
+composer.phar
+
+# language: swift
+.build/
+.swiftpm/
+Packages/
+*.xcodeproj/
+
+# docker
+.docker/
+ollama-data/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent Runtime Control Protocol contributors
+
+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.

Makefile

@@ -0,0 +1,64 @@
+# =============================================================================
+# arcp sdk-examples — top-level orchestration
+# =============================================================================
+# Per-language targets are defined below. Pattern targets fan out so you can
+# also run `make up-python`, `make logs-rust`, etc.
+# -----------------------------------------------------------------------------
+
+LANGS := csharp fsharp go java kotlin php python ruby rust swift typescript
+
+.DEFAULT_GOAL := help
+
+.PHONY: help
+help:  ## Show this help
+	@echo "arcp sdk-examples — top-level commands"
+	@echo
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_%-]+:.*?## / {printf "  \033[36m%-22s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+	@echo
+	@echo "Per-language commands (substitute any of: $(LANGS)):"
+	@echo "  make up-<lang>           # docker compose up for one language"
+	@echo "  make down-<lang>         # docker compose down"
+	@echo "  make logs-<lang>         # tail container logs"
+	@echo "  make verify-<lang>       # docker build only — proves @latest install"
+	@echo "  make shell-<lang>        # exec into the client container"
+
+.PHONY: verify
+verify:  ## docker build every language (proves @latest installs cleanly)
+	@for lang in $(LANGS); do \
+		echo "==> verify $$lang"; \
+		$(MAKE) verify-$$lang || exit 1; \
+	done
+	@echo
+	@echo "All languages verified."
+
+.PHONY: clean
+clean:  ## Remove all built images, containers, and volumes
+	@for lang in $(LANGS); do \
+		echo "==> clean $$lang"; \
+		$(MAKE) -C $$lang clean 2>/dev/null || true; \
+	done
+	@docker volume ls -q --filter "name=sdk-examples" | xargs -r docker volume rm || true
+
+.PHONY: ls
+ls:  ## List languages
+	@printf '%s\n' $(LANGS)
+
+# --- pattern targets ---------------------------------------------------------
+
+up-%:
+	@$(MAKE) -C $* up
+
+down-%:
+	@$(MAKE) -C $* down
+
+logs-%:
+	@$(MAKE) -C $* logs
+
+verify-%:
+	@$(MAKE) -C $* verify
+
+shell-%:
+	@$(MAKE) -C $* shell
+
+build-%:
+	@$(MAKE) -C $* build

README.md

@@ -0,0 +1,127 @@
+# arcp sdk-examples
+
+End-to-end, containerized examples for every ARCP SDK. Each subdirectory is a self-contained, configurable demo: an Ollama-backed local LLM, an ARCP runtime hosting an agent, and an ARCP client driving it.
+
+## What this repo is for
+
+1. **Drop-in e2e setup.** `git clone`, `cd <language>`, `make up`. You get a local LLM, an ARCP runtime, and a client wired together. No external services, no API keys.
+2. **`@latest` install proof.** Every Dockerfile pulls the SDK at the latest published version from each ecosystem's package registry. If a build is red, the SDK shipped broken — not the example.
+
+## Languages
+
+| Language                  | Example theme                                   | Package                                         | Install                                                           |
+| ------------------------- | ----------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------- |
+| [csharp](csharp/)         | ASP.NET Core background worker queue            | `Arcp`                                          | `dotnet add package Arcp`                                         |
+| [fsharp](fsharp/)         | Classical cipher cryptanalysis                  | `Arcp`                                          | `dotnet add package Arcp`                                         |
+| [go](go/)                 | Concurrent batch document summarizer            | `github.com/agentruntimecontrolprotocol/go-sdk` | `go get github.com/agentruntimecontrolprotocol/go-sdk@latest`     |
+| [java](java/)             | Disinformation network mapping (Spring Boot + Spark) | `io.agentruntimecontrolprotocol:arcp`      | `mvn` / `gradle` (see [java/README.md](java/README.md))           |
+| [kotlin](kotlin/)         | Coroutine async data pipeline                   | `dev.arcp:arcp`                                 | `gradle` (see [kotlin/README.md](kotlin/README.md))               |
+| [php](php/)               | Phishing-kit teardown sandbox                   | `arcp/sdk`                                      | `composer require arcp/sdk`                                       |
+| [python](python/)         | Multi-agent code reviewer (security/perf/style) | `agentruntimecontrolprotocol`                   | `pip install agentruntimecontrolprotocol`                         |
+| [ruby](ruby/)             | Authorized CTF post-exploitation orchestrator (lab-only) | `arcp`                                 | `gem install arcp`                                                |
+| [rust](rust/)             | High-throughput embedding pipeline              | `arcp`                                          | `cargo add arcp`                                                  |
+| [swift](swift/)           | macOS async/await tool-calling agent            | `ARCP` (SwiftPM)                                | `swift package add ARCP` (see [swift/README.md](swift/README.md)) |
+| [typescript](typescript/) | Darknet threat-intel crawler (lab `.onion`)     | `@agentruntimecontrolprotocol/sdk`              | `npm install @agentruntimecontrolprotocol/sdk`                    |
+
+## Quickstart
+
+```sh
+# Pick a language
+cd python
+
+# Copy and edit configuration (optional — sensible defaults provided)
+cp .env.example .env
+
+# Bring everything up: Ollama pulls model, runtime starts, client runs
+make up
+
+# Tear down
+make down
+```
+
+## How each example is wired
+
+Three containers per example, all defined in that language's `docker-compose.yml`:
+
+```
+┌──────────────┐  ws/arcp  ┌──────────────┐  http  ┌──────────────┐
+│ arcp-client  │──────────▶│ arcp-runtime │───────▶│   ollama     │
+│  (your code) │           │ (hosts agent)│        │ (local LLM)  │
+└──────────────┘           └──────────────┘        └──────────────┘
+```
+
+- **`ollama`** — pulls a small model on first start (default: `qwen2.5:1.5b-instruct`, ~1GB), serves OpenAI-compatible inference.
+- **`arcp-runtime`** — your language's SDK runtime, hosting a registered agent function. Talks to Ollama for reasoning.
+- **`arcp-client`** — your language's SDK client, submitting jobs to the runtime and consuming streamed events.
+
+## Configurability is the point
+
+Every example reads from `.env`. Common knobs (set across all languages):
+
+| Variable            | Default                 | Notes                                                  |
+| ------------------- | ----------------------- | ------------------------------------------------------ |
+| `OLLAMA_MODEL`      | `qwen2.5:1.5b-instruct` | Try `qwen2.5:0.5b` (tiny) or `qwen3:0.6b` (reasoning). |
+| `OLLAMA_URL`        | `http://ollama:11434`   | Point elsewhere to use a remote inference host.        |
+| `OLLAMA_KEEP_ALIVE` | `5m`                    | How long Ollama keeps the model loaded.                |
+| `ARCP_RUNTIME_HOST` | `0.0.0.0`               | Bind address inside the runtime container.             |
+| `ARCP_RUNTIME_PORT` | `8080`                  | Runtime listen port.                                   |
+| `ARCP_RUNTIME_PATH` | `/arcp`                 | WebSocket path.                                        |
+| `ARCP_AUTH_TOKEN`   | `dev-token-change-me`   | Bearer token. **Change for non-local use.**            |
+| `ARCP_SDK_VERSION`  | `latest`                | Pin a specific SDK release for reproducible builds.    |
+| `ARCP_AGENT_NAME`   | varies                  | Logical name registered by the runtime.                |
+| `LOG_LEVEL`         | `info`                  | `trace` / `debug` / `info` / `warn` / `error`.         |
+
+Each language adds example-specific knobs (e.g. `REVIEW_TARGET`, `BATCH_SIZE`, `STREAM_CHUNK_SIZE`). See each `.env.example`.
+
+## Model choices
+
+Default is **`qwen2.5:1.5b-instruct`** — ~1GB, supports tool calling, runs on CPU at a few tokens/sec on modern laptops. Three documented alternatives:
+
+| Model                      | Size   | Strengths                    |
+| -------------------------- | ------ | ---------------------------- |
+| `qwen2.5:0.5b`             | ~400MB | Fastest, weakest reasoning   |
+| `qwen2.5:1.5b-instruct` ⭐ | ~1GB   | Default — balanced           |
+| `qwen3:0.6b`               | ~520MB | Native thinking mode         |
+| `llama3.2:1b`              | ~1.3GB | Strong instruction following |
+| `phi3:mini`                | ~2.2GB | Stronger reasoning, slower   |
+
+Override with `OLLAMA_MODEL=...` in your `.env`.
+
+## Top-level commands
+
+From the repo root:
+
+```sh
+make help        # List per-language targets
+make verify      # docker build every language to prove @latest installs
+make verify-py   # Verify a single language (also: verify-ts, verify-go, ...)
+make clean       # Remove all built images and volumes
+```
+
+## Repo layout
+
+```
+sdk-examples/
+├── README.md                  # this file
+├── Makefile                   # top-level orchestration
+├── LICENSE
+├── .gitignore
+├── .env.example               # canonical list of all knobs
+├── shared/
+│   ├── ollama-entrypoint.sh   # pulls model on first boot
+│   └── docker-compose.ollama.yml
+└── <language>/
+    ├── Dockerfile             # alpine-based where supported
+    ├── docker-compose.yml     # extends shared/docker-compose.ollama.yml
+    ├── Makefile               # up/down/logs/shell/verify
+    ├── README.md              # what this example demonstrates
+    ├── .env.example           # language-specific knobs
+    ├── .dockerignore
+    ├── <build manifest>       # package.json / pyproject.toml / etc.
+    └── src/
+        └── .gitkeep           # your example code goes here
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

csharp/.dockerignore

@@ -0,0 +1,6 @@
+.env
+.env.local
+bin/
+obj/
+*.log
+.git/