melchizedek-agents 0.17.0 → 0.18.0

package/dist/lib/tools/openapiTools.js

@@ -20,7 +20,12 @@
  *     (ADR 0028), so a POST or a DELETE can wait for a person.
  *   - SECRETS FROM THE ENVIRONMENT. `auth` names an environment variable,
  *     never a value; a variable that is not set fails the compile, so an
- *     agent never runs half-authenticated.
+ *     agent never runs half-authenticated. A YAML (possibly registry-stored)
+ *     chooses both the variable and the host, so it may never name one of
+ *     the framework's own secrets (credentialEnvProblem): the database URL,
+ *     a provider key or an A2A secret cannot be sent to an API.
+ *     OPENAPI_CREDENTIAL_ENVS, when the operator sets it, is the exact list
+ *     of variables an `auth` may name.
  *   - THE SSRF GUARD. Every server URL the tools will call must be http(s)
  *     and pass lib/net/addressGuard.ts: its literal rules at compile time
  *     (offline), and the full check with DNS before each call (a name can
@@ -83,10 +88,35 @@ async function hostProblem(baseUrl, resolve) {
     const reason = resolve ? await checkHost(url.hostname) : blockedHostReason(url.hostname);
     return reason ? `refusing ${url.hostname}: ${reason} (set ALLOW_PRIVATE_OPENAPI=true for local development)` : null;
 }
+/** Prefixes and names of variables the framework itself reads: never an API credential. */
+const FRAMEWORK_ENV_PREFIXES = [
+    'A2A_', 'SUPABASE_', 'DATABASE_', 'MCP_', 'MODEL_', 'MEMORY_', 'OTEL_', 'TELEMETRY_', 'MELCHIZEDEK_',
+    'GOOGLE_', 'GEMINI_', 'ANTHROPIC_', 'OPENAI_', 'AZURE_', 'AWS_', 'XAI_', 'MOONSHOT_', 'OLLAMA_', 'WIKI_',
+    'ALLOW_', 'OPENAPI_',
+];
+const FRAMEWORK_ENV_NAMES = new Set(['PUBLIC_URL', 'HOST', 'PORT', 'PATH', 'HOME', 'NODE_OPTIONS', 'WEB_EXTRACT_CHAR_LIMIT']);
+/**
+ * Why an `auth` may not read this variable, or null. With
+ * OPENAPI_CREDENTIAL_ENVS set, only the names it lists are allowed; without
+ * it, anything but the framework's own variables is.
+ */
+export function credentialEnvProblem(name, env = process.env) {
+    const allow = env.OPENAPI_CREDENTIAL_ENVS?.split(',').map((s) => s.trim()).filter(Boolean);
+    if (allow?.length) {
+        return allow.includes(name) ? null : `${name} is not in OPENAPI_CREDENTIAL_ENVS (${allow.join(', ')})`;
+    }
+    if (FRAMEWORK_ENV_NAMES.has(name) || FRAMEWORK_ENV_PREFIXES.some((p) => name.startsWith(p))) {
+        return `${name} is one of the framework's own settings and may not be sent to an API; give the API its own variable (or list it in OPENAPI_CREDENTIAL_ENVS)`;
+    }
+    return null;
+}
 function credentialFor(auth, spec) {
     if (!auth)
         return {};
     const read = (env) => {
+        const refused = credentialEnvProblem(env);
+        if (refused)
+            throw new Error(`openapi ${spec}: ${refused}`);
         const value = process.env[env]?.trim();
         if (!value)
             throw new Error(`openapi ${spec}: ${env} is not set (auth reads it from the environment)`);

package/dist/scripts/a2a_server.js

@@ -25,7 +25,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  *                             with A2A_AUTH=callers it stays valid beside the caller
  *                             tokens, with its old scoping, until you remove it
  *   A2A_AUTH                  who a caller is (ADR 0025): secret (default) | callers |
- *                             jwt | header
+ *                             jwt | header (required with PUBLIC_URL, ADR 0039)
  *   A2A_CALLERS               callers: `name:sha256[:scope]; …` — one token per calling
  *                             backend. Mint: melchizedek-serve --new-caller <name>
  *   A2A_JWT_JWKS_URL          jwt: your identity provider's JWKS (or A2A_JWT_SECRET, HS256)
@@ -39,20 +39,25 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  *   ALLOW_UNHARDENED_DB       "true" to accept an unhardened Supabase schema
  *   A2A_TASK_TIMEOUT_MS       per-task wall-clock budget (900000; 0 = none)
  *   A2A_MAX_CONCURRENT_TASKS  concurrent tasks across all agents (0 = unlimited)
+ *   A2A_MAX_CONCURRENT_PER_SCOPE   concurrent tasks for one end user (4; 0 = unlimited)
+ *   A2A_MAX_CONCURRENT_PER_CALLER  concurrent tasks for one caller (0 = unlimited)
  *   A2A_RATE_LIMIT_MAX        task submissions per window per IP (60)
  *   A2A_RATE_LIMIT_WINDOW_MS  rate-limit window (900000)
  *   A2A_AUTH_FAILURE_MAX      failed authentications per window per IP (30)
- *   A2A_TRUST_PROXY           Express trust-proxy: hop count, true/false, or subnets (1)
+ *   A2A_TRUST_PROXY           Express trust-proxy: hop count, true/false, or subnets
+ *                             (false; required with PUBLIC_URL)
  *   A2A_BODY_LIMIT            JSON body limit ("1mb")
  *   A2A_KEY_MODE              server (default): models run on the server's keys;
  *                             byok: the caller's X-API-Key pays. Under A2A_AUTH=secret
  *                             the mode also scopes data: X-User-Id in server mode,
  *                             the key's hash in byok (the pre-0.16 behaviour)
  *   A2A_SERVED_AGENTS         comma list: the only agent ids /:agentId/ serves;
- *                             only these may fall back to examples/ and templates/
+ *                             only these may fall back to examples/ and templates/;
+ *                             * serves every one (required with PUBLIC_URL)
  *   A2A_REGISTRY_AGENTS       comma list: bare ids that load from adk_agent_registry
  *                             (others are files; registry:<id> always is the registry)
  *   A2A_SHUTDOWN_GRACE_MS     how long SIGTERM waits for running tasks (25000)
+ *   A2A_SHUTDOWN_DELAY_MS     of that, how long /readyz fails while requests are still served (5000)
  *   A2A_BUDGETS               daily budgets per UTC day (ADR 0026), JSON:
  *                             {"perCaller":{"tasks":500,"llmCalls":5000,"tokens":5000000},
  *                              "callers":{"reports":{"tasks":100}},"perScope":{"tasks":50}}.
@@ -101,8 +106,10 @@ function envInt(name, fallback) {
 }
 function envTrustProxy() {
     const raw = process.env.A2A_TRUST_PROXY?.trim();
+    // Unset: trust no proxy, so a client cannot choose its own IP with
+    // X-Forwarded-For. A public server must set it (the posture check below).
     if (!raw)
-        return 1;
+        return false;
     if (/^\d+$/.test(raw))
         return Number(raw);
     if (raw === 'true')
@@ -219,7 +226,28 @@ export async function startServer(syndicateName = 'syndicate.yaml', extensions =
         }
         return n;
     };
-    const servedAgents = list('A2A_SERVED_AGENTS');
+    // `*` serves every file in the agents directory and every registry row,
+    // stated on purpose; unset means the same off a public URL (ADR 0039).
+    const servedList = list('A2A_SERVED_AGENTS');
+    const servedAgents = servedList?.length === 1 && servedList[0] === '*' ? undefined : servedList;
+    // ── Public posture (ADR 0039) ──────────────────────────────────────────────
+    // A server on a public URL states how it authenticates, which agents it
+    // answers, and how many proxies stand in front of it. Each default was the
+    // permissive choice, so none is taken silently here.
+    if (publicUrl) {
+        const missing = [];
+        if (!process.env.A2A_AUTH?.trim()) {
+            missing.push('A2A_AUTH: callers or jwt (one identity per caller; recommended), header (a gateway authenticates users), or secret (one shared secret; any holder can act as any user by naming them in X-User-Id)');
+        }
+        if (!servedList?.length) {
+            missing.push('A2A_SERVED_AGENTS: the agent ids this server answers, comma-separated, or * for every file in the agents directory and every registry row');
+        }
+        if (!process.env.A2A_TRUST_PROXY?.trim()) {
+            missing.push('A2A_TRUST_PROXY: how many proxies stand in front of this server (1 behind one load balancer), or false when clients connect directly');
+        }
+        if (missing.length)
+            fatal(`PUBLIC_URL is set, so this server must state its security posture. Set:\n  - ${missing.join('\n  - ')}`);
+    }
     const registryAgents = list('A2A_REGISTRY_AGENTS');
     // Storage: Postgres when DATABASE_URL is set (every durable store, safe
     // across instances); otherwise createA2AApp's default (Supabase, else memory).
@@ -305,6 +333,8 @@ export async function startServer(syndicateName = 'syndicate.yaml', extensions =
             allowSchemaMismatch: process.env.ALLOW_SCHEMA_MISMATCH?.trim().toLowerCase() === 'true',
             turnLockWaitMs: envInt('A2A_TURN_LOCK_WAIT_MS', 30_000),
             maxConcurrentTasks: envInt('A2A_MAX_CONCURRENT_TASKS', 0),
+            maxConcurrentPerScope: envInt('A2A_MAX_CONCURRENT_PER_SCOPE', 4),
+            maxConcurrentPerCaller: envInt('A2A_MAX_CONCURRENT_PER_CALLER', 0),
             rateLimit: { windowMs: envInt('A2A_RATE_LIMIT_WINDOW_MS', 15 * 60 * 1000), max: envInt('A2A_RATE_LIMIT_MAX', 60) },
             authFailureLimit: { windowMs: 15 * 60 * 1000, max: envInt('A2A_AUTH_FAILURE_MAX', 30) },
             trustProxy: envTrustProxy(),
@@ -334,7 +364,7 @@ export async function startServer(syndicateName = 'syndicate.yaml', extensions =
     const authMode = `${identityLabel || (secret ? 'bearer secret' : 'no secret (loopback only)')}; keys: ${keyMode === 'byok' ? "caller's X-API-Key (byok)" : "server's own"}`;
     // The secret is not needed past this point; drop the reference.
     secret = undefined;
-    const { app, config, sessionBackend, shutdown } = built;
+    const { app, config, sessionBackend, shutdown, markUnready } = built;
     const server = await new Promise((resolve) => {
         const s = host ? app.listen(port, host, () => resolve(s)) : app.listen(port, () => resolve(s));
     });
@@ -364,13 +394,26 @@ export async function startServer(syndicateName = 'syndicate.yaml', extensions =
     // ── Lifecycle ──────────────────────────────────────────────────────────────
     let stopping = false;
     const graceMs = envInt('A2A_SHUTDOWN_GRACE_MS', 25_000);
+    // A load balancer keeps sending requests for a few seconds after SIGTERM,
+    // until it sees /readyz fail and deregisters this instance. Closing the
+    // listener at once would refuse those requests; fail readiness first and
+    // keep serving for the delay, then close and drain. The delay is part of
+    // the grace budget (running tasks keep running through it), so a stop still
+    // takes at most A2A_SHUTDOWN_GRACE_MS, inside Kubernetes' default 30 s.
+    const delayMs = Math.min(envInt('A2A_SHUTDOWN_DELAY_MS', 5_000), graceMs);
     const stop = async (signal) => {
         if (stopping)
             return;
         stopping = true;
-        emit('info', `[A2A] ${signal}: draining — no new tasks; waiting up to ${graceMs} ms for running ones.`);
+        markUnready();
+        if (delayMs > 0) {
+            emit('info', `[A2A] ${signal}: /readyz now fails; still serving for ${delayMs} ms while the load balancer deregisters this instance.`);
+            await new Promise((r) => setTimeout(r, delayMs));
+        }
+        const drainMs = graceMs - delayMs;
+        emit('info', `[A2A] ${signal}: draining — no new tasks; waiting up to ${drainMs} ms for running ones.`);
         server.close();
-        const canceled = await shutdown(graceMs);
+        const canceled = await shutdown(drainMs);
         if (canceled > 0)
             emit('warn', `[A2A] ⚠ ${canceled} task(s) did not finish in time and were canceled.`);
         // Give canceled tasks a moment to publish their final status, then flush

package/dist/scripts/db.d.ts

@@ -22,5 +22,14 @@
 /** db/migrations/NNNN_name.sql, in numeric order. */
 export declare function migrationFiles(dir?: string): string[];
 export declare function installOrder(withTelemetry: boolean): string[];
+/**
+ * The whole install as one psql script: an advisory lock first, then every
+ * file in order with a progress line before each. psql runs it with
+ * --single-transaction and ON_ERROR_STOP, so a failure anywhere rolls the
+ * whole install back (no half-applied migration), and a second `apply`
+ * started meanwhile waits on the lock instead of interleaving with this one.
+ */
+export declare const APPLY_LOCK_KEY = "melchizedek-db apply";
+export declare function applyScript(files: string[], sqlOf: (file: string) => string, label?: (file: string) => string): string;
 /** postgres://user:pass@host:port/db?sslmode=… → libpq environment variables. */
 export declare function pgEnv(url: string): Record<string, string>;

package/dist/scripts/db.js

@@ -42,6 +42,20 @@ export function installOrder(withTelemetry) {
     const base = [...migrationFiles(), 'hardening.sql'];
     return withTelemetry ? [...base, 'telemetry.sql', 'hardening.sql'] : base;
 }
+/**
+ * The whole install as one psql script: an advisory lock first, then every
+ * file in order with a progress line before each. psql runs it with
+ * --single-transaction and ON_ERROR_STOP, so a failure anywhere rolls the
+ * whole install back (no half-applied migration), and a second `apply`
+ * started meanwhile waits on the lock instead of interleaving with this one.
+ */
+export const APPLY_LOCK_KEY = 'melchizedek-db apply';
+export function applyScript(files, sqlOf, label = (f) => `db/${f}`) {
+    const parts = [`SELECT pg_advisory_xact_lock(hashtext('${APPLY_LOCK_KEY}'));\n`];
+    for (const file of files)
+        parts.push(`\\echo '→ applying ${label(file).replace(/'/g, '')}'\n`, sqlOf(file), '\n');
+    return parts.join('');
+}
 /** postgres://user:pass@host:port/db?sslmode=… → libpq environment variables. */
 export function pgEnv(url) {
     const u = new URL(url);
@@ -100,21 +114,22 @@ async function main() {
                 console.error('  or set DATABASE_URL to the Postgres connection string (Supabase: Settings → Database).');
                 process.exit(1);
             }
-            for (const file of installOrder(withTelemetry)) {
-                console.log(`→ applying db/${file}${schema === 'public' ? '' : ` into schema ${schema}`}`);
-                const r = spawnSync('psql', ['-v', 'ON_ERROR_STOP=1', '-q', '-f', '-'], {
-                    input: sqlOf(file),
-                    stdio: ['pipe', 'inherit', 'inherit'],
-                    // The connection goes to psql as PG* variables, never as an
-                    // argument, so the password stays out of the process list.
-                    env: { ...process.env, ...pgEnv(url) },
-                });
-                if (r.error) {
-                    console.error(`✗ could not run psql (${r.error.message}). Install the Postgres client, or use \`print\`.`);
-                    process.exit(1);
-                }
-                if (r.status !== 0)
-                    process.exit(r.status ?? 1);
+            // One transaction under one lock (see applyScript): all of it, or none.
+            const script = applyScript(installOrder(withTelemetry), sqlOf, (f) => `db/${f}${schema === 'public' ? '' : ` into schema ${schema}`}`);
+            const r = spawnSync('psql', ['-v', 'ON_ERROR_STOP=1', '-q', '--single-transaction', '-f', '-'], {
+                input: script,
+                stdio: ['pipe', 'inherit', 'inherit'],
+                // The connection goes to psql as PG* variables, never as an
+                // argument, so the password stays out of the process list.
+                env: { ...process.env, ...pgEnv(url) },
+            });
+            if (r.error) {
+                console.error(`✗ could not run psql (${r.error.message}). Install the Postgres client, or use \`print\`.`);
+                process.exit(1);
+            }
+            if (r.status !== 0) {
+                console.error('✗ the install failed and was rolled back: the database is as it was before `apply`.');
+                process.exit(r.status ?? 1);
             }
             console.log('✓ database is installed and hardened');
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "melchizedek-agents",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "A multi-model, multi-agent orchestration framework on Google ADK — YAML-defined syndicates, Supabase session persistence, pgvector long-term memory. Companion repo to the lyceumagents.com curriculum.",
   "type": "module",
   "license": "MIT",
@@ -12,7 +12,7 @@
   "bugs": {
     "url": "https://github.com/jhwadman/melch-ai/issues"
   },
-  "//": "adk + genai are pinned exact in dev: newer genai minors change response part shapes and silently break the chat printer. Bump deliberately, verify a live run, then update the pin. adk itself is a PEER dependency — the consumer's app owns the ADK instance so the model registry is a singleton.",
+  "//": "adk + genai are pinned exact in dev: newer genai minors change response part shapes and silently break the chat printer. Bump deliberately, verify a live run, then update the pin. adk itself is a PEER dependency — the consumer's app owns the ADK instance so the model registry is a singleton. The adk peer range is capped to the tested minor (~2.2.0): a new adk minor can pull a second genai copy, so the range widens only after a release is tested against it.",
   "engines": {
     "node": ">=22.6.0"
   },
@@ -126,7 +126,7 @@
     "@anthropic-ai/bedrock-sdk": ">=0.20.0",
     "@anthropic-ai/vertex-sdk": ">=0.11.0",
     "@azure/identity": ">=4.0.0",
-    "@google/adk": "^2.2.0",
+    "@google/adk": "~2.2.0",
     "redis": ">=4.6.0"
   },
   "dependencies": {