foundry-sandbox 0.13.0__tar.gz

foundry_sandbox-0.13.0/.env.example

@@ -0,0 +1,35 @@
+# Foundry Sandbox API Keys Configuration
+# Copy this file to .env and fill in your keys, or export them in your shell profile.
+#
+# Keys are passed to containers via docker-compose environment section.
+
+# =============================================================================
+# AI Provider Keys (at least one required)
+# =============================================================================
+
+# Claude Code - Get via: claude setup-token
+# CLAUDE_CODE_OAUTH_TOKEN=
+
+# OpenAI/Codex API
+# OPENAI_API_KEY=
+
+# Cursor Agent
+# CURSOR_API_KEY=
+
+# Note: Gemini CLI uses OAuth credentials stored in ~/.gemini/oauth_creds.json
+# Run `gemini auth` to authenticate (no environment variable needed)
+
+# =============================================================================
+# Search Provider Keys (optional - for deep research features)
+# =============================================================================
+
+# Tavily Search API - https://tavily.com/
+# TAVILY_API_KEY=
+
+# Perplexity API - https://perplexity.ai/
+# PERPLEXITY_API_KEY=
+
+# Search provider override (comma-separated)
+# Available: tavily, perplexity, semantic_scholar
+# If set, overrides auto-detection. If unset, providers are auto-detected from API keys.
+# FOUNDRY_SEARCH_PROVIDERS=tavily,perplexity

foundry_sandbox-0.13.0/.foundry-mcp.toml

@@ -0,0 +1,651 @@
+# foundry-mcp configuration
+#
+# Configuration Priority (highest to lowest):
+# 1. Environment variables (runtime overrides)
+# 2. Project config (./foundry-mcp.toml or ./.foundry-mcp.toml)
+# 3. User config (~/.foundry-mcp.toml)
+# 4. XDG config (~/.config/foundry-mcp/config.toml)
+# 5. Built-in defaults
+
+# =============================================================================
+# Workspace Configuration
+# =============================================================================
+
+[workspace]
+# Where your specs live (auto-detected if not set).
+# Good default: keep specs in ./specs.
+specs_dir = "./specs"
+
+# Notes inbox (defaults to specs_dir/.notes)
+# Env var: FOUNDRY_MCP_NOTES_DIR
+notes_dir = "./specs/.notes"
+
+# Directory for storing research artifacts
+research_dir = "./specs/.research"
+
+# =============================================================================
+# Logging Configuration
+# =============================================================================
+
+[logging]
+# Log level: DEBUG, INFO, WARNING, ERROR
+level = "INFO"
+
+# JSON logs are easier to ingest; set false for human-readable logs.
+structured = true
+
+# =============================================================================
+# Tools Configuration
+# =============================================================================
+
+[tools]
+# Disable specific tools to reduce prompt size.
+# Tool descriptions are loaded into the model's context on each message.
+# Good default: disable setup-only tools you do not use day-to-day.
+#
+# Available tools:
+#   health       - Liveness/readiness checks (used by setup)
+#   plan         - Plan creation and review workflows
+#   pr           - Pull request creation
+#   error        - Error collection and querying
+#   journal      - Implementation journals
+#   authoring    - Spec authoring operations
+#   review       - Fidelity and code reviews
+#   spec         - Spec management
+#   task         - Task management
+#   provider     - AI provider status
+#   environment  - Environment setup and detection
+#   lifecycle    - Spec lifecycle transitions
+#   verification - Verification workflows
+#   server       - Server introspection
+#   test         - Test runner integration
+#   research     - Research workflows (chat, consensus, thinkdeep, ideate, deep)
+#
+# Default: disable tools not needed, or only needed during setup
+disabled_tools = ["health", "error"]
+
+# Environment variable alternative: FOUNDRY_MCP_DISABLED_TOOLS (comma-separated)
+# Example: FOUNDRY_MCP_DISABLED_TOOLS=error,research
+
+# =============================================================================
+# Observability Configuration
+# =============================================================================
+#
+# Requires optional dependencies:
+#   - For OpenTelemetry: pip install foundry-mcp[tracing]
+#   - For Prometheus: pip install foundry-mcp[metrics]
+#   - For both: pip install foundry-mcp[observability]
+
+[observability]
+# Master switch for all observability features
+# Set to true to enable, then configure individual providers below
+enabled = false
+
+# =============================================================================
+# Health Checks Configuration
+# =============================================================================
+
+[health]
+# Health probes for liveness/readiness.
+enabled = false
+
+# =============================================================================
+# Error Collection Configuration
+# =============================================================================
+#
+# Stores error logs for observability and debugging.
+# Errors are stored in append-only JSONL format with automatic cleanup.
+
+[error_collection]
+# Enable error collection
+enabled = true
+
+# =============================================================================
+# Metrics Persistence Configuration
+# =============================================================================
+#
+# Persist time-series metrics to disk so they survive restarts.
+
+[metrics_persistence]
+# Enable metrics persistence (default: false)
+enabled = false
+
+# =============================================================================
+# Implement Command Configuration
+# =============================================================================
+#
+# Default flags for the /implement command. These can be overridden via CLI flags.
+
+[implement]
+
+# Use subagent(s) for implementation (on by default)
+delegate = true
+
+# Run subagents concurrently for independent tasks (implies delegate=true)
+parallel = true
+
+# =============================================================================
+# Git Workflow Configuration
+# =============================================================================
+
+[git]
+# Enable git-aware workflows (automatic commit prompts, commit cadence, etc.)
+enabled = true
+
+# Determine when to offer automatic commits: "manual", "task", or "phase"
+commit_cadence = "phase"
+
+# Control automated behaviors
+auto_commit = true
+auto_push = true
+auto_pr = false
+
+# Show staged file preview before committing (recommended)
+show_before_commit = false
+
+# =============================================================================
+# Workflow Configuration
+# =============================================================================
+
+[workflow]
+# Execution mode:
+#   "single"     - One task at a time with user approval
+#   "autonomous" - Complete all phase tasks automatically
+#   "batch"      - Execute batch_size tasks, then pause
+mode = "autonomous"
+
+# Auto-compact setting (matches Claude Code's autoCompactEnabled)
+# When false, context window is 200k; when true (default), it's 155k
+# Sandboxes disable auto-compact for more predictable context management
+auto_compact = false
+
+# Automatically run validation after task completion
+auto_validate = true
+
+# Enable journaling of task completions
+journal_enabled = true
+
+# Number of tasks to execute in batch mode
+batch_size = 5
+
+# Context usage threshold (%) to trigger automatic pause
+# When context reaches this threshold, autonomous/batch mode pauses
+context_threshold = 85
+
+# =============================================================================
+# AI Consultation Configuration
+# =============================================================================
+
+[consultation]
+# Default timeout for AI provider calls in seconds
+default_timeout = 600
+
+# Number of retry attempts per provider for transient failures
+max_retries = 2
+
+# Delay between retry attempts in seconds
+retry_delay = 5.0
+
+# Enable fallback to next available provider when one fails
+fallback_enabled = true
+
+# Cache time-to-live in seconds for consultation results
+cache_ttl = 3600
+
+# Provider priority list - first available provider wins
+# Update order to match your preferred providers/models.
+priority = [
+    "[cli]codex:gpt-5.2-codex",
+    "[cli]gemini:pro",
+    "[cli]claude:opus",
+    "[cli]opencode:zai-coding-plan/glm-4.7",
+    "[cli]claude-zai:opus"
+]
+
+# Per-provider overrides (optional)
+# [consultation.overrides]
+# "[cli]opencode:openai/gpt-5.2-codex" = { timeout = 600 }
+
+# Per-workflow overrides
+[consultation.workflows.fidelity_review]
+# Good default: 2 models for consensus
+min_models = 2
+timeout_override = 600.0
+default_review_type = "full"
+
+[consultation.workflows.plan_review]
+# Good default: 2 models for consensus
+min_models = 2
+default_review_type = "full"
+
+[consultation.workflows.markdown_plan_review]
+# Good default: 2 models
+min_models = 2
+timeout_override = 600.0
+default_review_type = "full"
+
+# =============================================================================
+# Research Workflow Configuration
+# =============================================================================
+
+[research]
+# Enable research tools (chat, consensus, thinkdeep, ideate, deep-research)
+enabled = true
+
+# Default LLM provider for research workflows
+# Supports ProviderSpec format: "[cli]gemini:pro" or simple: "gemini"
+default_provider = "[cli]gemini:pro"
+
+# Providers for CONSENSUS workflow (multi-model consultation)
+# Use the providers you have installed.
+consensus_providers = [
+    "[cli]gemini:pro",
+    "[cli]codex:gpt-5.2-codex",
+    "[cli]claude:opus",
+    "[cli]opencode:zai-coding-plan/glm-4.7",
+    "[cli]claude-zai:opus"
+]
+
+# State TTL in hours before cleanup
+ttl_hours = 24
+
+# Maximum messages per conversation thread
+max_messages_per_thread = 100
+
+# Default timeout for provider calls in seconds
+# Minimum recommended: 600s for AI CLI providers
+default_timeout = 600.0
+
+# Maximum investigation depth for THINKDEEP workflow
+thinkdeep_max_depth = 5
+
+# Perspectives for IDEATE brainstorming
+ideate_perspectives = ["technical", "creative", "practical", "visionary"]
+
+# -----------------------------------------------------------------------------
+# Deep Research Settings
+# -----------------------------------------------------------------------------
+
+# Maximum refinement iterations
+deep_research_max_iterations = 3
+
+# Maximum sub-queries per decomposition
+deep_research_max_sub_queries = 5
+
+# Maximum sources per sub-query
+deep_research_max_sources = 10
+
+# Follow and extract content from URLs
+deep_research_follow_links = true
+
+# Whole workflow timeout in seconds (recommended: 600s)
+deep_research_timeout = 600.0
+
+# Maximum parallel operations
+deep_research_max_concurrent = 3
+
+# Write audit artifacts for debugging
+deep_research_audit_artifacts = true
+
+# Research mode: controls source prioritization
+# - "general"   : No domain preferences (default)
+# - "academic"  : Prioritizes journals, publishers, preprints
+# - "technical" : Prioritizes official docs, arxiv, Stack Overflow
+deep_research_mode = "technical"
+
+# Search providers (in priority order)
+# Available: tavily, perplexity, google, semantic_scholar
+deep_research_providers = [
+    "semantic_scholar"
+]
+
+# -----------------------------------------------------------------------------
+# Per-Phase Timeouts (override deep_research_timeout)
+# Minimum recommended: 600s per operation for AI CLI providers
+# -----------------------------------------------------------------------------
+
+deep_research_planning_timeout = 600.0    # Query decomposition
+deep_research_analysis_timeout = 600.0    # Finding extraction
+deep_research_synthesis_timeout = 600.0   # Report generation (may take longer)
+deep_research_refinement_timeout = 600.0  # Gap identification
+
+# -----------------------------------------------------------------------------
+# Per-Phase Providers (override default_provider)
+# -----------------------------------------------------------------------------
+# Supports ProviderSpec format for model selection:
+#   "[cli]gemini:pro"
+#   "[cli]claude:opus"
+#   "[cli]opencode:openai/gpt-5.2-codex"
+#   "[cli]codex:gpt-5.2-codex"
+
+deep_research_planning_provider = "[cli]gemini:flash"
+deep_research_analysis_provider = "[cli]gemini:pro"
+deep_research_synthesis_provider = "[cli]gemini:pro"
+deep_research_refinement_provider = "[cli]gemini:pro"
+
+# -----------------------------------------------------------------------------
+# Per-Phase Fallback Provider Lists (Retry & Resilience)
+# -----------------------------------------------------------------------------
+# Each phase can have an ordered list of fallback providers.
+# On failure/timeout, the workflow retries with backoff, then tries
+# the next provider in the list until success or exhaustion.
+# Empty list = no fallback (use only the primary provider)
+
+# Planning phase: query decomposition (can use faster/cheaper models)
+deep_research_planning_providers = [
+    "[cli]gemini:flash",
+    "[cli]codex:gpt-5.1-codex-mini",
+    "[cli]claude:sonnet",
+    "[cli]opencode:zai-coding-plan/glm-4.7",
+    "[cli]claude-zai:sonnet"
+]
+
+# Analysis phase: finding extraction
+deep_research_analysis_providers = [
+    "[cli]gemini:pro",
+    "[cli]codex:gpt-4.1",
+    "[cli]claude:opus",
+    "[cli]opencode:zai-coding-plan/glm-4.7",
+    "[cli]claude-zai:opus"
+]
+
+# Synthesis phase: report generation (may benefit from stronger models)
+deep_research_synthesis_providers = [
+    "[cli]gemini:pro",
+    "[cli]codex:gpt-5.2-codex",
+    "[cli]claude:opus",
+    "[cli]opencode:zai-coding-plan/glm-4.7",
+    "[cli]claude-zai:opus"
+]
+
+# Refinement phase: gap identification
+deep_research_refinement_providers = [
+    "[cli]gemini:pro",
+    "[cli]codex:gpt-5.2-codex",
+    "[cli]claude:opus",
+    "[cli]opencode:zai-coding-plan/glm-4.7",
+    "[cli]claude-zai:opus"
+]
+
+deep_research_max_retries = 2
+deep_research_retry_delay = 5.0
+
+# -----------------------------------------------------------------------------
+# Search Rate Limiting
+# -----------------------------------------------------------------------------
+
+search_rate_limit = 60              # Requests per minute (global)
+max_concurrent_searches = 3         # Concurrent search requests
+
+[research.per_provider_rate_limits]
+tavily = 60
+perplexity = 60
+semantic_scholar = 100
+
+# -----------------------------------------------------------------------------
+# Tavily Search Provider Configuration
+# -----------------------------------------------------------------------------
+# Tavily is optimized for AI applications. Get API key at https://tavily.com/
+
+# Search depth: affects result quality and API credit cost
+# - "basic"      : Standard search (default, 1x credits)
+# - "advanced"   : Deeper analysis with more content (2x credits)
+# - "fast"       : Reduced latency
+# - "ultra_fast" : Minimal latency
+tavily_search_depth = "advanced"
+
+# Search topic: "general" or "news"
+tavily_topic = "general"
+
+# Days limit for news search (1-365, only when topic="news")
+# tavily_news_days = 7
+
+# Include image results
+tavily_include_images = false
+
+# ISO 3166-1 alpha-2 country code to boost results (e.g., "US", "GB", "DE")
+tavily_country = "US"
+
+# Chunks per source for advanced search (1-5)
+tavily_chunks_per_source = 3
+
+# Let Tavily auto-configure parameters based on query intent
+tavily_auto_parameters = false
+
+# -----------------------------------------------------------------------------
+# Tavily Extract Provider Configuration
+# -----------------------------------------------------------------------------
+# Extract structured content from URLs for deeper analysis
+
+# Extract depth: "basic" or "advanced"
+tavily_extract_depth = "advanced"
+
+# Include images in extracted content
+tavily_extract_include_images = false
+
+# Enable extract as follow-up step in deep research workflow
+# When true, deep research will extract full content from top search results
+tavily_extract_in_deep_research = true
+
+# Maximum URLs to extract per deep research run
+tavily_extract_max_urls = 5
+
+
+
+# -----------------------------------------------------------------------------
+# Document Digest Configuration
+# -----------------------------------------------------------------------------
+# Controls automatic content compression for large research sources.
+# When enabled, lengthy content is summarized into structured digests
+# with key findings and evidence snippets, reducing token usage while
+# preserving essential information.
+
+# Digest policy: controls when digestion is applied
+# - "off"    : Never digest content (preserve raw text)
+# - "auto"   : Digest when content exceeds min_chars threshold (default)
+# - "always" : Always digest eligible sources regardless of size
+deep_research_digest_policy = "auto"
+
+# Minimum character count before digest is applied (auto mode only)
+deep_research_digest_min_chars = 10000
+
+# Maximum sources to digest per batch
+deep_research_digest_max_sources = 8
+
+# Timeout per digest operation in seconds
+deep_research_digest_timeout = 180.0
+
+# Maximum concurrent digest operations
+deep_research_digest_max_concurrent = 3
+
+# Include evidence snippets (direct quotes) in digests
+deep_research_digest_include_evidence = true
+
+# Maximum characters per evidence snippet
+deep_research_digest_evidence_max_chars = 600
+
+# Maximum evidence snippets per digest
+deep_research_digest_max_evidence_snippets = 5
+
+# Fetch and extract PDF content from URLs
+# When true, PDFs are downloaded, text extracted, and digested
+# Requires additional processing time; disabled by default
+deep_research_digest_fetch_pdfs = true
+
+# Archive canonical text for digested sources
+# When true, original full text is saved to disk before digesting
+deep_research_archive_content = true
+
+# Days to retain archived digest content (0 = keep indefinitely)
+deep_research_archive_retention_days = 30
+
+# Primary LLM provider for digest operations
+# Uses analysis provider if not set
+deep_research_digest_provider = "[cli]gemini:flash"
+
+# Fallback providers for digest (tried in order if primary fails)
+deep_research_digest_providers = [
+    "[cli]gemini:flash",
+    "[cli]codex:gpt-5.1-codex-mini",
+    "[cli]claude:haiku",
+    "[cli]opencode:zai-coding-plan/glm-4.7",
+    "[cli]claude-zai:sonnet"
+]
+
+# -----------------------------------------------------------------------------
+# Perplexity Search Provider Configuration
+# -----------------------------------------------------------------------------
+# Perplexity provides AI-powered search with citations.
+# Get API key at https://www.perplexity.ai/settings/api
+
+# Search context size: affects result depth and API cost
+# - "low"    : Minimal context, fastest responses
+# - "medium" : Balanced context (default)
+# - "high"   : Maximum context, most comprehensive
+perplexity_search_context_size = "medium"
+
+# Maximum tokens for response
+perplexity_max_tokens = 50000
+
+# Maximum tokens per page
+perplexity_max_tokens_per_page = 2048
+
+# Time filter for results: "day", "week", "month", "year"
+# perplexity_recency_filter = "week"
+
+# ISO 3166-1 alpha-2 country code to boost results (e.g., "US", "GB", "DE")
+perplexity_country = "US"
+
+# -----------------------------------------------------------------------------
+# Semantic Scholar Search Provider Configuration
+# -----------------------------------------------------------------------------
+# Semantic Scholar provides academic paper search with TLDR summaries.
+# API key is optional but recommended for higher rate limits.
+
+# Filter by publication types (list of types)
+# Valid types: Review, JournalArticle, Conference, CaseReport, ClinicalTrial,
+#              Dataset, Editorial, LettersAndComments, MetaAnalysis, News,
+#              Study, Book, BookSection
+semantic_scholar_publication_types = ["JournalArticle", "Conference", "Review", "MetaAnalysis", "Study"]
+
+# Sort results by field: citationCount, publicationDate, paperId
+semantic_scholar_sort_by = "citationCount"
+
+# Sort direction: asc or desc (default: desc)
+semantic_scholar_sort_order = "desc"
+
+# Include TLDR and extended metadata (default: true)
+# Set to false for faster responses with less metadata
+semantic_scholar_use_extended_fields = true
+
+# -----------------------------------------------------------------------------
+# Search Provider Credentials (optional, prefer env vars)
+# -----------------------------------------------------------------------------
+# API keys can be set here or via environment variables (preferred):
+#   TAVILY_API_KEY, PERPLEXITY_API_KEY, SEMANTIC_SCHOLAR_API_KEY
+#
+# tavily_api_key = "tvly-..."
+# perplexity_api_key = "pplx-..."
+# semantic_scholar_api_key = "..."
+
+# -----------------------------------------------------------------------------
+# Token Management Configuration
+# -----------------------------------------------------------------------------
+# Controls token budget management for deep research workflows.
+# When enabled, content is intelligently compressed or archived to fit
+# within model context limits.
+
+# Master switch for token management features
+# When disabled, all token budget calculations are skipped
+token_management_enabled = true
+
+# Safety margin: fraction of budget reserved as buffer (0.0 - 1.0)
+# Higher values provide more headroom but reduce usable context
+# Default: 0.15 (15% buffer)
+token_safety_margin = 0.15
+
+# Runtime overhead: tokens reserved for CLI/IDE runtime context
+# This accounts for system prompts, conversation history, and tool schemas
+# that consume context before your research content.
+#
+# Recommended values by environment:
+#   Claude Code:    60000  (default, ~60K for system + tools + history)
+#   Codex/OpenCode: 30000  (minimal IDE integration overhead)
+#   Gemini CLI:     20000  (lightweight CLI)
+#   Direct API:     10000  (minimal overhead)
+#
+# Tip: If you see "context exceeded" errors, increase this value.
+# If content is being dropped unnecessarily, decrease it.
+runtime_overhead = 60000
+
+# -----------------------------------------------------------------------------
+# Summarization Configuration
+# -----------------------------------------------------------------------------
+# When content exceeds budget, summarization compresses it to fit.
+# Uses LLM providers to generate condensed versions while preserving
+# key information.
+
+# Primary provider for summarization (uses default_provider if not set)
+summarization_provider = "[cli]gemini:flash"
+
+# Fallback providers for summarization (tried in order if primary fails)
+summarization_providers = [
+    "[cli]gemini:flash",
+    "[cli]claude:haiku",
+    "[cli]codex:gpt-5.1-codex-mini",
+    "[cli]claude-zai:opus",
+    "[cli]opencode:zai-coding-plan/glm-4.7"
+]
+
+# Timeout per summarization request in seconds
+summarization_timeout = 60.0
+
+# Cache summarization results to avoid redundant API calls
+# Caches by content hash + summarization level + provider
+summarization_cache_enabled = true
+
+# -----------------------------------------------------------------------------
+# Content Dropping & Archive Configuration
+# -----------------------------------------------------------------------------
+# When budget is exhausted and summarization isn't sufficient,
+# low-priority content can be dropped. Optionally archive dropped
+# content to disk for later retrieval.
+
+# Allow dropping low-priority content when budget is exhausted
+# When false: workflow may fail if content exceeds budget
+# When true: drops lowest-priority items to fit budget
+allow_content_dropping = true
+
+# Archive dropped/compressed content to disk
+# Enables potential future restoration and audit trail
+content_archive_enabled = true
+
+# TTL for archived content in hours (default: 168 = 7 days)
+# Older content is automatically cleaned up
+content_archive_ttl_hours = 168
+
+# Directory for content archive storage
+# Default: research_dir/.archive (e.g., specs/.research/.archive)
+# research_archive_dir = "~/.foundry-mcp/research-archive"
+
+# =============================================================================
+# Test Runner Configuration
+# =============================================================================
+#
+# Configure which test runner to use and customize runner settings.
+# The foundry-setup command can auto-detect and configure this section.
+#
+# Supported runners (built-in defaults): pytest, go, npm, jest, make
+# Custom runners can be defined in [test.runners.*] sections.
+
+[test]
+# Default runner to use when running tests
+# Valid values: pytest, go, npm, jest, make, or any custom runner name
+default_runner = "pytest"
+
+# Example custom runner:
+# [test.runners.go]
+# command = ["go", "test"]
+# run_args = ["./..."]
+# pattern = "*_test.go"
+# timeout = 300