melchizedek-agents 0.16.2 → 0.18.0

package/dist/lib/tools/urlContextTool.js

@@ -0,0 +1,39 @@
+/**
+ * lib/tools/urlContextTool.ts — `url_context`: the model reads the pages
+ * whose URLs appear in the conversation, server-side, on Gemini.
+ *
+ * WHY: ADK's URL_CONTEXT is Gemini's built-in URL reading, and it THROWS for
+ * any other model, which would fail a mixed-provider syndicate at request
+ * time. This is the same tool made safe to declare anywhere, the pattern
+ * web_search uses: on a Gemini model it adds `{ urlContext: {} }` to the
+ * request; on any other it does nothing, and `npm run doctor` reports it as
+ * dropped (lib/models/capabilities.ts). For reading a page on every
+ * provider, declare `web_extract` (client-side, SSRF-guarded).
+ *
+ * Exposure: Google fetches the URLs, not this host, so no address of this
+ * deployment's network is reachable through it. Page text arrives as model
+ * input; treat it as data, as any fetched page.
+ */
+import { BaseTool } from '@google/adk';
+import { providerForModel } from '../models/providerMap.js';
+export const URL_CONTEXT_TOOL_NAME = 'url_context';
+export class UrlContextTool extends BaseTool {
+    constructor() {
+        super({ name: URL_CONTEXT_TOOL_NAME, description: 'Gemini reads the pages at URLs in the conversation (server-side).' });
+    }
+    /** Never a client-side function tool. */
+    _getDeclaration() {
+        return undefined;
+    }
+    async runAsync() {
+        return Promise.resolve();
+    }
+    async processLlmRequest({ llmRequest }) {
+        if (!llmRequest.model || providerForModel(llmRequest.model) !== 'gemini')
+            return;
+        llmRequest.config = llmRequest.config ?? {};
+        llmRequest.config.tools = llmRequest.config.tools ?? [];
+        llmRequest.config.tools.push({ urlContext: {} });
+    }
+}
+export const URL_CONTEXT = new UrlContextTool();

package/dist/lib/workflow.d.ts

@@ -0,0 +1,72 @@
+/**
+ * lib/workflow.ts — the `workflow:` block: a syndicate as a graph.
+ *
+ * ── The third orchestration method ───────────────────────────────────────
+ * DELEGATE lets an orchestrator call subagents as tools; PLAN-DISPATCH
+ * (lib/dispatch.ts) lets a classifier pick ONE subagent to answer. Neither
+ * can say "run these two in parallel, join their outputs, review, ask the
+ * person, then publish". A `workflow:` block does: it is a graph whose
+ * nodes are the syndicate's own agents plus a few node kinds the engine
+ * supplies, and whose edges say what runs after what and on which route.
+ *
+ *   workflow:
+ *     edges:
+ *       - [START, Planner, { article: [Writer, Checker], answer: Answerer }]
+ *       - [[Writer, Checker], Both, Editor, Confirm, Publisher]
+ *     nodes:
+ *       Both:    { join: true }                 # waits for every predecessor
+ *       Confirm: { ask_user: "Publish? yes, or say what to change." }
+ *       Planner: { route_key: "kind", retry: { max_attempts: 2 } }
+ *
+ * ADK 2.2 runs it (`Workflow`, `FunctionNode`, `JoinNode`, `ParallelWorker`,
+ * `ToolNode`, `RequestInput`): per-node retries and timeouts, fan-out and
+ * fan-in, a pause that waits for a person and resumes on the next message,
+ * and resumption from the session's own events. Every agent is already a
+ * node (`LlmAgent extends BaseNode`): a node agent receives the previous
+ * node's output as its user turn and, unless its YAML sets
+ * `includeContents`, sees nothing else of the conversation.
+ *
+ * ── What the engine adds to ADK ───────────────────────────────────────────
+ * ROUTING. ADK's TypeScript port never derives a route from an agent's
+ *   output, so a routing map in YAML gets a hidden step after the agent
+ *   (`<Agent>__route`) that reads the route from the output — the
+ *   `route_key` property of a JSON output, else the trimmed text — and
+ *   re-emits the output with it. A `default` key catches what no key
+ *   matched.
+ * THE PAUSE. `ask_user` is a node that raises ADK's `RequestInput`. The
+ *   turn ends `input-required` carrying the question (`result.input`); the
+ *   next message on the conversation is the answer and becomes that node's
+ *   output. The A2A server publishes the question; the chat prints it.
+ * NAMES. Nodes are addressed by their YAML names everywhere (edges, events,
+ *   the wiki), including a `map` node, which ADK would otherwise name after
+ *   the agent it wraps.
+ *
+ * ── Not in this version ───────────────────────────────────────────────────
+ * Approval gates (`require_approval`, `skills.scripts: local`) and remote
+ * `a2a_agent_url` subagents are refused inside a workflow by the schema: a
+ * gated call pauses a node through ADK's interrupt path, whose resume is not
+ * the one ADR 0028 built, and a remote agent is reachable only as a tool.
+ * Both are open for a later record. A `Workflow` cannot yet be another
+ * agent's subagent (an ADK limit), so `yaml_reference` to a workflow
+ * syndicate compiles its orchestrator alone.
+ */
+import { Workflow } from '@google/adk';
+import type { BaseNode, LlmAgent } from '@google/adk';
+import type { CompileOptions } from './compile.ts';
+import type { SyndicateYamlConfig } from './loadSyndicate.ts';
+export * from './workflowConfig.ts';
+export interface CompiledWorkflow {
+    workflow: Workflow;
+    /** Every agent node by YAML name, compiled. */
+    agents: Map<string, LlmAgent>;
+    /** Every node by YAML name, hidden route steps excluded. */
+    nodes: Map<string, BaseNode>;
+}
+/**
+ * Compile a workflow syndicate: every agent through `compileSubagent` (its
+ * tools, skills and MCP server as in any mode), the declared nodes, the
+ * hidden route steps, and the edge chains, into one ADK `Workflow` named
+ * after the syndicate. Throws on a name the schema let through, a tool that
+ * is not registered, or a graph ADK rejects (unreachable node, cycle).
+ */
+export declare function compileWorkflow(config: SyndicateYamlConfig, opts?: CompileOptions, transformAgent?: (agent: LlmAgent) => LlmAgent): Promise<CompiledWorkflow>;

package/dist/lib/workflow.js

@@ -0,0 +1,180 @@
+/**
+ * lib/workflow.ts — the `workflow:` block: a syndicate as a graph.
+ *
+ * ── The third orchestration method ───────────────────────────────────────
+ * DELEGATE lets an orchestrator call subagents as tools; PLAN-DISPATCH
+ * (lib/dispatch.ts) lets a classifier pick ONE subagent to answer. Neither
+ * can say "run these two in parallel, join their outputs, review, ask the
+ * person, then publish". A `workflow:` block does: it is a graph whose
+ * nodes are the syndicate's own agents plus a few node kinds the engine
+ * supplies, and whose edges say what runs after what and on which route.
+ *
+ *   workflow:
+ *     edges:
+ *       - [START, Planner, { article: [Writer, Checker], answer: Answerer }]
+ *       - [[Writer, Checker], Both, Editor, Confirm, Publisher]
+ *     nodes:
+ *       Both:    { join: true }                 # waits for every predecessor
+ *       Confirm: { ask_user: "Publish? yes, or say what to change." }
+ *       Planner: { route_key: "kind", retry: { max_attempts: 2 } }
+ *
+ * ADK 2.2 runs it (`Workflow`, `FunctionNode`, `JoinNode`, `ParallelWorker`,
+ * `ToolNode`, `RequestInput`): per-node retries and timeouts, fan-out and
+ * fan-in, a pause that waits for a person and resumes on the next message,
+ * and resumption from the session's own events. Every agent is already a
+ * node (`LlmAgent extends BaseNode`): a node agent receives the previous
+ * node's output as its user turn and, unless its YAML sets
+ * `includeContents`, sees nothing else of the conversation.
+ *
+ * ── What the engine adds to ADK ───────────────────────────────────────────
+ * ROUTING. ADK's TypeScript port never derives a route from an agent's
+ *   output, so a routing map in YAML gets a hidden step after the agent
+ *   (`<Agent>__route`) that reads the route from the output — the
+ *   `route_key` property of a JSON output, else the trimmed text — and
+ *   re-emits the output with it. A `default` key catches what no key
+ *   matched.
+ * THE PAUSE. `ask_user` is a node that raises ADK's `RequestInput`. The
+ *   turn ends `input-required` carrying the question (`result.input`); the
+ *   next message on the conversation is the answer and becomes that node's
+ *   output. The A2A server publishes the question; the chat prints it.
+ * NAMES. Nodes are addressed by their YAML names everywhere (edges, events,
+ *   the wiki), including a `map` node, which ADK would otherwise name after
+ *   the agent it wraps.
+ *
+ * ── Not in this version ───────────────────────────────────────────────────
+ * Approval gates (`require_approval`, `skills.scripts: local`) and remote
+ * `a2a_agent_url` subagents are refused inside a workflow by the schema: a
+ * gated call pauses a node through ADK's interrupt path, whose resume is not
+ * the one ADR 0028 built, and a remote agent is reachable only as a tool.
+ * Both are open for a later record. A `Workflow` cannot yet be another
+ * agent's subagent (an ADK limit), so `yaml_reference` to a workflow
+ * syndicate compiles its orchestrator alone.
+ */
+import { DEFAULT_ROUTE, FunctionNode, JoinNode, ParallelWorker, RequestInput, ToolNode, Workflow, createEvent, } from '@google/adk';
+import { compileSubagent } from './compile.js';
+import { resolveTools as resolveNamedTools } from './toolRegistry.js';
+import { DEFAULT_ROUTE_KEY, ROUTE_STEP_SUFFIX, START_NAME, isWorkflowSyndicate, nodeKind, nodeSettings, routeOf } from './workflowConfig.js';
+export * from './workflowConfig.js';
+/**
+ * Compile a workflow syndicate: every agent through `compileSubagent` (its
+ * tools, skills and MCP server as in any mode), the declared nodes, the
+ * hidden route steps, and the edge chains, into one ADK `Workflow` named
+ * after the syndicate. Throws on a name the schema let through, a tool that
+ * is not registered, or a graph ADK rejects (unreachable node, cycle).
+ */
+export async function compileWorkflow(config, opts = {}, transformAgent = (a) => a) {
+    if (!isWorkflowSyndicate(config))
+        throw new Error(`${config.syndicate_name}: no workflow block`);
+    const wf = config.workflow;
+    const nodeYaml = wf.nodes ?? {};
+    const agentConfigs = new Map();
+    agentConfigs.set(config.orchestrator.name, { description: '', ...config.orchestrator });
+    for (const sub of config.subagents ?? [])
+        agentConfigs.set(sub.name, sub);
+    // Agents, with their node modifiers (retry, timeout) at construction.
+    const compileOpts = {
+        ...opts,
+        nodeConfig: (name) => {
+            const settings = nodeSettings(nodeYaml[name]);
+            return Object.keys(settings).length ? settings : undefined;
+        },
+    };
+    const agents = new Map();
+    for (const [name, sub] of agentConfigs)
+        agents.set(name, transformAgent(await compileSubagent(sub, compileOpts)));
+    // Declared nodes.
+    const nodes = new Map(agents);
+    for (const [name, entry] of Object.entries(nodeYaml)) {
+        const kind = nodeKind(entry);
+        if (!kind)
+            continue; // modifiers on an agent
+        const settings = nodeSettings(entry);
+        if (kind === 'ask_user') {
+            const message = entry.ask_user ?? '';
+            const schema = entry.schema;
+            // The node runs again on resume (rerunOnResume): ADK then hands it the
+            // same input and the answers resolved so far, so its output can carry
+            // BOTH the reply and what the person was asked about. A node fast-
+            // forwarded by ADK would output the bare reply, and the next agent
+            // would never see the draft it is meant to act on.
+            nodes.set(name, new FunctionNode(name, (ctx, input) => {
+                const replies = Object.values(ctx.resumeInputs);
+                if (replies.length > 0)
+                    return { reply: replies[replies.length - 1], input };
+                return new RequestInput({ message, payload: input, ...(schema ? { responseSchema: schema } : {}) });
+            }, { ...settings, rerunOnResume: true }));
+        }
+        else if (kind === 'join') {
+            nodes.set(name, new JoinNode({ name, ...settings }));
+        }
+        else if (kind === 'map') {
+            const inner = agents.get(entry.map);
+            if (!inner)
+                throw new Error(`workflow node '${name}': map names '${entry.map}', which is not an agent of this syndicate`);
+            const worker = new ParallelWorker(inner, entry.max_parallel !== undefined ? { maxParallelWorkers: entry.max_parallel } : {});
+            // ADK names a worker after the agent it wraps; the YAML name is what
+            // the edges, the events and the docs use.
+            Object.defineProperty(worker, 'name', { value: name, enumerable: true });
+            nodes.set(name, worker);
+        }
+        else if (kind === 'tool') {
+            const [tool] = resolveNamedTools([entry.tool], opts.onUnknownTool);
+            if (!tool)
+                throw new Error(`workflow node '${name}': tool '${entry.tool}' is not registered`);
+            nodes.set(name, new ToolNode(tool, { name, ...settings }));
+        }
+    }
+    const nodeOf = (name) => {
+        const node = nodes.get(name);
+        if (!node)
+            throw new Error(`workflow: '${name}' is not an agent or a declared node of this syndicate`);
+        return node;
+    };
+    const routeSteps = new Map();
+    const routeStepAfter = (name) => {
+        let step = routeSteps.get(name);
+        if (step)
+            return step;
+        const routeKey = nodeYaml[name]?.route_key ?? 'route';
+        const stepName = `${name}${ROUTE_STEP_SUFFIX}`;
+        step = new FunctionNode(stepName, (ctx, input) => createEvent({
+            author: stepName,
+            invocationId: ctx.invocationId,
+            branch: ctx.branch,
+            output: input,
+            route: routeOf(input, routeKey),
+        }));
+        routeSteps.set(name, step);
+        return step;
+    };
+    const edges = wf.edges.map((chain) => {
+        const out = [];
+        chain.forEach((element, i) => {
+            if (typeof element === 'string') {
+                out.push(element === START_NAME ? 'START' : nodeOf(element));
+            }
+            else if (Array.isArray(element)) {
+                out.push(element.map(nodeOf));
+            }
+            else {
+                const previous = chain[i - 1];
+                if (typeof previous !== 'string' || previous === START_NAME) {
+                    throw new Error(`workflow: a routing map must follow the name of the node whose output it routes`);
+                }
+                out.push(routeStepAfter(previous));
+                const map = {};
+                for (const [key, target] of Object.entries(element)) {
+                    map[key === DEFAULT_ROUTE_KEY ? DEFAULT_ROUTE : key] = Array.isArray(target) ? target.map(nodeOf) : nodeOf(target);
+                }
+                out.push(map);
+            }
+        });
+        return out;
+    });
+    const workflow = new Workflow({
+        name: config.syndicate_name,
+        edges,
+        ...(wf.max_concurrency !== undefined ? { maxConcurrency: wf.max_concurrency } : {}),
+    });
+    return { workflow, agents, nodes };
+}

package/dist/lib/workflowConfig.d.ts

@@ -0,0 +1,95 @@
+/**
+ * lib/workflowConfig.ts — the `workflow:` block's contract: its types, the
+ * names it reserves, and the pure helpers the schema (lib/syndicateSchema.ts),
+ * the compiler (lib/workflow.ts) and the turn runner share. No imports
+ * beyond types, so the schema can read it without pulling the compiler in.
+ */
+import type { RetryConfig as AdkRetryConfig } from '@google/adk';
+/** `START` in an edge chain: the graph's entry. Not a node. */
+export declare const START_NAME = "START";
+/** The routing-map key that catches an unmatched route. */
+export declare const DEFAULT_ROUTE_KEY = "default";
+/** Suffix of the hidden step inserted after an agent a routing map follows. */
+export declare const ROUTE_STEP_SUFFIX = "__route";
+/** One element of an edge chain: a name, several names (fan-out or fan-in), or a routing map. */
+export type EdgeElement = string | string[] | Record<string, string | string[]>;
+export interface RetryYaml {
+    /** Attempts including the first. 1 = no retry. Default 5 in ADK. */
+    max_attempts?: number;
+    /** Seconds before the first retry. */
+    initial_delay?: number;
+    max_delay?: number;
+    backoff_factor?: number;
+}
+/** Per-node settings. A node is an agent (modifiers only) or exactly one of the kinds. */
+export interface WorkflowNodeYaml {
+    /** Pause and ask the person this; the reply becomes the node's output. */
+    ask_user?: string;
+    /** JSON Schema a structured reply to `ask_user` must satisfy. A plain-text reply passes as is. */
+    schema?: Record<string, unknown>;
+    /** Wait for every predecessor, then output `{ <predecessor>: <output> }`. */
+    join?: true;
+    /** Run this agent once per item of a list input, concurrently; output the list of results. */
+    map?: string;
+    /** Concurrency of `map`. Default 8. */
+    max_parallel?: number;
+    /** Run this registry tool with the node input as its arguments. */
+    tool?: string;
+    /** Property of a JSON output holding the route (agents). Default "route". */
+    route_key?: string;
+    retry?: RetryYaml;
+    /** Seconds this node may run before it fails. */
+    timeout?: number;
+}
+export interface WorkflowConfig {
+    /** Chains, each a list of elements; `START` begins at least one of them. */
+    edges: EdgeElement[][];
+    nodes?: Record<string, WorkflowNodeYaml>;
+    /** Nodes that may run at once. Default: unbounded. */
+    max_concurrency?: number;
+}
+/** True when the syndicate is a graph (a `workflow:` block is present). */
+export declare function isWorkflowSyndicate(config: {
+    workflow?: unknown;
+}): config is {
+    workflow: WorkflowConfig;
+};
+export declare const NODE_KINDS: readonly ['ask_user', 'join', 'map', 'tool'];
+/** The kind a node entry declares, or undefined for a modifier-only entry (an agent). */
+export declare function nodeKind(node: WorkflowNodeYaml | undefined): (typeof NODE_KINDS)[number] | undefined;
+/** Every name an edge element references (`START` excluded). */
+export declare function elementNames(element: EdgeElement): string[];
+/** ADK's retry config from the YAML spelling. */
+export declare function toRetryConfig(retry: RetryYaml | undefined): AdkRetryConfig | undefined;
+/** The BaseNode fields a node entry's modifiers map to. */
+export declare function nodeSettings(node: WorkflowNodeYaml | undefined): {
+    retryConfig?: AdkRetryConfig;
+    timeout?: number;
+};
+/**
+ * The route an output names: the `routeKey` property of an object (a parsed
+ * JSON output), else the trimmed text. Never undefined, so an edge with a
+ * `default` key always has something to fall back from.
+ */
+export declare function routeOf(output: unknown, routeKey?: string): string;
+/** A pause raised by an `ask_user` node, read from the run's events (`adk_request_input`). */
+export interface PendingInput {
+    /** The interrupt id. A plain-text next message answers it. */
+    id: string;
+    /** The node that asked. */
+    node: string;
+    /** The question. */
+    message: string;
+    payload?: unknown;
+    /** JSON Schema a structured answer must satisfy, when the node declared one. */
+    schema?: unknown;
+}
+/** ADK's function-call name for a workflow input request. */
+export declare const INPUT_REQUEST = "adk_request_input";
+/** The request an `adk_request_input` call carries, or undefined for another call. */
+export declare function inputRequestFrom(author: string | undefined, call: {
+    name?: string;
+    args?: Record<string, unknown>;
+}): PendingInput | undefined;
+/** One line a person can read: what the workflow is waiting for. */
+export declare function describeInput(input: PendingInput): string;

package/dist/lib/workflowConfig.js

@@ -0,0 +1,93 @@
+/**
+ * lib/workflowConfig.ts — the `workflow:` block's contract: its types, the
+ * names it reserves, and the pure helpers the schema (lib/syndicateSchema.ts),
+ * the compiler (lib/workflow.ts) and the turn runner share. No imports
+ * beyond types, so the schema can read it without pulling the compiler in.
+ */
+/** `START` in an edge chain: the graph's entry. Not a node. */
+export const START_NAME = 'START';
+/** The routing-map key that catches an unmatched route. */
+export const DEFAULT_ROUTE_KEY = 'default';
+/** Suffix of the hidden step inserted after an agent a routing map follows. */
+export const ROUTE_STEP_SUFFIX = '__route';
+/** True when the syndicate is a graph (a `workflow:` block is present). */
+export function isWorkflowSyndicate(config) {
+    return !!config.workflow && typeof config.workflow === 'object';
+}
+export const NODE_KINDS = ['ask_user', 'join', 'map', 'tool'];
+/** The kind a node entry declares, or undefined for a modifier-only entry (an agent). */
+export function nodeKind(node) {
+    if (!node)
+        return undefined;
+    return NODE_KINDS.find((k) => node[k] !== undefined);
+}
+/** Every name an edge element references (`START` excluded). */
+export function elementNames(element) {
+    if (typeof element === 'string')
+        return element === START_NAME ? [] : [element];
+    if (Array.isArray(element))
+        return element;
+    return Object.values(element).flatMap((v) => (Array.isArray(v) ? v : [v]));
+}
+/** ADK's retry config from the YAML spelling. */
+export function toRetryConfig(retry) {
+    if (!retry)
+        return undefined;
+    const out = {};
+    if (retry.max_attempts !== undefined)
+        out.maxAttempts = retry.max_attempts;
+    if (retry.initial_delay !== undefined)
+        out.initialDelay = retry.initial_delay;
+    if (retry.max_delay !== undefined)
+        out.maxDelay = retry.max_delay;
+    if (retry.backoff_factor !== undefined)
+        out.backoffFactor = retry.backoff_factor;
+    return out;
+}
+/** The BaseNode fields a node entry's modifiers map to. */
+export function nodeSettings(node) {
+    const out = {};
+    const retry = toRetryConfig(node?.retry);
+    if (retry)
+        out.retryConfig = retry;
+    if (node?.timeout !== undefined)
+        out.timeout = node.timeout;
+    return out;
+}
+/**
+ * The route an output names: the `routeKey` property of an object (a parsed
+ * JSON output), else the trimmed text. Never undefined, so an edge with a
+ * `default` key always has something to fall back from.
+ */
+export function routeOf(output, routeKey = 'route') {
+    if (output && typeof output === 'object' && !Array.isArray(output)) {
+        const value = output[routeKey];
+        if (value === undefined || value === null)
+            return '';
+        return String(value).trim();
+    }
+    if (typeof output === 'string')
+        return output.trim();
+    return output === undefined || output === null ? '' : String(output).trim();
+}
+/** ADK's function-call name for a workflow input request. */
+export const INPUT_REQUEST = 'adk_request_input';
+/** The request an `adk_request_input` call carries, or undefined for another call. */
+export function inputRequestFrom(author, call) {
+    if (call.name !== INPUT_REQUEST)
+        return undefined;
+    const args = call.args ?? {};
+    return {
+        id: String(args.interruptId ?? ''),
+        node: author ?? '',
+        message: typeof args.message === 'string' ? args.message : '',
+        ...(args.payload !== undefined && args.payload !== null ? { payload: args.payload } : {}),
+        ...(args.response_schema !== undefined && args.response_schema !== null ? { schema: args.response_schema } : {}),
+    };
+}
+/** One line a person can read: what the workflow is waiting for. */
+export function describeInput(input) {
+    const options = input.payload?.options;
+    const choices = Array.isArray(options) && options.length ? ` (${options.join(' / ')})` : '';
+    return `${input.node} asks: ${input.message || '(no question text)'}${choices}`;
+}

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>;