github.com/Kocoro-lab/Shannon

Shannon v0.5.1

Docker Images

docker pull waylandzhang/gateway:v0.5.1
docker pull waylandzhang/orchestrator:v0.5.1
docker pull waylandzhang/agent-core:v0.5.1
docker pull waylandzhang/llm-service:v0.5.1
docker pull waylandzhang/playwright-service:v0.5.1

Quick Start

curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Shannon/main/scripts/install.sh | bash

Full Changelog

See CHANGELOG.md

Fixed

• One-command install failing on Apple Silicon / arm64 hosts — agent-core is published amd64-only, so docker compose pull errored with no matching manifest for linux/arm64. The release compose now pins agent-core to platform: linux/amd64, so arm64 hosts pull the amd64 image and run it under emulation. (Pre-existing since v0.4.0.)

Shannon v0.5.0

Docker Images

docker pull waylandzhang/gateway:v0.5.0
docker pull waylandzhang/orchestrator:v0.5.0
docker pull waylandzhang/agent-core:v0.5.0
docker pull waylandzhang/llm-service:v0.5.0
docker pull waylandzhang/playwright-service:v0.5.0

Quick Start

curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Shannon/main/scripts/install.sh | bash

Full Changelog

See CHANGELOG.md

Added

• LiteLLM embedded provider — use LiteLLM as an in-process AI gateway, broadening provider coverage (tool deltas, cache TTL split, timeout, reasoning, alias support)
• xAI x_search tool — native X/Twitter search with cache-aware billing
• MiniMax M3 model support (512K context, 128K max output, vision-capable) — new default minimax model in the medium and large tier priority lists; M2.7 and M2.7-highspeed remain available
• Anthropic 1M context — claude-sonnet-4-6 and claude-opus-4-6 context windows raised to 1M (native, no beta header)
• Content-blocks passthrough — ordered content_blocks relayed end-to-end through cache and streaming paths to clients
• Attachment MIME classification — three-way MIME classification, raised caps, and a dangerous-filename gate
• Python SDK v0.7.0 — API parity and session fixes, E2E verified

Changed

• Cache-aware quota and billing — 1h vs 5m cache-creation TTL routing, cache-aware token aggregation and quota enforcement across budget, gateway, research, swarm, and session pricing (adds cache_aware_total_tokens column)
• Promoted gpt-5.1 to priority 1 in the large tier
• Raised conservative limits for 1M-context power users (web_fetch/web_crawl/web_subpage_fetch and agent text caps; MAX_PROMPT_CHARS = 1M)
• playwright-service is now optional via the browser compose profile

Fixed

• Missing gRPC runtime files (*_pb2.py/*_pb2_grpc.py) absent from source tags, causing llm-service image import failures — runtime files (protobuf 5.x) are now committed (#173)
• Gateway returning spurious 429s due to a redundant per-model rate limiter; per-provider rate limiter disabled by default
• Uniform cache-TTL enforcement to prevent Anthropic 1h/5m mixing returning 400
• Desktop module-not-found errors — track desktop/lib/ TypeScript libraries

Shannon v0.4.1

Docker Images

docker pull waylandzhang/gateway:v0.4.1
docker pull waylandzhang/orchestrator:v0.4.1
docker pull waylandzhang/agent-core:v0.4.1
docker pull waylandzhang/llm-service:v0.4.1
docker pull waylandzhang/playwright-service:v0.4.1

Quick Start

curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Shannon/main/scripts/install.sh | bash

Full Changelog

See CHANGELOG.md

Fixed

• Gateway auth bypass failing when .env values contain trailing whitespace — GATEWAY_SKIP_AUTH=1 with ENVIRONMENT=dev now works reliably
• Proto generation (make setup) failing on macOS/Linux with Python 3.12+ due to PEP 668 externally-managed-environment — now uses a dedicated venv

Shannon v0.4.0 — Consolidated Platform Release

Complete platform consolidation — the full Shannon multi-agent AI platform in a single, clean release.

Major Features Added

• OAuth2 authentication — Google provider, JWT tokens, API key management
• Attachments & multimodal — image/file uploads, OpenAI-compatible content blocks
• Agent workflow — dedicated single-agent execution with tool calling
• BrowserUse strategy — browser automation as a first-class execution strategy
• DomainAnalysis strategy — structured domain research with multi-source analysis
• Daemon approval routing — HITL approval dispatch through WebSocket daemon
• Scheduled task dispatch — daemon channel routing for scheduled results
• Workspace quotas — per-tenant retention and size limits
• Playwright SSRF protection — hostname validation and private IP blocking
• Firecracker executor — guest-agent, VM pool, vsock, workspace sync
• New gateway endpoints — `/agents`, `/llm-models`, `/memory/files`
• Rate limits config — externalized to `config/rate_limits.yaml`
• MiniMax provider — first-class dedicated provider
• Kimi (Moonshot AI) — new provider support
• Python SDK — `pip install shannon-ai` with streaming, sessions, workflow routing
• Desktop app (Tauri v2) — real-time execution timeline, research visualization
• Release tooling — one-command installer, Docker Hub multi-arch images, CI/CD
• Prompt cache optimization — Anthropic models, 1h TTL, multi-turn support

Docker Images

```bash
docker pull waylandzhang/gateway:v0.4.0
docker pull waylandzhang/orchestrator:v0.4.0
docker pull waylandzhang/agent-core:v0.4.0
docker pull waylandzhang/llm-service:v0.4.0
docker pull waylandzhang/playwright-service:v0.4.0
```

Quick Start

```bash
curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Shannon/main/scripts/install.sh | bash
```

Breaking Changes from v0.3.x

This release replaces all prior history with a clean consolidated codebase. Previous state preserved at tag `v0.3.1-legacy`.

Full Changelog

See CHANGELOG.md

Added

• OAuth2 authentication with Google provider, JWT tokens, and API key management
• Attachments and multimodal support — image/file uploads through gateway, OpenAI-compatible content blocks, Python attachment handling
• Agent workflow — dedicated single-agent execution path with tool calling
• BrowserUse strategy — browser automation as a first-class execution strategy
• DomainAnalysis strategy — structured domain research with multi-source analysis
• Daemon approval routing — human-in-the-loop approval dispatch through WebSocket daemon
• Daemon dispatch for scheduled tasks — scheduled task results routed through daemon channels
• Workspace quotas — per-tenant retention and size limits (migration 012)
• Playwright SSRF protection — hostname validation and private IP blocking
• Firecracker executor rewrite — guest-agent, VM pool, vsock communication, workspace sync
• Gateway endpoints — /api/v1/agents, /api/v1/llm-models, /api/v1/memory/files
• Rate limits configuration — externalized to config/rate_limits.yaml (was inline)
• MiniMax as first-class LLM provider (dedicated provider, not OpenAI-compatible shim)
• Kimi (Moonshot AI) provider support
• Python SDK (pip install shannon-sdk) with streaming, sessions, and workflow routing
• Desktop app (Tauri v2) with real-time execution timeline and research visualization
• Release tooling — one-command installer, Docker Hub multi-arch images, CI/CD workflows
• Prompt cache optimization for Anthropic models (1h TTL, multi-turn support)
• Cache token tracking in token_usage and task_executions tables (migration 112)
• Performance indexes for large tables (migration 118)
• Per-LLM-call sequence tracking for cache behavior analysis (migration 120)

Fixed

• DeepSeek model aliases updated to official API IDs (deepseek-chat, deepseek-reasoner)
• Auth API key validation no longer references non-existent tier / rate_limit_override columns

Changed

• Consolidated platform release — clean codebase derived from Shannon Cloud with all enterprise features removed
• History replaces prior git history (previous state preserved at tag v0.3.1-legacy)

Shannon v0.3.1

🖥️ Desktop Apps

Download the desktop application for your platform:

macOS (Universal Binary - Intel & Apple Silicon)

• .dmg installer (recommended)
• .app.tar.gz for manual installation

Windows

• .msi installer (recommended)
• .exe NSIS installer (alternative)

Linux

• .AppImage (portable, no installation required)
• .deb package (Debian/Ubuntu)

🐳 Docker Images

docker pull waylandzhang/gateway:v0.3.1
docker pull waylandzhang/orchestrator:v0.3.1
docker pull waylandzhang/agent-core:v0.3.1
docker pull waylandzhang/llm-service:v0.3.1

🚀 Quick Start

Recommended: One-command install

curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Shannon/v0.3.1/scripts/install.sh | bash

This downloads all required files (config, migrations, WASM interpreter) and starts services.

Manual setup: Clone the repo and use deploy/compose/docker-compose.release.yml with the full directory structure.

📚 Documentation

• Quick Start Guide
• Desktop App Guide
• API Documentation

📝 What's Changed

See CHANGELOG.md for detailed changes.

What's Changed

• feat(swarm): workflow reliability, Lead tools, and desktop UI improvements by @Awakehsh in #152

Full Changelog: v0.3.0...v0.3.1

Added

• Swarm: file_delete tool with WASI sandbox security hardening (path traversal, symlink escape, /memory/ protection)
• Swarm: Lead tool_call protocol — Lead can invoke web_search, web_fetch, calculator directly
• Swarm: Lead file_read / file_list actions — zero LLM cost workspace file access
• Swarm: Conversation history injection for multi-turn context
• Swarm: HITL (human-in-the-loop) gateway infrastructure for Lead tool calls
• Desktop: Panel resize drag and React.memo optimization on RunConversation
• Desktop: Swarm message dedup and fetchFinalOutput fix

Fixed

• Swarm: Drain running agents on budget exhaustion — prevents orphaned child workflows and incomplete synthesis results
• Swarm: Unify session ID validation across Go (p2p, lead_file_read) and Python (file_ops) — strict alphanumeric + hyphen + underscore only
• Swarm: Fix tool_params JSON schema from "string" to "object" to match Pydantic model, add warning logs on parse fallback
• Swarm: P2P version gates, lenMust safety guards, and fallback timeout
• Swarm: Closing checkpoint hardening and dependency-aware task filtering
• LLM service health endpoint reporting stale version "0.1.0"

Changed

• Docker Compose: Add :- defaults to bare env var references (GOOGLE_SEARCH_API_KEY, EXA_API_KEY, FIRECRAWL_API_KEY) to suppress warnings

Shannon v0.3.1-legacy

🖥️ Desktop Apps

Download the desktop application for your platform:

macOS (Universal Binary - Intel & Apple Silicon)

• .dmg installer (recommended)
• .app.tar.gz for manual installation

Windows

• .msi installer (recommended)
• .exe NSIS installer (alternative)

Linux

• .AppImage (portable, no installation required)
• .deb package (Debian/Ubuntu)

🐳 Docker Images

docker pull waylandzhang/gateway:v0.3.1-legacy
docker pull waylandzhang/orchestrator:v0.3.1-legacy
docker pull waylandzhang/agent-core:v0.3.1-legacy
docker pull waylandzhang/llm-service:v0.3.1-legacy

🚀 Quick Start

Recommended: One-command install

curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Shannon/v0.3.1-legacy/scripts/install.sh | bash

This downloads all required files (config, migrations, WASM interpreter) and starts services.

Manual setup: Clone the repo and use deploy/compose/docker-compose.release.yml with the full directory structure.

📚 Documentation

• Quick Start Guide
• Desktop App Guide
• API Documentation

📝 What's Changed

See CHANGELOG.md for detailed changes.

What's Changed

• fix: sandbox, gateway, and lead hardening (15 confirmed issues) by @Awakehsh in #155
• Fix DeepSeek model aliases for official API IDs by @dyingcowboy in #156
• feat: add MiniMax M2.7/M2.7-highspeed as first-class LLM provider by @octo-patch in #157

New Contributors

• @dyingcowboy made their first contribution in #156
• @octo-patch made their first contribution in #157

Full Changelog: v0.3.1...v0.3.1-legacy

Shannon v0.3.0

🖥️ Desktop Apps

Download the desktop application for your platform:

macOS (Universal Binary - Intel & Apple Silicon)

• .dmg installer (recommended)
• .app.tar.gz for manual installation

Windows

• .msi installer (recommended)
• .exe NSIS installer (alternative)

Linux

• .AppImage (portable, no installation required)
• .deb package (Debian/Ubuntu)

🐳 Docker Images

docker pull waylandzhang/gateway:v0.3.0
docker pull waylandzhang/orchestrator:v0.3.0
docker pull waylandzhang/agent-core:v0.3.0
docker pull waylandzhang/llm-service:v0.3.0

🚀 Quick Start

Recommended: One-command install

curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Shannon/v0.3.0/scripts/install.sh | bash

This downloads all required files (config, migrations, WASM interpreter) and starts services.

Manual setup: Clone the repo and use deploy/compose/docker-compose.release.yml with the full directory structure.

📚 Documentation

• Quick Start Guide
• Desktop App Guide
• API Documentation

📝 What's Changed

See CHANGELOG.md for detailed changes.

Added

• Swarm V2 — Lead-orchestrated multi-agent system with parallel agent loops
• Channels system — Slack and LINE webhook integration (CRUD + inbound webhooks)
• Daemon WebSocket system — Redis-backed WS hub for CLI connectivity
• SearchAPI.io as web search provider
• Tool execution API (direct tool invocation without full orchestration)
• Scheduled tasks with Temporal Schedule API (cron-based recurring execution)
• Session workspaces with WASI-sandboxed file operations
• User memory extraction and persistence across sessions
• Synthesis templates for swarm, domain analysis, and research output customization
• Workflow templates (8 example YAML workflows)
• Desktop: radar canvas with Lead pulse and swarm agent colors
• Research workflow tiered model architecture (50-70% cost reduction)

Fixed

• Swarm AgentLoop tool tokens not accumulated into metadata totals
• Streaming manager send-to-closed-channel panic during shutdown
• Budget idempotency RLock/Lock TOCTOU race allowing duplicate token recording
• Lead HTTP timeout exceeding Temporal activity timeout
• Missing metadata on synthesis failure return path
• Leaked timer futures inflating Temporal workflow history
• Ignored workflow.Sleep error delaying cancellation
• CircuitBreaker data race and json.Marshal error handling
• Research model tier and agent output format
• Desktop workspace panel not resetting on session switch

Changed

• Release compose: aligned timeout defaults with dev environment
• Release compose: added shannon-users volume and user memory env vars
• Install script: added all synthesis and workflow templates
• Regenerated proto files (SessionContext.user_id, ExecuteTaskResponse.metadata)

Shannon v0.2.0

🖥️ Desktop Apps

Download the desktop application for your platform:

macOS (Universal Binary - Intel & Apple Silicon)

• .dmg installer (recommended)
• .app.tar.gz for manual installation

Windows

• .msi installer (recommended)
• .exe NSIS installer (alternative)

Linux

• .AppImage (portable, no installation required)
• .deb package (Debian/Ubuntu)

🐳 Docker Images

docker pull waylandzhang/gateway:v0.2.0
docker pull waylandzhang/orchestrator:v0.2.0
docker pull waylandzhang/agent-core:v0.2.0
docker pull waylandzhang/llm-service:v0.2.0

🚀 Quick Start

Recommended: One-command install

curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Shannon/v0.2.0/scripts/install.sh | bash

This downloads all required files (config, migrations, WASM interpreter) and starts services.

Manual setup: Clone the repo and use deploy/compose/docker-compose.release.yml with the full directory structure.

📚 Documentation

• Quick Start Guide
• Desktop App Guide
• API Documentation

📝 What's Changed

See CHANGELOG.md for detailed changes.

What's Changed

• fix(citations): add three-tier LLM signal detection to prevent snippet pollution by @Awakehsh in #111
• fix(gateway): improve SSE streaming reliability for long-running tasks by @waylandzhang in #115
• feat(browser): migrate browser_use from Enterprise to OSS by @waylandzhang in #113
• feat(web-search): multi-engine support, localization, Finance API & Search-First strategy by @Awakehsh in #112
• feat(research): multi-tool loop hardening + citation pipeline fixes by @Awakehsh in #117
• feat(research): Citation V2 + Verify V2 + P1 Efficiency Improvements by @Awakehsh in #118
• fix(security): remove WASI /tmp symlink bypass and unify ModelTier enum by @waylandzhang in #120
• fix(security): SSRF hardening, BM25 guard, URL sanitization, alias scoring by @waylandzhang in #121
• feat: add DAG cycle detection, tool filtering, and idempotency TTL cleanup by @waylandzhang in #122
• feat: Deep Research output quality improvements by @Awakehsh in #124
• fix(research): comprehensive Deep Research output quality improvements by @Awakehsh in #125
• feat(trading): add trading agent roles and template workflows by @waylandzhang in #126
• fix: add template_results truncation and warning-level import logging by @waylandzhang in #127
• Deep Research: Domain Discovery & Prefetch Optimization + Multilingual Enhancement by @Awakehsh in #129
• fix: use general output format for non-research roles by @Awakehsh in #130
• Feat/makefile by @weedge in #128
• feat(templates): add parallel_by expansion and cron scheduling support by @waylandzhang in #131
• Revert "Feat/makefile" by @waylandzhang in #132
• feat: Research Workflow Upgrade - Domain Analysis, OODA Loop, and Quality Improvements by @Awakehsh in #133
• feat(citation): implement placement-based citation with fallback by @Awakehsh in #135
• feat: add skills system, filesystem tools, and WASI sandbox integration by @waylandzhang in #137
• feat(research): optimize research strategy cost and performance by @Awakehsh in #138
• fix(citations): filter fallback-only snippets and block table row placements by @Awakehsh in #140
• feat: WASI session workspace mounting + hybrid Python sandbox scaffolding by @waylandzhang in #139
• feat(hitl): Human-in-the-Loop research plan review system by @Awakehsh in #141
• feat(swarm): add swarm multi-agent workflow with P2P messaging by @waylandzhang in #144

New Contributors

• @weedge made their first contribution in #128

Full Changelog: v0.1.0...v0.2.0

Added

• Add swarm multi-agent workflow with P2P messaging
• Add Human-in-the-Loop research plan review system with Redis lock for feedback/approve race conditions
• Add skills system, filesystem tools, WASI sandbox integration, and session workspace mounting
• Add citation pipeline V2/V3 with placement-based validation, soft attribution guidance, and fallback logic
• Add deep research domain analysis, OODA loop, domain discovery, prefetch optimization, and multilingual enhancement
• Add research workflow tiered model architecture with quick_research_agent role and forced parallel execution
• Add multi-engine web search with localization, Finance API, and search-first strategy
• Add parallel_by template expansion and cron scheduling support for template workflows
• Add trading agent roles and template workflows
• Add browser_use tool migration from Enterprise to OSS
• Add temporal awareness to synthesis and search prompts
• Add DAG cycle detection, tool filtering, and idempotency TTL cleanup
• Add hybrid Python sandbox scaffolding (WASI + Firecracker)

Fixed

• Fix duplicate tool execution after forced_tool_calls
• Fix synthesis "large" model_tier bleeding into gap-filling agents
• Fix session_id propagation to Python tools via ensureSessionContext helper
• Fix SSE streaming reliability for long-running tasks
• Fix citation snippet pollution with three-tier LLM signal detection and fallback-only filtering
• Fix research relationship identification to prevent vendor/customer misclassification
• Fix Chinese vs Japanese language detection in refine pass
• Fix web-subpage-fetch MAP_TIMEOUT from 15s to 45s
• Fix deep research output quality and completeness across multiple iterations
• Fix template_results truncation and warning-level import logging
• Fix non-research roles using general output format in interpretation pass
• Fix workspace creation race condition
• Fix protoc missing detection in proto generation script
• Fix domain prefetch for comparative query type

Security

• Add SSRF hardening, BM25 guard, URL sanitization, and alias scoring
• Remove WASI /tmp symlink bypass and unify ModelTier enum
• Block absolute path writes and env secret leaks in sandbox
• Fix session ID validation, timeouts, and skill auth from code review

Changed

• Skip title generation for non-first tasks in session (performance)
• Restrict Chinese sources to Chinese-company queries only
• Rename citation V3 to placement-based naming convention
• Translate Chinese comments to English in web_fetch, web_search, verify
• Update default COMPLEXITY_MODEL_ID to gpt-5
• Update architecture diagram, model names, and versions in README
• Sync docker-compose.release.yml and install.sh with Phase 4 features