melchizedek-agents 0.16.2 → 0.18.0

package/dist/lib/runtime/questions.d.ts

@@ -0,0 +1,55 @@
+/**
+ * lib/runtime/questions.ts — an agent asks the person a question mid-turn,
+ * and the next message is the answer.
+ *
+ * WHY: A syndicate that is put in front of users needs to ask: "which of
+ * these three accounts?", "what is the order number?". Before this, an
+ * agent could only end its turn with a question in its text and hope the
+ * next message answered it, with nothing in the session saying a question
+ * was open. `ask_user` is ADK's long-running tool mechanism under one YAML
+ * name: the call is recorded, the run ends without a response to it, the
+ * turn ends `input-required` (`result.input`), and the next message on the
+ * conversation becomes the call's response, so the agent resumes its own
+ * tool loop where it asked, with the question and the answer side by side
+ * in its history.
+ *
+ * The same `input-required` path carries a workflow's `ask_user` node
+ * (lib/workflow.ts) and an approval (ADR 0028); a client handles all three
+ * by showing `result.input` (or the approval) and sending the next message.
+ *
+ * WHERE: only on an agent the turn runs directly (the orchestrator, or a
+ * plan-dispatch route), as with approval gates: inside a delegated
+ * subagent ADK swallows the pause. Not inside a workflow node yet. The
+ * schema refuses both.
+ */
+import { LongRunningFunctionTool } from '@google/adk';
+import type { Event } from '@google/adk';
+import { z } from 'zod';
+import type { PendingInput } from '../workflowConfig.ts';
+/** The registry name, and the function-call name an open question carries. */
+export declare const ASK_USER = "ask_user";
+export declare const MAX_OPTIONS = 10;
+/**
+ * The tool. Its execute returns nothing: a long-running call with no result
+ * ends the run, and ADK waits for a function response with the call's id.
+ */
+export declare const askUserTool: LongRunningFunctionTool<z.ZodObject<{
+    question: z.ZodString;
+    options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>>;
+/** The question an `ask_user` call carries, as the turn result reports it. */
+export declare function questionFrom(author: string | undefined, call: {
+    name?: string;
+    id?: string;
+    args?: Record<string, unknown>;
+}): PendingInput | undefined;
+/**
+ * The question still waiting for an answer in a session, or undefined. A
+ * question the person moved past (a text message after it was answered)
+ * is not pending; an answered one carries a function response with its id.
+ */
+export declare function pendingQuestion(events: readonly Event[]): PendingInput | undefined;
+/** The message part that answers question `id` with the person's text. */
+export declare function questionAnswerPart(id: string, answer: string): Record<string, unknown>;
+/** Index of the user message that started the turn holding call `id` (replayed raw on a dispatch resume). */
+export declare function turnStartOfCall(events: readonly Event[], id: string): number;

package/dist/lib/runtime/questions.js

@@ -0,0 +1,107 @@
+/**
+ * lib/runtime/questions.ts — an agent asks the person a question mid-turn,
+ * and the next message is the answer.
+ *
+ * WHY: A syndicate that is put in front of users needs to ask: "which of
+ * these three accounts?", "what is the order number?". Before this, an
+ * agent could only end its turn with a question in its text and hope the
+ * next message answered it, with nothing in the session saying a question
+ * was open. `ask_user` is ADK's long-running tool mechanism under one YAML
+ * name: the call is recorded, the run ends without a response to it, the
+ * turn ends `input-required` (`result.input`), and the next message on the
+ * conversation becomes the call's response, so the agent resumes its own
+ * tool loop where it asked, with the question and the answer side by side
+ * in its history.
+ *
+ * The same `input-required` path carries a workflow's `ask_user` node
+ * (lib/workflow.ts) and an approval (ADR 0028); a client handles all three
+ * by showing `result.input` (or the approval) and sending the next message.
+ *
+ * WHERE: only on an agent the turn runs directly (the orchestrator, or a
+ * plan-dispatch route), as with approval gates: inside a delegated
+ * subagent ADK swallows the pause. Not inside a workflow node yet. The
+ * schema refuses both.
+ */
+import { LongRunningFunctionTool } from '@google/adk';
+import { z } from 'zod';
+/** The registry name, and the function-call name an open question carries. */
+export const ASK_USER = 'ask_user';
+export const MAX_OPTIONS = 10;
+/**
+ * The tool. Its execute returns nothing: a long-running call with no result
+ * ends the run, and ADK waits for a function response with the call's id.
+ */
+export const askUserTool = new LongRunningFunctionTool({
+    name: ASK_USER,
+    description: 'Ask the person one question and wait for their answer before you continue: a missing detail you need, or a choice only they can make. ' +
+        'Pass `options` when the answer is one of a few choices. The turn ends here; the person\'s next message is the answer, returned to you as this call\'s result. ' +
+        'Ask only what you cannot find out or reasonably assume, one question per call.',
+    parameters: z.object({
+        question: z.string().min(1).max(500).describe('The question, as the person will read it.'),
+        options: z
+            .array(z.string().min(1).max(120))
+            .max(MAX_OPTIONS)
+            .optional()
+            .describe('The choices, when the answer is one of a few. Omit for a free answer.'),
+    }),
+    execute: async (_args, context) => {
+        if (context)
+            context.actions.skipSummarization = true;
+        return null;
+    },
+});
+const partsOf = (e) => (e.content?.parts ?? []);
+const hasUserText = (e) => e.author === 'user' && partsOf(e).some((p) => typeof p.text === 'string' && p.text.trim() && !p.thought);
+/** The question an `ask_user` call carries, as the turn result reports it. */
+export function questionFrom(author, call) {
+    if (call.name !== ASK_USER || !call.id)
+        return undefined;
+    const args = call.args ?? {};
+    const options = Array.isArray(args.options) ? args.options.filter((o) => typeof o === 'string') : [];
+    return {
+        id: call.id,
+        node: author ?? '',
+        message: typeof args.question === 'string' ? args.question : '',
+        ...(options.length ? { payload: { options } } : {}),
+    };
+}
+/**
+ * The question still waiting for an answer in a session, or undefined. A
+ * question the person moved past (a text message after it was answered)
+ * is not pending; an answered one carries a function response with its id.
+ */
+export function pendingQuestion(events) {
+    const answered = new Set();
+    for (let i = events.length - 1; i >= 0; i--) {
+        const e = events[i];
+        if (hasUserText(e))
+            return undefined;
+        for (const p of partsOf(e)) {
+            if (p.functionResponse?.name === ASK_USER && p.functionResponse.id)
+                answered.add(p.functionResponse.id);
+        }
+        for (const p of partsOf(e)) {
+            const call = p.functionCall;
+            if (call?.name !== ASK_USER || !call.id || answered.has(call.id))
+                continue;
+            return questionFrom(e.author, call);
+        }
+    }
+    return undefined;
+}
+/** The message part that answers question `id` with the person's text. */
+export function questionAnswerPart(id, answer) {
+    return { functionResponse: { id, name: ASK_USER, response: { result: answer } } };
+}
+/** Index of the user message that started the turn holding call `id` (replayed raw on a dispatch resume). */
+export function turnStartOfCall(events, id) {
+    let callAt = -1;
+    for (let i = events.length - 1; i >= 0 && callAt === -1; i--) {
+        if (partsOf(events[i]).some((p) => p.functionCall?.id === id))
+            callAt = i;
+    }
+    for (let i = callAt; i >= 0; i--)
+        if (hasUserText(events[i]))
+            return i;
+    return Math.max(0, callAt);
+}

package/dist/lib/runtime/syndicateTurn.d.ts

@@ -26,12 +26,17 @@
  * time, and an outer AbortSignal cancels it. All three abort the provider
  * request in flight, not just the loop around it.
  */
+import type { BasePlugin } from '@google/adk';
 import type { BaseMemoryService, BaseSessionService, Event, LlmAgent } from '@google/adk';
+import type { PendingInput } from '../workflow.ts';
+export { describeInput } from '../workflow.ts';
+export type { PendingInput } from '../workflow.ts';
 import type { CompileOptions } from '../compile.ts';
 import type { RouteResolution } from '../dispatch.ts';
 import type { SyndicateYamlConfig } from '../loadSyndicate.ts';
+export { ASK_USER, pendingQuestion, questionAnswerPart } from './questions.ts';
 import type { PendingApproval } from './approvals.ts';
-export { approvalResponsePart, pendingApproval } from './approvals.ts';
+export { approvalResponsePart, describeApproval, pendingApproval } from './approvals.ts';
 export type { PendingApproval } from './approvals.ts';
 import type { TurnStopReason } from './turnControl.ts';
 /** One part of the user's message. Text is the common case; the genai part
@@ -72,6 +77,8 @@ export interface TraceOptions {
         traceId: string;
         spanId: string;
     }) => void;
+    /** A caller's W3C traceparent: the turn's root span links to it (never joins it). */
+    traceparent?: string;
 }
 export interface SyndicateTurnOptions {
     config: SyndicateYamlConfig;
@@ -95,7 +102,7 @@ export interface SyndicateTurnOptions {
     signal?: AbortSignal;
     /** Wall-clock budget for the turn, in ms. Default: none. */
     deadlineMs?: number;
-    /** Model-call ceiling for the whole turn. Default: the YAML's `max_steps`. */
+    /** Model-call ceiling for the whole turn. Default: the YAML's `max_steps`, else DEFAULT_MAX_STEPS (50). */
     maxLlmCalls?: number;
     /** Ask adapters for token-by-token partial events (the REPL's live view). */
     streaming?: boolean;
@@ -140,11 +147,20 @@ export interface DrainedRun {
         code: string;
         message: string;
     };
+    /** Workflow runs: questions `ask_user` nodes raised (`adk_request_input`). */
+    inputRequests: PendingInput[];
+    /** Workflow runs: errors nodes reported along the way (a retried attempt, a failed node). */
+    nodeErrors: Array<{
+        node: string;
+        code: string;
+        message: string;
+    }>;
 }
-export type TurnStage = 'classify' | 'dispatch' | 'delegate';
+export type TurnStage = 'classify' | 'dispatch' | 'delegate' | 'workflow';
 export interface RouteDecision extends RouteResolution {
-    /** `approval`: the turn resumed the route that asked for an approval (ADR 0028). */
-    decidedBy: 'override' | 'forced' | 'classifier' | 'approval';
+    /** `approval`: the turn resumed the route that asked for an approval (ADR 0028).
+     *  `answer`: the message answered the route's open `ask_user` question. */
+    decidedBy: 'override' | 'forced' | 'classifier' | 'approval' | 'answer';
 }
 export interface SyndicateTurnResult {
     /** completed: an answer was produced. failed: an error, a deadline or the
@@ -154,6 +170,9 @@ export interface SyndicateTurnResult {
     /** The call waiting for approval, when status is input-required. Answer it
      *  with `approvalResponsePart(approval.id, approved)` as the next turn's part. */
     approval?: PendingApproval;
+    /** The question a workflow's `ask_user` node asked, when status is
+     *  input-required. The next message on the conversation is the answer. */
+    input?: PendingInput;
     /** The text the user receives (relay fallback and guards applied). */
     text: string;
     error?: {
@@ -188,6 +207,20 @@ export interface TurnUsage {
     outputTokens: number;
     thinkingTokens: number;
 }
+export declare const DEFAULT_MODEL_ERROR_RETRIES = 2;
+export declare const DEFAULT_TOOL_ERROR_RETRIES = 3;
+/**
+ * ADK's reflect-and-retry plugins, on by default. The model plugin turns a
+ * reply ADK marks malformed (MALFORMED_FUNCTION_CALL) into a retry with
+ * guidance instead of a failed turn; the tool plugin answers a tool that
+ * threw with structured guidance and caps its retries. Every retry is a
+ * model call under the turn's max_steps. Fresh instances per run: their
+ * counters are per invocation, but a run is the unit a surface reasons in.
+ */
+export declare function retryPlugins(retries: {
+    model_errors?: number;
+    tool_errors?: number;
+} | undefined): BasePlugin[];
 /**
  * Drains one ADK event stream into a DrainedRun. The answer is the LAST
  * event's text, not every event's: a tool-using agent narrates between
@@ -203,6 +236,13 @@ export declare function drainAgentStream(stream: AsyncIterable<Event>, opts?: {
     subagentNames?: Set<string>;
     /** Forward partial reply text to events.onTextDelta (answering stages only). */
     streamText?: boolean;
+    /**
+     * What an event carrying an error means. `fail` (default): the run is
+     * over, the error is the result. `collect`: note it and read on — a
+     * workflow node that will retry emits its failed attempt, and a node
+     * that gives up ends the stream itself.
+     */
+    errorPolicy?: 'fail' | 'collect';
 }): Promise<DrainedRun>;
 /** True when an orchestrator's text is just the name of a tool it called —
  *  the degenerate relay ("FinancialAnalyst", 3 tokens). Deliberately narrow:

package/dist/lib/runtime/syndicateTurn.js

@@ -26,8 +26,11 @@
  * time, and an outer AbortSignal cancels it. All three abort the provider
  * request in flight, not just the loop around it.
  */
-import { InMemorySessionService, Runner, StreamingMode, getFunctionCalls, getFunctionResponses } from '@google/adk';
-import { compileGraph, compileSubagent } from '../compile.js';
+import { InMemorySessionService, ReflectAndRetryModelPlugin, ReflectAndRetryToolPlugin, Runner, StreamingMode, getFunctionCalls, getFunctionResponses } from '@google/adk';
+import { DEFAULT_MAX_STEPS } from '../config.js';
+import { agentGates, compileGraph, compileSubagent } from '../compile.js';
+import { ROUTE_STEP_SUFFIX, compileWorkflow, describeInput, inputRequestFrom, isWorkflowSyndicate } from '../workflow.js';
+export { describeInput } from '../workflow.js';
 import { isDispatchSyndicate, matchRouteOverride, resolveRoute } from '../dispatch.js';
 import { collectGrounding, describeGrounding, newGroundingState, webSourcesLine } from '../grounding.js';
 import { resolveGuards } from '../guards/index.js';
@@ -36,13 +39,36 @@ import { registerAvailableProviders } from '../models/registry.js';
 import { traceAgentRun } from '../observability/tracer.js';
 import { ProjectedSessionService, renderTranscriptDigest } from '../session/transcript.js';
 import { approvalDecisionIn, describeApproval, interruptedTurnStart, pendingApproval } from './approvals.js';
-export { approvalResponsePart, pendingApproval } from './approvals.js';
+import { pendingQuestion, questionAnswerPart, questionFrom, turnStartOfCall } from './questions.js';
+export { ASK_USER, pendingQuestion, questionAnswerPart } from './questions.js';
+export { approvalResponsePart, describeApproval, pendingApproval } from './approvals.js';
 import { RemoteA2AAgent, remoteContextId, remoteToolOutput } from '../a2a/remoteAgent.js';
 import { createTurnControl, runWithTurnControl, stopCode, stopMessage } from './turnControl.js';
 const THOUGHTS_PREVIEW_CHARS = 600;
 const CLASSIFIER_PREAMBLE = `RECENT CONVERSATION, oldest first — context for your classification only. `
     + `Never answer it, and never route on it alone; it is here so you can tell a `
     + `follow-up, a redo request, or a challenge to a previous answer apart from small talk.\n`;
+// ── Self-correction (ADR 0034) ───────────────────────────────────────────────
+export const DEFAULT_MODEL_ERROR_RETRIES = 2;
+export const DEFAULT_TOOL_ERROR_RETRIES = 3;
+/**
+ * ADK's reflect-and-retry plugins, on by default. The model plugin turns a
+ * reply ADK marks malformed (MALFORMED_FUNCTION_CALL) into a retry with
+ * guidance instead of a failed turn; the tool plugin answers a tool that
+ * threw with structured guidance and caps its retries. Every retry is a
+ * model call under the turn's max_steps. Fresh instances per run: their
+ * counters are per invocation, but a run is the unit a surface reasons in.
+ */
+export function retryPlugins(retries) {
+    const model = retries?.model_errors ?? DEFAULT_MODEL_ERROR_RETRIES;
+    const tool = retries?.tool_errors ?? DEFAULT_TOOL_ERROR_RETRIES;
+    const plugins = [];
+    if (model > 0)
+        plugins.push(new ReflectAndRetryModelPlugin({ maxRetries: model }));
+    if (tool > 0)
+        plugins.push(new ReflectAndRetryToolPlugin({ maxRetries: tool, throwExceptionIfRetryExceeded: false }));
+    return plugins;
+}
 // ── Draining one agent's stream ──────────────────────────────────────────────
 function formatToolArgs(args) {
     if (!args || Object.keys(args).length === 0)
@@ -75,10 +101,13 @@ export async function drainAgentStream(stream, opts = {}) {
         thoughts: '',
         tokens: { input: 0, output: 0, thinking: 0 },
         eventCount: 0,
+        inputRequests: [],
+        nodeErrors: [],
     };
     const grounding = newGroundingState();
     let groundingAnnounced = false;
     let streamed = false;
+    let lastNode = '';
     for await (const event of stream) {
         const e = event;
         d.eventCount++;
@@ -95,8 +124,24 @@ export async function drainAgentStream(stream, opts = {}) {
                 ev.onProgress?.('Invoking tool: web_search');
             groundingAnnounced = true;
         }
+        // A workflow event names its node; say when the graph moves on. The
+        // root (a path with no dot) and the hidden route steps are not nodes a
+        // person declared, so they stay out of the progress.
+        const nodePath = e.nodeInfo?.path;
+        if (nodePath && nodePath.includes('.') && e.author && !String(e.author).endsWith(ROUTE_STEP_SUFFIX) && e.author !== lastNode && e.partial !== true) {
+            lastNode = e.author;
+            ev.log?.(`⇢ Node: ${e.author}`);
+            if (opts.publishToolStatus)
+                ev.onProgress?.(`Running node: ${e.author}`);
+        }
         if ((e.errorCode || e.errorMessage) && e.errorCode !== 'STOP') {
-            d.error = { code: String(e.errorCode ?? 'ERROR'), message: String(e.errorMessage ?? '') };
+            const error = { code: String(e.errorCode ?? 'ERROR'), message: String(e.errorMessage ?? '') };
+            if (opts.errorPolicy === 'collect') {
+                d.nodeErrors.push({ node: String(e.author ?? ''), ...error });
+                ev.warn?.(`Node ${e.author ?? '?'} reported [${error.code}]: ${error.message}`);
+                continue;
+            }
+            d.error = error;
             ev.warn?.(`Error [${d.error.code}]: ${d.error.message}`);
             break;
         }
@@ -123,6 +168,13 @@ export async function drainAgentStream(stream, opts = {}) {
                     ev.onProgress?.(`Delegating to subagent: ${target}`);
                 continue;
             }
+            const inputRequest = inputRequestFrom(e.author, call) ?? questionFrom(e.author, call);
+            if (inputRequest) {
+                // An ask_user node: the workflow waits for the person (lib/workflow.ts).
+                d.inputRequests.push(inputRequest);
+                ev.log?.(`⏸ ${describeInput(inputRequest)}`);
+                continue;
+            }
             if (!name)
                 continue;
             d.invokedToolNames.add(name);
@@ -214,7 +266,7 @@ export async function runSyndicateTurn(opts) {
     if (!opts.compile?.resolveModel)
         registerAvailableProviders();
     const control = createTurnControl({
-        maxLlmCalls: opts.maxLlmCalls ?? config.max_steps,
+        maxLlmCalls: opts.maxLlmCalls ?? config.max_steps ?? DEFAULT_MAX_STEPS,
         deadlineMs: opts.deadlineMs,
         signal: opts.signal,
     });
@@ -234,7 +286,7 @@ async function runTurnInner(opts, control) {
     const transform = opts.transformAgent ?? ((a) => a);
     const subagentNames = new Set((config.subagents ?? []).map((s) => s.name));
     const trace = opts.trace === false ? undefined : opts.trace ?? {};
-    const parts = opts.parts.map((p) => (typeof p === 'string' ? { text: p } : p));
+    let parts = opts.parts.map((p) => (typeof p === 'string' ? { text: p } : p));
     const messageText = parts.map((p) => (typeof p.text === 'string' ? p.text : '')).join('\n');
     const result = {
         status: 'completed',
@@ -286,12 +338,39 @@ async function runTurnInner(opts, control) {
         // The log names the call, not its arguments: they are user content.
         ev.log?.(`✓ Approval ${decision.approved ? 'granted' : 'refused'}: ${resuming.agent} → ${resuming.tool}`);
     }
+    // ── Questions (lib/runtime/questions.ts) ───────────────────────────────────
+    // While an agent's `ask_user` call is open, a plain-text message is its
+    // answer: it becomes that call's response, and the agent that asked
+    // resumes its own tool loop. A workflow's pauses are ADK's own business.
+    let answering;
+    if (!decision && !isWorkflowSyndicate(config)) {
+        const question = pendingQuestion(existing?.events ?? []);
+        const plainText = parts.length > 0 && parts.every((p) => typeof p.text === 'string');
+        if (question && plainText) {
+            answering = { agent: question.node, id: question.id };
+            parts = [questionAnswerPart(question.id, messageText)];
+            ev.log?.(`✓ Answer to ${question.node}'s question`);
+        }
+    }
+    /** The agent a dispatch turn must resume, and the call its interrupted turn holds. */
+    const resumeTarget = resuming ? { agent: resuming.agent, id: resuming.id, why: 'resuming an approval' } : answering ? { ...answering, why: 'answering its question' } : undefined;
     /** After the answering run: is a gated call now waiting? */
     const awaitingApproval = async (agentName) => {
         const after = await sessionService.getSession({ appName, userId, sessionId });
         const pending = pendingApproval(after?.events ?? []);
         return pending && pending.agent === agentName ? pending : undefined;
     };
+    /** After the answering run: did the agent ask the person something? */
+    const asked = (run) => {
+        const input = run.inputRequests[run.inputRequests.length - 1];
+        if (!input)
+            return undefined;
+        result.status = 'input-required';
+        result.input = input;
+        result.text = input.message;
+        ev.log?.(`⏸ Input needed: ${describeInput(input)}`);
+        return finish();
+    };
     const pause = (pending) => {
         result.status = 'input-required';
         result.approval = pending;
@@ -305,6 +384,7 @@ async function runTurnInner(opts, control) {
             agent: params.agent,
             appName,
             sessionService: params.sessions,
+            plugins: retryPlugins(config.retries),
             ...(opts.memoryService ? { memoryService: opts.memoryService } : {}),
         });
         let stream = runner.runAsync({
@@ -329,6 +409,7 @@ async function runTurnInner(opts, control) {
                 configHash: trace.configHash,
                 attributes: trace.attributes,
                 onSpanStart: trace.onSpanStart,
+                traceparent: trace.traceparent,
                 onEnd: () => ({
                     'syndicate.relay_fallback': params.stage === 'delegate' && !!params.relayFallback?.(),
                     ...(control.stopReason ? { 'syndicate.stop_reason': control.stopReason } : {}),
@@ -342,6 +423,7 @@ async function runTurnInner(opts, control) {
                 publishToolStatus: params.publishToolStatus,
                 subagentNames,
                 streamText: params.stage !== 'classify' && !guarded,
+                errorPolicy: params.errorPolicy,
             });
         }
         catch (err) {
@@ -359,16 +441,16 @@ async function runTurnInner(opts, control) {
         // Deterministic overrides first: when the message itself decides the
         // route there is nothing to classify, and the classifier call is skipped.
         const warnings = [];
-        let resolution = resuming ? null : matchRouteOverride(messageText, config, warnings);
+        let resolution = resumeTarget ? null : matchRouteOverride(messageText, config, warnings);
         let decidedBy = 'override';
         for (const w of warnings)
             ev.warn?.(w);
-        if (resuming) {
-            if (!subagentNames.has(resuming.agent)) {
-                throw new Error(`Approval ${resuming.id} was raised by '${resuming.agent}', which is not a route of this syndicate.`);
+        if (resumeTarget) {
+            if (!subagentNames.has(resumeTarget.agent)) {
+                throw new Error(`Call ${resumeTarget.id} was raised by '${resumeTarget.agent}', which is not a route of this syndicate.`);
             }
-            resolution = { route: resuming.agent, reason: 'resuming an approval', fellBack: false, fallbackReason: '', viaOverride: false };
-            decidedBy = 'approval';
+            resolution = { route: resumeTarget.agent, reason: resumeTarget.why, fellBack: false, fallbackReason: '', viaOverride: false };
+            decidedBy = resuming ? 'approval' : 'answer';
         }
         else if (resolution) {
             ev.log?.(`⇄ Route pinned by override: ${resolution.route}`);
@@ -437,9 +519,13 @@ async function runTurnInner(opts, control) {
                 agent: routeAgent,
                 sid: sessionId,
                 userParts: parts,
-                // Resuming an approval: the interrupted turn is replayed raw, so ADK
-                // finds the call the approval answers (ADR 0028).
-                sessions: new ProjectedSessionService(sessionService, routeCfg.name, resuming ? { rawFrom: (events) => interruptedTurnStart(events, resuming.id) } : {}),
+                // Resuming an approval or answering a question: the interrupted turn
+                // is replayed raw, so ADK finds the call the message answers.
+                sessions: new ProjectedSessionService(sessionService, routeCfg.name, resuming
+                    ? { rawFrom: (events) => interruptedTurnStart(events, resuming.id) }
+                    : answering
+                        ? { rawFrom: (events) => turnStartOfCall(events, answering.id) }
+                        : {}),
                 stage: 'dispatch',
                 route: resolution,
                 publishToolStatus: true,
@@ -452,11 +538,14 @@ async function runTurnInner(opts, control) {
             result.error = answer.error;
             return finish();
         }
-        if (!routeCfg.a2a_agent_url && routeCfg.require_approval?.length) {
+        if (!routeCfg.a2a_agent_url && agentGates(routeCfg)) {
             const pending = await awaitingApproval(routeCfg.name);
             if (pending)
                 return pause(pending);
         }
+        const askedRoute = asked(answer);
+        if (askedRoute)
+            return askedRoute;
         result.text = answer.text;
         if (!result.text) {
             // Naming the route turns a blank reply into a lead (the XScout outage
@@ -466,6 +555,60 @@ async function runTurnInner(opts, control) {
             result.text = `${resolution.route} returned no output — the server logs carry the upstream error.`;
         }
     }
+    else if (isWorkflowSyndicate(config)) {
+        // ══ WORKFLOW ═════════════════════════════════════════════════════════
+        // The syndicate is a graph (lib/workflow.ts): every agent a node, run
+        // by ADK's Workflow in the shared session. A node agent sees only its
+        // input unless its YAML says otherwise, so no projection is needed. An
+        // `ask_user` node ends the turn input-required; the next message
+        // resumes the graph where it waited.
+        const compiled = await compileWorkflow(config, compileOpts, transform);
+        try {
+            answer = await runAgent({
+                agent: compiled.workflow,
+                sid: sessionId,
+                userParts: parts,
+                sessions: sessionService,
+                stage: 'workflow',
+                publishToolStatus: true,
+                errorPolicy: 'collect',
+            });
+        }
+        catch (err) {
+            // A node that gave up (its retries spent, a timeout, a schema it could
+            // not satisfy) ends the run by throwing; the last reported error names it.
+            const last = control.stopReason ? undefined : err;
+            if (!last)
+                throw err;
+            result.status = 'failed';
+            result.failedStage = 'workflow';
+            result.error = { code: 'NODE_FAILED', message: last.message };
+            return finish();
+        }
+        result.answer = answer;
+        if (answer.error || control.stopReason) {
+            result.status = 'failed';
+            result.failedStage = 'workflow';
+            result.error = answer.error;
+            return finish();
+        }
+        if (answer.inputRequests.length) {
+            const input = answer.inputRequests[answer.inputRequests.length - 1];
+            result.status = 'input-required';
+            result.input = input;
+            result.text = input.message;
+            ev.log?.(`⏸ Input needed: ${describeInput(input)}`);
+            return finish();
+        }
+        result.text = answer.text;
+        if (!result.text) {
+            const failed = answer.nodeErrors[answer.nodeErrors.length - 1];
+            ev.warn?.(`The workflow produced no output${failed ? ` (last node error: ${failed.node} [${failed.code}] ${failed.message})` : ''}.`);
+            result.text = failed
+                ? `The workflow ended without an answer — ${failed.node} failed [${failed.code}]: ${failed.message}`
+                : 'The workflow ended without an answer.';
+        }
+    }
     else {
         // ══ DELEGATE ═════════════════════════════════════════════════════════
         // Subagents are AgentTools; the orchestrator relays the answer it got.
@@ -488,11 +631,14 @@ async function runTurnInner(opts, control) {
             result.error = answer.error;
             return finish();
         }
-        if (config.orchestrator.require_approval?.length) {
+        if (agentGates(config.orchestrator)) {
             const pending = await awaitingApproval(config.orchestrator.name);
             if (pending)
                 return pause(pending);
         }
+        const askedOrchestrator = asked(answer);
+        if (askedOrchestrator)
+            return askedOrchestrator;
         result.text = answer.text;
         // Failed-relay fallback: an orchestrator can botch the hop that relays a
         // specialist's answer — STOP with no text, or the bare tool NAME as its
@@ -563,6 +709,8 @@ async function runRemoteRoute(name, url, messageText, sessionId, control, ev) {
 }
 function emptyRun(error) {
     return {
+        inputRequests: [],
+        nodeErrors: [],
         text: '',
         lastToolResultText: '',
         toolResultTexts: [],

package/dist/lib/storage/postgres/index.d.ts

@@ -17,6 +17,8 @@ import type { Embedder, MemoryExtractor } from '../../memory/providers.ts';
 import type { EraseCounts, EraseOptions } from '../../memory/erase.ts';
 import { PostgresSessionService } from './sessionService.ts';
 import { PostgresTaskStore } from './taskStore.ts';
+import type { AuditSink } from '../../observability/audit.ts';
+import type { RlsHardeningStatus } from '../rlsStatus.ts';
 import type { TaskBackend } from '../../tools/taskTools.ts';
 import type { TurnLock } from '../../a2a/turnLock.ts';
 import type { PostgresTaskStoreOptions } from './taskStore.ts';
@@ -70,6 +72,13 @@ export interface PostgresStorage {
     erase: (scopeKey: string, options?: EraseOptions) => Promise<EraseCounts>;
     /** The highest migration recorded in melchizedek_schema_version; null if none. */
     schemaVersion: () => Promise<number | null>;
+    /**
+     * Whether db/hardening.sql is in force where an API could expose the
+     * tables (lib/storage/rlsStatus.ts). Never throws.
+     */
+    rlsHardening: () => Promise<RlsHardeningStatus>;
+    /** Appends to melchizedek_audit (migration 0012, ADR 0042). */
+    audit: AuditSink;
     /**
      * One turn at a time per conversation, across every instance on this
      * database: a session-level advisory lock on a dedicated connection, so a

package/dist/lib/storage/postgres/index.js

@@ -19,6 +19,8 @@ import { PostgresSessionService } from './sessionService.js';
 import { PostgresTaskStore, reapExpiredTasks, renewTaskLeases } from './taskStore.js';
 import { postgresTaskBackend } from './taskQueue.js';
 import { searchPathOption } from '../schema.js';
+import { POSTGRES_RLS_QUERY, evaluatePostgresRls } from '../rlsStatus.js';
+import { postgresAuditSink } from '../../observability/audit.js';
 import { createHash, randomUUID } from 'node:crypto';
 import { hostname } from 'node:os';
 export { PostgresSessionService } from './sessionService.js';
@@ -121,6 +123,17 @@ export function postgresStorage(options) {
                 throw err;
             }
         },
+        audit: postgresAuditSink(pool),
+        async rlsHardening() {
+            try {
+                const r = await pool.query(POSTGRES_RLS_QUERY);
+                const row = r.rows[0];
+                return evaluatePostgresRls({ apiRoles: row.api_roles, schema: row.schema, rows: row.rows });
+            }
+            catch (err) {
+                return { applied: false, detail: `hardening check failed: ${err instanceof Error ? err.message : String(err)}` };
+            }
+        },
         async erase(scopeKey, eraseOptions = {}) {
             if (!scopeKey?.trim())
                 throw new Error('erase: a scope key is required');