.env.example

# kaiban-distributed environment variables
# Copy this file to .env for local development
# Never commit .env to version control

# Redis connection URL
REDIS_URL=redis://localhost:6379

# Kafka broker addresses (comma-separated for multiple brokers)
KAFKA_BROKERS=localhost:9092

# Kafka client identifier for this worker node
KAFKA_CLIENT_ID=kaiban-worker

# Kafka consumer group ID
KAFKA_GROUP_ID=kaiban-group

# HTTP server port
PORT=3000

# Service name used in telemetry/traces
SERVICE_NAME=kaiban-worker

# Structured logging (pino). Default output is JSON (production-grade).
# LOG_LEVEL: trace|debug|info|warn|error|fatal|silent  (default: info)
# LOG_PRETTY=true → human-readable colourised logs for local dev/demos (needs pino-pretty)
# LOG_LEVEL=info
# LOG_PRETTY=true

# Messaging driver: "bullmq" (default, uses Redis) or "kafka"
MESSAGING_DRIVER=bullmq

# OpenTelemetry OTLP exporter endpoint (optional)
# Leave unset to use ConsoleSpanExporter (dev mode — verbose, not suitable for production)
# OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318/v1/traces

# Process role for the single combined image (src/main/index.ts dispatches on it).
#   ROLE=gateway → HTTP / WebSocket / A2A / MCP front door only (no task-consuming actors)
#   ROLE=worker  → loads the AGENT_IDS pool and wires real LLM-backed handlers
# Unset defaults to "gateway". (ADR-013 gateway/worker split.)
# ROLE=gateway

# Comma-separated list of agent IDs this worker node serves (required for ROLE=worker)
AGENT_IDS=researcher,writer,editor

# LLM Configuration — Standard OpenAI OR OpenRouter (or any OpenAI-compatible API)
#
# Standard OpenAI:
#   OPENAI_API_KEY=sk-...
#   LLM_MODEL=gpt-4o-mini
#
# OpenRouter (https://openrouter.ai):
#   OPENROUTER_API_KEY=sk-or-v1-...
#   LLM_MODEL=openai/gpt-4o-mini
#
# Any OpenAI-compatible endpoint:
#   OPENAI_API_KEY=your-key
#   OPENAI_BASE_URL=http://your-endpoint/v1
#   LLM_MODEL=your-model

OPENAI_API_KEY=your_openai_api_key_here
# OPENROUTER_API_KEY=your_openrouter_api_key_here
# OPENAI_BASE_URL=
# LLM_MODEL=gpt-4o-mini
# Other LLM providers are also honored if set (passed through to KaibanJS):
# ANTHROPIC_API_KEY=
# GOOGLE_API_KEY=
# MISTRAL_API_KEY=
# GROQ_API_KEY=

# Opt out of KaibanJS anonymous telemetry (any non-empty value = opt out).
# ⚠ Set to 1 on networks that block nom.telemetrydeck.com at DNS level — the
# blocked telemetry fetch otherwise crashes the agent process with an unhandled
# rejection inside kaibanjs before the first task completes.
# KAIBAN_TELEMETRY_OPT_OUT=1

# ── Security: mTLS (optional) ──────────────────────────────────
# Paths to TLS certificates for Redis/Kafka mTLS connections
# Generate self-signed certs: ./scripts/generate-dev-certs.sh
# REDIS_TLS_CA=./certs/ca.crt
# REDIS_TLS_CERT=./certs/client.crt
# REDIS_TLS_KEY=./certs/client.key
# KAFKA_SSL_CA=./certs/ca.crt
# KAFKA_SSL_CERT=./certs/client.crt
# KAFKA_SSL_KEY=./certs/client.key
# TLS_REJECT_UNAUTHORIZED=true  # Set to false for self-signed certs in staging

# ── Security: Semantic Firewall (optional) ─────────────────────
# SEMANTIC_FIREWALL_ENABLED=false
# SEMANTIC_FIREWALL_LLM_URL=http://localhost:11434/api/generate  # Optional local LLM

# ── Security: JIT Token Provider (optional) ────────────────────
# JIT_TOKENS_ENABLED=false

# ── Security: Circuit Breaker (optional) ───────────────────────
# CIRCUIT_BREAKER_ENABLED=false
# CIRCUIT_BREAKER_THRESHOLD=10     # Failures before breaker trips
# CIRCUIT_BREAKER_WINDOW_MS=60000  # Sliding window duration (ms)

# ── Security: Redis password (recommended) ─────────────────────
# Set this to require a password on the Redis server (matches docker-compose.yml)
# (compose-only) — consumed by docker-compose, not read directly by src/; fold it into REDIS_URL below.
# REDIS_PASSWORD=<random 32+ chars>
# When set, use: REDIS_URL=redis://:${REDIS_PASSWORD}@localhost:6379

# ── Security: Socket.io Board Auth (optional, strongly recommended in production) ────────────
# JWT secret for board viewer tokens. When set, all Socket.io connections must present a valid token.
# BOARD_JWT_SECRET=<random 32+ bytes, base64-encoded>
# SOCKET_CORS_ORIGINS=http://localhost:5173,https://board.example.com

# ── Security: A2A RPC Auth (optional, strongly recommended in production) ──────────────────
# JWT secret for agent/orchestrator service tokens. When set, POST /a2a/rpc requires Bearer token.
# A2A_JWT_SECRET=<random 32+ bytes, base64-encoded>

# ── Federation: MCP server (Phase M — OFF by default) ──────────────────────────────────────
# Exposes allow-listed Tools/Resources/Prompts + elicitation (HITL consent) over Streamable HTTP,
# behind the gateway's security chain (rate-limit + the A2A_JWT_SECRET bearer above). See docs/federation/MCP.md.
# ⚠ SECURITY: the MCP route is authenticated ONLY when A2A_JWT_SECRET (above) is set. If you enable
#   MCP in production WITHOUT A2A_JWT_SECRET, the MCP surface (dispatch_task + agent resources) is
#   UNAUTHENTICATED (still rate-limited + dispatch is elicitation-consent-gated). Set A2A_JWT_SECRET.
# MCP_SERVER_ENABLED=false               # master switch (default false)
# MCP_SERVER_PATH=/mcp                   # mount path on the gateway
# MCP_DISPATCH_CONSENT=true              # require elicitation consent before dispatch_task (fail-closed)
# Optional least-privilege allow-lists (CSV). Unset ⇒ the full curated set ships; empty ⇒ none of that kind.
# MCP_ALLOWED_TOOLS=dispatch_task
# MCP_ALLOWED_RESOURCES=agents,agent-status
# MCP_ALLOWED_PROMPTS=delegate_task

# ── Economics / FinOps (Phase E — OFF by default) ──────────────────────────────────────────
# Fleet-wide rate + cost control on top of per-task accounting (which is unchanged). 0 = unlimited.
# See docs/economics/ECONOMICS.md. The per-task MAX_TOKEN_BUDGET above is separate and still applies.
# ECONOMICS_ENABLED=false                  # master switch (default false)
# ECONOMICS_MAX_REQUESTS_PER_WINDOW=0      # request-rate ceiling per scope (0 = unlimited)
# ECONOMICS_MAX_COST_PER_WINDOW=0          # cost-unit budget per tenant/agent scope (0 = unlimited)
# ECONOMICS_GLOBAL_COST_CEILING=0          # cost-unit ceiling across ALL scopes (0 = unlimited)
# ECONOMICS_WINDOW_SECONDS=60              # sliding window length (seconds)
# ECONOMICS_DEGRADE_THRESHOLD=0.75         # utilization at/above which to DEGRADE (run cheaper)

# ── Governance / Action Gate (Phase G — OFF by default) ────────────────────────────────────
# Non-bypassable enforcement (firewall + breaker + cost + policy + kill-switch), hash-chained audit,
# policy-as-code, agent registry/kill-switch, memory RBAC. See docs/governance/GOVERNANCE.md.
# GOVERNANCE_ENABLED=false                          # master switch (default false → gate is a no-op allow)
# GOVERNANCE_POLICIES_PATH=/etc/kaiban/policies.yml # optional policy-as-code file (see src/governance/policies.yml)

# ── Security: Redis Channel Signing (optional, strongly recommended in production) ─────────
# HMAC-SHA256 secret for signing state events on Redis pub/sub. When set, fake state injection
# from anyone with Redis access is blocked.
# CHANNEL_SIGNING_SECRET=<random 32+ bytes, base64-encoded>

# ── Security: Deployment settings ──────────────────────────────
# NODE_ENV=production
# TRUST_PROXY=false   # Set to true when behind a reverse proxy (Railway, K8s ingress, Nginx)

# ── Telemetry: OTLP auth (optional) ────────────────────────────
# When using an authenticated OTLP collector, add an Authorization header:
# (reserved — not yet wired in code; honored by the OTLP SDK env contract, not parsed by src/)
# OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <token>

# ── HITL Decision Options ───────────────────────────────────────
# Comma-separated list of valid human decisions for the HITL gate.
# The gateway validates incoming board decisions against this list.
# This matches the code default (src/main/config.ts). Do NOT add VIEW here:
# VIEW is an interactive terminal-only action that re-prompts the orchestrator
# prompt — it does not resolve the gate and is NOT a valid board/gateway decision.
VALID_HITL_DECISIONS=PUBLISH,REVISE,REJECT

# ── Agent Identity (set per-node process / container) ───────────
# Each agent node reads its own identity from AGENT_ID.
# Set this to match the agent's role in the pipeline.
#
# Blog Team example agents:
#   AGENT_ID=researcher   (researcher-node.ts — Ava, News Researcher)
#   AGENT_ID=writer       (writer-node.ts — Kai, Content Creator)
#   AGENT_ID=editor       (editor-node.ts — Morgan, Editorial Fact-Checker)
#
# Global Research example agents:
#   AGENT_ID=writer       (writer-node.ts — Atlas, Research Synthesiser)
#   AGENT_ID=reviewer     (reviewer-node.ts — Sage, AI Ethics & Compliance Officer)
#   AGENT_ID=editor       (editor-node.ts — Morgan, Chief Research Editor)
#   SEARCHER_ID=searcher    (searcher-node.ts — Zara; OPTIONAL. If unset, each replica
#                            auto-assigns a unique id (searcher-0, searcher-1, … via a
#                            Redis counter) and appears as a distinct board entry. Set
#                            this only to pin a fixed id.)
#
AGENT_ID=researcher

# Public base URL advertised in the A2A AgentCard (/.well-known/agent-card.json).
# Set this to the gateway's externally-reachable URL for federated deployments
# behind a public hostname/proxy. Defaults to http://localhost:${PORT}.
# A2A_PUBLIC_URL=https://agents.example.com

# ── Example Orchestrator Vars (set in docker-compose or shell) ──
# These are only used by the example orchestrators, not the core library.
#
# Blog Team orchestrator:
#   GATEWAY_URL=http://localhost:3000       # Gateway HTTP endpoint
#   TOPIC=Latest developments in AI agents  # Blog post topic
#   RESEARCH_WAIT_MS=120000                 # Timeout for research phase (ms)
#   WRITE_WAIT_MS=240000                    # Timeout for write phase (ms)
#   EDIT_WAIT_MS=300000                     # Timeout for edit phase (ms)
#
# WORKFLOW_ID — both example orchestrators read it to namespace the Redis
# checkpoint (crash-safe resume). Unset → derived from the topic/context, so a
# restart with the same input RESUMES; set a unique value to force a fresh run.
#   WORKFLOW_ID=my-run-001
#
# Global Research orchestrator:
#   GATEWAY_URL=http://localhost:3000       # Gateway HTTP endpoint
#   QUERY=The Future of AI Agents           # Research query
#   NUM_SEARCHERS=4                         # Number of searcher agents
#   SEARCH_WAIT_MS=120000                   # Timeout per search phase (ms)
#   WRITE_WAIT_MS=240000                    # Timeout for write phase (ms)
#   REVIEW_WAIT_MS=180000                   # Timeout for governance review (ms)
#   EDIT_WAIT_MS=300000                     # Timeout for editorial phase (ms)
#   AUTO_PUBLISH=false                      # Skip HITL gate (auto-approve)
#   CHAOS_MODE=false                        # Simulate random searcher crashes
#
# Multi-process entry point (global-research/node.ts):
#   NODE_TYPE=searcher|writer|reviewer|editor

# ── Agent guardrails ──────────────────────────────────────────────────────────
# Max time (ms) a single task handler may run before being forcibly timed out.
# Prevents infinite loops and runaway LLM calls. Default: 300000 (5 minutes).
AGENT_TIMEOUT_MS=300000
# Max cumulative tokens per AgentStatePublisher instance before it raises an error.
# Use to cap LLM spend per agent process. 0 = unlimited (default).
MAX_TOKEN_BUDGET=0
# Workflow-level spend guard for the example orchestrators (checked between phases
# and before each revision). Caps the WHOLE workflow's cumulative spend so a runaway
# (e.g. repeated revisions) stops gracefully instead of draining the budget. The
# example compose files default MAX_WORKFLOW_COST_USD to 0.50; 0 = unlimited.
MAX_WORKFLOW_COST_USD=0
MAX_WORKFLOW_TOKENS=0