melchizedek-agents 0.17.0 → 0.19.0

package/.env.example

@@ -19,6 +19,12 @@ GOOGLE_GENAI_API_KEY=
 # keep their task list and job queue. Default: outputs/tasks.json.
 # MELCHIZEDEK_TASKS_FILE=outputs/tasks.json
 
+# ── Optional: runtime (ADR 0045) ──────────────────────────────────────────────
+# Which runtime runs a turn's agents: adk (default) or native (the engine's own loop).
+# MELCHIZEDEK_RUNTIME=adk
+# Which adapter serves a Gemini model id on the native path: adk (default) or engine.
+# GEMINI_ADAPTER=adk
+
 # ── Optional: MCP (Model Context Protocol) ────────────────────────────────────
 # ALLOW_PRIVATE_MCP: set to "true" to permit mcp_server_url values pointing at
 # localhost / private / link-local hosts. Off by default as an SSRF guard;
@@ -129,6 +135,8 @@ A2A_SERVER_SECRET=
 # Used when compiling the AgentCard that advertises this agent to A2A clients.
 # Defaults to http://localhost:4000 if not set.
 # Only needed for cloud deployments where the server has a real public URL.
+# With it set, the server also refuses to start until A2A_AUTH,
+# A2A_SERVED_AGENTS and A2A_TRUST_PROXY are set explicitly (ADR 0039).
 PUBLIC_URL=
 
 # ── A2A server: identity and billing (all optional; ADR 0017, 0025) ─────────
@@ -141,6 +149,7 @@ PUBLIC_URL=
 #   jwt     a JWT from your identity provider; the scope comes from its claims.
 #   header  an authenticating gateway in front sets the user header; requires
 #           A2A_SERVER_SECRET, which only the gateway holds.
+# Required with PUBLIC_URL; prefer callers or jwt there.
 # A2A_AUTH=secret
 # callers: `name:sha256[:scope]` entries separated by ';'. The config holds only
 # each token's SHA-256. Mint one: npx melchizedek-serve --new-caller <name>
@@ -171,8 +180,8 @@ PUBLIC_URL=
 # The server refuses a database behind the migrations it ships (run
 # `npx melchizedek-db apply`); this starts it anyway.
 # ALLOW_SCHEMA_MISMATCH=false
-# Only these agent ids are served at /<agentId>/... (comma list). Unset = any
-# syndicate the loader can find.
+# Only these agent ids are served at /<agentId>/... (comma list). Unset, or *,
+# = any syndicate the loader can find. Required with PUBLIC_URL (* allowed).
 # A2A_SERVED_AGENTS=support_triage,research_brief
 # Per-task wall-clock budget (ms; 0 = none). Default 15 minutes.
 # A2A_TASK_TIMEOUT_MS=900000
@@ -191,11 +200,23 @@ PUBLIC_URL=
 # A2A_RATE_LIMIT_MAX=60
 # A2A_RATE_LIMIT_WINDOW_MS=900000
 # A2A_AUTH_FAILURE_MAX=30
-# Express trust-proxy: proxy hop count, true/false, or a subnet list. Default 1.
+# Express trust-proxy: proxy hop count, true/false, or a subnet list. Default
+# false (no proxy is trusted). Required with PUBLIC_URL: 1 behind one load
+# balancer, false when clients connect directly.
 # A2A_TRUST_PROXY=1
+# Concurrent tasks for one end user (scope), and for one caller. 0 = unlimited.
+# A2A_MAX_CONCURRENT_PER_SCOPE=4
+# A2A_MAX_CONCURRENT_PER_CALLER=0
+
+# OpenAPI tools: the exact environment variables an `auth:` may name. Unset, any
+# variable but the framework's own settings (this file's) is allowed.
+# OPENAPI_CREDENTIAL_ENVS=WEATHER_API_KEY,CRM_TOKEN
 # A2A_BODY_LIMIT=1mb
 # How long SIGTERM waits for running tasks before canceling them.
 # A2A_SHUTDOWN_GRACE_MS=25000
+# Of that, how long /readyz fails while requests are still served, so a load
+# balancer deregisters this instance before the listener closes.
+# A2A_SHUTDOWN_DELAY_MS=5000
 # Daily budgets per UTC day (ADR 0026), per caller and per scope (one end
 # user), on tasks, model calls and tokens. A task over budget ends `rejected`
 # with the reason. Counted in Postgres/Supabase (db/migrations/0004) when
@@ -219,6 +240,12 @@ PUBLIC_URL=
 # with `melchizedek-db apply --schema <name>` (or this variable) and run the
 # server with the same value. Needs DATABASE_URL.
 # MELCHIZEDEK_DB_SCHEMA=public
+# The key that seals third-party OAuth tokens held for tools, per end user, in
+# melchizedek_tool_credentials (migration 0013, ADR 0072): 32 random bytes as
+# base64 or 64 hex characters. Generate with `openssl rand -base64 32`; keep it
+# out of the database and its backups. Unset = no credential store. A row
+# sealed with another key stays unreadable (the user reconnects).
+# MELCHIZEDEK_CREDENTIAL_KEY=
 
 # ── Optional: Knowledge Bundle (wiki) ─────────────────────────────────────────
 # WIKI_ROOT: filesystem path of the OKF knowledge bundle the wiki tools serve.
@@ -279,6 +306,11 @@ WIKI_AGENT_MODEL=
 # retried with jittered backoff, honouring Retry-After up to 60 s, before any
 # output is produced. Total attempts per model call; 1 turns retries off.
 # MODEL_RETRY_MAX_ATTEMPTS=3
+# For agents with a fallback_model: after this many consecutive provider-side
+# failures a provider's circuit opens and those agents answer from their
+# fallback for the cooldown. 0 disables the breaker.
+# MODEL_BREAKER_THRESHOLD=5
+# MODEL_BREAKER_COOLDOWN_MS=30000
 # Per-attempt timeout for xAI (Grok) calls, ms; floor 120000.
 # XAI_TIMEOUT_MS=600000
 

package/AGENT_SETUP.md

@@ -193,7 +193,8 @@ user id.
 
 Deploying the server itself (Heroku, Fly, a VPS) needs `PUBLIC_URL` set
 — at which point the server refuses to start without the bearer secret,
-by design. Run `db/hardening.sql` before real user data arrives, and
+and until `A2A_AUTH`, `A2A_SERVED_AGENTS` and `A2A_TRUST_PROXY` are set
+explicitly, by design. Run `db/hardening.sql` before real user data arrives, and
 read the deployment notes in `lib/memory/README.md` end to end. The
 patient in module 2.02's specimen would expect no less of you.