v2.5.0 — A2A Protocol

A2A Protocol

Google Agent2Agent protocol implementation: server mode for receiving task requests, client mode for delegating to remote agents, streaming, multi-turn INPUT_REQUIRED, and push notifications.

Server

• REST endpoints via MapHttpA2A(), public agent card at /.well-known/agent-card.json
• Task processing bridged to AgentStepExecutor with RBAC
• JSONL persistence with ConcurrentDictionary envelope pattern
• TTL + cap eviction of terminal tasks
• AgentStepExecutor.StreamAsync with 5 StreamEvent variants
• INPUT_REQUIRED via complete-and-re-execute pattern
• Push notifications bridged to WebhookDeliveryWorker

Client

• Streaming delegation default, sync fallback from agent card capabilities
• Single a2a_delegate tool with dynamic description from registry
• Local depth enforcement + cooperative metadata propagation (chainId, depth, maxDepth)

Observability

• 12 OTel attribute constants + 4 delegation metadata keys
• 4 metric instruments on Clawsharp.A2a meter
• Span wrapping with error status propagation

47 files, +8,188 lines. 234 new tests. Reviewed at 7.5/10.

v2.4.0 — Knowledge Ingestion Pipeline

Knowledge Ingestion Pipeline

Full RAG pipeline: plugin system with Ed25519 integrity verification, document loading, chunking, batch embedding, hybrid search with RRF fusion across 5 backends, and reranking.

Plugin System

• AssemblyLoadContext-isolated plugins with Ed25519 + SHA-256 verification
• clawsharp-sign CLI for keypair generation, signing, verification
• 5 first-party plugins: Confluence, Git, S3, Azure Blob, GCS

Document Loading & Chunking

• 5 built-in loaders: plaintext, Markdown, PDF, HTML, DOCX
• Recursive character chunker + heading-aware chunker with token-based sizing
• Batch embedding with Polly retry and bounded parallelism

Ingestion

• Per-document SHA-256 delta detection + Merkle rollup
• Background worker with bounded Channel
• SyncStateTracker with CAS transitions

Retrieval

• Hybrid FTS + vector search with RRF fusion across all 5 backends
• IReranker with PassThrough and Cohere implementations
• KnowledgeSearchTool for LLM-integrated RAG queries

Observability

• knowledge.ingest/load/chunk/embed/store spans
• Embedding latency histogram, chunks ingested counter, documents failed counter

158 files, +18,617 lines. 326 new tests. Reviewed at 8.3/10.

v2.3.0 — Webhook / Event System

Webhook / Event System

Outbox-pattern webhook delivery engine with HTTP + channel routing, HMAC signing, circuit breakers, DLQ with replay, and SSE dashboard.

Delivery

• Per-endpoint bounded channels with Polly retry + circuit breaker
• HMAC-SHA256 signing (ULID + timestamp headers)
• 4 formatters: JSON, Slack Block Kit, Discord embed, Teams Adaptive Card
• Outbox crash recovery, 429 Retry-After honoring, DLQ with single + batch replay

HTTP API

• /webhooks/status — endpoint health + circuit state
• /webhooks/dlq — browse + replay dead letter queue
• /webhooks/stream — SSE delivery event stream
• All routes: BearerTokenAuthFilter + AdminRoleFilter

Observability

• 13 OTel attribute constants, webhook.dispatch / webhook.deliver spans
• 4 metric instruments (delivered/failed counters, duration histogram, DLQ depth gauge)

81 files, +11,730 lines. Reviewed at 8.4/10.

v2.2.0 — MCP Server Mode

MCP Server Mode

Model Context Protocol server allowing AI assistants (Claude Desktop, Cursor, Copilot) to connect and use clawsharp's 22+ tools via StreamableHTTP transport.

Authentication

• Constant-time API key comparison with JWT fallback
• Origin allowlist with wildcard support
• Per-session RBAC: tools filtered by org policy

SDK Integration

• ModelContextProtocol.AspNetCore 1.1.0 StreamableHTTP on /mcp
• Tool annotation mapping (readOnly, destructive, idempotent, openWorld)
• Per-connection tool registration with RBAC filtering

Observability

• McpAttributes (6 OTel constants), McpExecutionContext (AsyncLocal)
• mcp.session.init span, tool.execute MCP enrichment
• Zero-cost CostRecord per tool call

34 files, +3,193 lines. 100 new tests. Reviewed at 8.4/10.

v2.1.0 — OpenTelemetry + Semantic Traces

OpenTelemetry + Semantic Traces

Full observability layer: distributed tracing with GenAI semantic conventions, 9 source-generated metric instruments, streaming latency histograms, and OTLP export.

Tracing

• 5 named ActivitySource instances: Pipeline, Providers, Tools, Memory, Channels
• Root message.process span per inbound message with pipeline stage children
• gen_ai.chat LLM spans with GenAI semantic convention attributes (model, token counts, finish reason)
• tool.execute spans with tool name, sensitivity, duration
• SpanIsolation for background tasks (null parent + ActivityLink)
• Audit-trace correlation via creation-time context snapshot

Metrics

• Token usage histogram (input/output/cache by model)
• LLM operation duration histogram
• Active sessions gauge
• Tool execution counter + duration histogram
• TTFT (time to first token) histogram
• TPOT (time per output token) histogram
• StreamingMetricsHelper for streaming latency decomposition
• ModelFamilyNormalizer for cardinality-safe model tags

Configuration

• TelemetryConfig with 9 properties (OTLP endpoint, protocol, sampling, content capture)
• 0.1 default sampling rate, HTTP/protobuf default protocol
• Zero overhead when disabled (null-gated enrichment throughout)

46 files, +4,867 lines. Reviewed at 8.5/10 aesthetic score.

v2.0.0 — Org Policy Engine

Org Policy Engine

Complete organizational policy engine with RBAC + ABAC access control, identity resolution, approval workflows, budget enforcement, and OIDC authentication.

New Subsystems

• IdentityResolver — maps channel:senderId to OrgUser via FrozenDictionary with atomic snapshot swap
• PolicyEvaluator — RBAC role merge + ABAC condition overlay (deny-override)
• PolicyDecision — 6-step tool/model access evaluation
• ApprovalQueue — CAS-based state machine for tool approval workflows
• AdminNotifier — multi-channel admin notifications
• OidcService — PKCE S256, JWKS rotation retry, nonce validation
• AgentStepExecutor — lightweight tool loop for sub-agent execution
• IEventBus — copy-on-write pub/sub with immutable subscription lists
• HttpHostService — shared Kestrel host with IHttpRouteRegistrar pattern

Slash Commands

• /policy explain [tool] — explain current user's access rights
• /policy simulate <user> <tool> — simulate policy evaluation
• /policy approve|deny|cancel <id> — manage approval requests
• /org link — OIDC account linking
• /org whoami — show resolved identity

Security

• OIDC: PKCE S256 + state cookie + nonce validation + JWKS rotation
• Constant-time comparisons throughout
• SpawnPermissionScope: never-escalate privilege enforcement

159 files, +20,890 lines. Reviewed at 8.4/10 aesthetic score.

v1.5.0 — Dedicated OpenRouter Provider

What's New

Dedicated OpenRouter Provider

OpenRouter now has a full native provider instead of routing through the generic OpenAI passthrough. One API key gives you access to 200+ models with native cost tracking, multimodal support, and account management.

Setup:

{
  "agents": { "defaults": { "provider": "openrouter", "model": "anthropic/claude-sonnet-4" } },
  "providers": { "openrouter": { "type": "openrouter", "apiKey": "sk-or-v1-..." } }
}

Features

Cost Passthrough

• Provider-reported USD cost flows through the entire pipeline: ChatResponse → StreamUsageChunk → LoopResult → RecordUsage → CostTracker
• CostTracker prefers provider-reported cost over token-based pricing estimates

Slash Commands

• /usage — Shows local cost tracking + OpenRouter credits remaining, credit limit, daily/monthly/total usage
• /models [search] — Lists available models with context length and per-1M-token pricing, with substring filtering

Multimodal Support

• Image generation — modalities: ["image", "text"] for image-capable models, delivered via PendingFileStore → IFileChannel
• PDF/file input — FileAttachment with 8 MIME types (PDF, text, CSV, markdown, JSON, HTML, XML), Telegram document upload
• Audio input — AudioAttachment with native input_audio content parts, Telegram/Discord retain raw bytes alongside transcription
• Audio output — Streaming delta.audio chunks accumulated and delivered as audio files with correct format extension
• Video input — VideoAttachment with video_url content parts (base64 data URLs + HTTPS URLs)

Error Handling

• Mid-stream SSE errors (finish_reason: "error" + top-level error object)
• Per-choice errors on non-streaming responses
• Base64 decoding resilience (try-catch on image/audio prevents pipeline crashes)

Privacy

• Zero Data Retention — ZeroDataRetention + DataCollection fields on provider preferences
• Only routes to endpoints that won't store or train on your data

Architecture

• MessageContentBuilder — Fluent builder for multimodal message content, shared across OpenAI + OpenRouter providers
• Performance optimized — Constant URL, pre-sized List + foreach (no LINQ on hot paths), explicit JsonDocument disposal, zero-alloc MIME-to-format conversion
• Health check via GET /api/v1/key — validates API key AND shows credits remaining

Documentation

• OpenRouter setup guide with config examples and feature table
• OPENROUTER_API_KEY in .env.example
• In-channel slash commands reference table (all 11 commands)
• Full comparison matrix rows for all new features
• Sibling project OpenRouter support levels updated

Quality

• 299 new tests (2,326 total, 0 regressions)
• 3 review passes: aesthetic architecture, rigorous code review, performance scan
• All HIGH/MEDIUM/LOW findings addressed and verified
• 73 handler-level slash command tests via SlashCommandHarness
• 54 files changed, +7,113 / -85 lines

Breaking Changes

None. The existing OpenAI-compatible routing for type: "openrouter" is replaced by the dedicated provider transparently.

---

Full Changelog: v1.4.5...v1.5.0

v1.4.5

What's New

Sibling Feature Sync (from openclaw, nanobot, nullclaw, picoclaw, zeroclaw)

• /model slash command — session-persistent runtime model switching
• Custom provider headers (extraHeaders) — with auth header duplication guard
• API key rotation (apiKeys) — thread-safe round-robin via shared ApiKeyRotator
• Configurable sub-agent timeout (spawnTimeout) — replaces hardcoded 60s, with upper-bound clamp at 24h
• Background memory consolidation — fire-and-forget with message snapshot (race condition fix)

Redis Memory Backend (5th backend)

• memory.backend: "redis" with RediSearch FT index for full-text search
• Optional HNSW vector index for hybrid search
• Hash-based storage (clawsharp:fact:{id}) with decay scoring
• 34 integration tests + 8 E2E tests via Testcontainers

Testing & Quality

• 76 new regression tests covering 11 historical bugs across PRs #1–#12
• 32 E2E memory tests across all 4 backends (SQLite, Postgres, MsSql, Redis)
• 10 hybrid search tests with case-insensitive coverage for Postgres/MsSql
• All regression tests call real production code (no logic duplication)
• SpawnTimeout upper-bound guard fixes TimeSpan.MaxValue crash
• WebChannel.NormalizeIp made testable via internal visibility
• ToolRegistry test constructor for error sanitization verification
• Total: 2,027 non-integration tests, 0 failures

Bug Fixes

• Auth header duplication guard on ExtraHeaders (case-insensitive)
• ApiKeyRotator off-by-one index initialization
• SlashCommandRouter unconditional argument passing for all commands
• ComputeHybridScore DRY extraction in Redis backend
• _vectorSearchEnabled marked volatile for thread safety

Full Changelog

v1.4.4...v1.4.5

v1.4.4

What's Changed

Configurable Network Egress Policy

• Deny-by-default egress allowlist — new security.egress config section inspired by NVIDIA OpenShell's security model
• Two modes: open (default, unchanged behavior) and allowlist (only explicitly listed hosts permitted)
• Wildcard host patterns (*.example.com), optional port restrictions, case-insensitive matching
• Dual-layer enforcement: pre-flight URI validation (SsrfGuard.CheckAsync) and TCP connect time (CreateConnectCallback)
• ConfigValidator warns on: allowlist with no rules, whitespace in hosts, bare * wildcard, invalid ports
• LLM provider traffic exempt from egress policy (admin-configured endpoints, not user-controlled)
• 32 new unit tests

OpenShell Sandbox Support

• deploy/openshell/sandbox-policy.yaml — reference policy for running clawsharp inside NVIDIA OpenShell with filesystem isolation, network egress rules, and process restrictions
• Dockerfile: commented env var for inference.local transparent inference routing
• README: new "OpenShell Deployment" and "Network egress policy" sections
• Comparison Table: added Network egress policy and OpenShell sandbox rows (clawsharp exclusives)

CI Pipeline Fix

• Fixed .NET 10 MSBuild glob expansion bug on GitHub Actions runners where **/*.cs was passed literally to CSC (error CS2021)
• Workaround: when CI=true, enumerate source files via Directory.GetFiles() instead of relying on broken glob expansion
• Added global.json pinning SDK version
• Removed RuntimeIdentifiers from csproj (pass -r at publish time)

Full Changelog: v1.4.3...v1.4.4

v1.4.3

What's Changed

• Integration test fixes

  • Restore SQLite WORM triggers destroyed by AlterColumn table rebuild
  • Add RestoreWormTriggers migration to recreate triggers with IF NOT EXISTS
  • Add safety net in InitSchemaAsync to ensure triggers exist on every startup
  • Fix AccessCount not incrementing on LIKE/ILIKE fallback search path
  • Disable InvariantGlobalization in test project (required by SqlClient and pgvector)
  • Add Pgvector.EntityFrameworkCore package for UseVector() support
  • Rewrite SimpleDbContextFactory to fix PostgresMemoryContext constructor mismatch

• Docker image upgrades

  • Upgrade Postgres 16 → 18, pgvector pg17 → pg18-trixie
  • Upgrade SQL Server 2022 → 2025

• CI/CD pipeline

  • Add ci.yml workflow (build + unit tests on PR)
  • Add integration-tests.yml manual workflow
  • Fix MSBuild glob expansion failure in CI
  • Add LM Studio round-trip tests with configurable OLLAMA_HOST env var

Co-Authored-By: Claude Opus 4.6 noreply@anthropic.com