melchizedek-agents 0.18.0 → 0.20.0

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

@@ -1,6 +1,6 @@
 /**
- * lib/storage/postgres/sessionService.ts — ADK sessions on a direct Postgres
- * connection (ADR 0021).
+ * lib/storage/postgres/sessionService.ts — sessions on a direct Postgres
+ * connection (ADR 0021), for either runtime (ADR 0052, ADR 0058).
  *
  * WHY it differs from the Supabase session service:
  *   That one re-uploads a conversation's WHOLE events array on every event.
@@ -15,23 +15,44 @@
  *   event; appending each event once removes that cost, and a DELEGATE
  *   conversation that is replayed to the model gets back exactly what it sent.
  *
+ * TWO FACES, ONE STORE:
+ *   The class is the engine's SessionService (create, get, list, delete,
+ *   append) and ADK's BaseSessionService (createSession, getSession, …), so
+ *   the ADK runtime and the native one read and write the same rows. The ADK
+ *   methods call the engine's, except appendEvent, which applies the event
+ *   to the runner's session through ADK's base service (its write-order
+ *   check included), where append uses applyEvent. Both record it the same
+ *   way. The rules are lib/runtime/sessions.ts's: a create of an existing
+ *   id keeps the conversation, `afterTimestamp` is strict and filters
+ *   before `numRecentEvents` counts, an event whose id the caller's session
+ *   already holds replaces that row in place (as applyEvent replaces it in
+ *   the session), and lastUpdateTime is the appended event's timestamp.
+ *
  * Rows share adk_sessions with the Supabase service (same id scheme:
  * '<appName>:<userId>:<sessionId>'), so erase and the session prune cover
  * both. Tables: db/migrations/0001_base.sql and 0003_postgres_storage.sql.
  */
 import { randomUUID } from 'node:crypto';
-import { BaseSessionService, createSession } from '@google/adk';
+import { BaseSessionService } from '../../adkPeer.js';
+import { applyEvent, listPage, listWindow, withoutTempKeys } from '../../runtime/sessions.js';
 function dbId(appName, userId, sessionId) {
     return `${appName}:${userId}:${sessionId}`;
 }
-/** The persisted part of a state delta: ADK never stores `temp:` keys. */
+/** The persisted part of a state delta: `temp:` keys are never stored. */
 export function persistedDelta(delta) {
-    const out = {};
-    for (const [k, v] of Object.entries(delta ?? {})) {
-        if (!k.startsWith('temp:'))
-            out[k] = v;
-    }
-    return out;
+    return withoutTempKeys(delta ?? {});
+}
+/** Whether the session already holds an event with this one's id: the append replaces it. */
+function holds(session, event) {
+    return Boolean(event.id) && session.events.some((e) => e.id === event.id);
+}
+/** An event's timestamp, or the clock for an event without one. */
+function eventTime(ms) {
+    return typeof ms === 'number' && Number.isFinite(ms) ? ms : Date.now();
+}
+/** last_update_time is BIGINT milliseconds. */
+function rowTime(ms) {
+    return Math.floor(eventTime(ms));
 }
 /**
  * A conversation written by the Supabase session service keeps its events as
@@ -52,6 +73,18 @@ const IMPORT_LEGACY_EVENTS = `
          jsonb_array_elements(coalesce(s.events, '[]'::jsonb)) WITH ORDINALITY AS e(elem, ord)
    WHERE s.id = $1
      AND NOT EXISTS (SELECT 1 FROM adk_session_events WHERE session_id = $1)`;
+/** The conversation's next event row. Runs under the session's row lock. */
+const INSERT_EVENT = `
+  INSERT INTO adk_session_events (session_id, seq, ts, event)
+  VALUES ($1, (SELECT coalesce(max(seq), 0) + 1 FROM adk_session_events WHERE session_id = $1), $2, $3::jsonb)`;
+/**
+ * An event whose id the session already holds replaces that row in place,
+ * as applyEvent replaces it in the session. It reads every event of the
+ * conversation, so it runs only when the caller's session held the id.
+ */
+const REPLACE_EVENT = `
+  UPDATE adk_session_events SET ts = $2, event = $3::jsonb
+   WHERE session_id = $1 AND event->>'id' = $4`;
 export class PostgresSessionService extends BaseSessionService {
     ttlMs;
     pool;
@@ -63,28 +96,23 @@ export class PostgresSessionService extends BaseSessionService {
     expireAt() {
         return new Date(Date.now() + this.ttlMs).toISOString();
     }
-    async createSession(request) {
+    // ── The engine's interface (lib/runtime/sessions.ts) ─────────────────────
+    async create(request) {
         const sessionId = request.sessionId || randomUUID();
         const id = dbId(request.appName, request.userId, sessionId);
+        const state = withoutTempKeys(request.state ?? {});
         const now = Date.now();
-        // A concurrent create for the same id keeps the row that is already
-        // there, events and all, instead of resetting it.
+        // A create for an id that exists, concurrent or not, keeps the row
+        // that is already there, events and all, instead of resetting it.
         const inserted = await this.pool.query(`INSERT INTO adk_sessions (id, app_name, user_id, state, events, last_update_time, expire_at)
        VALUES ($1, $2, $3, $4::jsonb, '[]'::jsonb, $5, $6)
-       ON CONFLICT (id) DO NOTHING`, [id, request.appName, request.userId, JSON.stringify(request.state ?? {}), now, this.expireAt()]);
+       ON CONFLICT (id) DO NOTHING`, [id, request.appName, request.userId, JSON.stringify(state), now, this.expireAt()]);
         if (inserted.rowCount === 0) {
-            const existing = await this.getSession({ appName: request.appName, userId: request.userId, sessionId });
+            const existing = await this.get({ appName: request.appName, userId: request.userId, sessionId });
             if (existing)
                 return existing;
         }
-        return createSession({
-            id: sessionId,
-            appName: request.appName,
-            userId: request.userId,
-            state: request.state ?? {},
-            events: [],
-            lastUpdateTime: now,
-        });
+        return { id: sessionId, appName: request.appName, userId: request.userId, state, events: [], lastUpdateTime: now };
     }
     /** Copy a legacy JSON history into rows, once, under the conversation's row lock. */
     async importLegacyEvents(id) {
@@ -103,8 +131,9 @@ export class PostgresSessionService extends BaseSessionService {
             client.release();
         }
     }
-    async getSession(request) {
-        const id = dbId(request.appName, request.userId, request.sessionId);
+    /** selectEvents' rules, pushed down: strictly after the timestamp, then the newest N, oldest first. */
+    async get(key, options = {}) {
+        const id = dbId(key.appName, key.userId, key.sessionId);
         const row = await this.pool.query(`SELECT app_name, user_id, state, last_update_time,
               (jsonb_array_length(coalesce(events, '[]'::jsonb)) > 0
                AND NOT EXISTS (SELECT 1 FROM adk_session_events WHERE session_id = $1)) AS legacy
@@ -113,20 +142,20 @@ export class PostgresSessionService extends BaseSessionService {
             return undefined;
         if (row.rows[0].legacy)
             await this.importLegacyEvents(id);
-        const cfg = request.config ?? {};
         const params = [id];
         let where = 'session_id = $1';
-        if (cfg.afterTimestamp) {
-            params.push(cfg.afterTimestamp);
+        if (options.afterTimestamp) {
+            params.push(options.afterTimestamp);
             where += ` AND ts > $${params.length}`;
         }
-        // The newest N, returned oldest first.
-        const events = cfg.numRecentEvents
-            ? await this.pool.query(`SELECT event FROM (SELECT event, seq FROM adk_session_events WHERE ${where} ORDER BY seq DESC LIMIT ${Math.max(0, Math.floor(cfg.numRecentEvents))}) recent ORDER BY seq ASC`, params)
+        const n = options.numRecentEvents;
+        const recent = typeof n === 'number' && Number.isFinite(n) ? Math.floor(n) : 0;
+        const events = recent > 0
+            ? await this.pool.query(`SELECT event FROM (SELECT event, seq FROM adk_session_events WHERE ${where} ORDER BY seq DESC LIMIT $${params.length + 1}) recent ORDER BY seq ASC`, [...params, recent])
             : await this.pool.query(`SELECT event FROM adk_session_events WHERE ${where} ORDER BY seq ASC`, params);
         const r = row.rows[0];
         return {
-            id: request.sessionId,
+            id: key.sessionId,
             appName: r.app_name,
             userId: r.user_id,
             state: r.state ?? {},
@@ -135,15 +164,13 @@ export class PostgresSessionService extends BaseSessionService {
         };
     }
     /**
-     * Same paging contract as the Supabase service: `limit` with `page`
-     * (1-based, wins) or `offset` (0-based), optional order by last update,
-     * and the real total alongside the page. Events are omitted.
+     * listWindow and listPage's paging, with the real total beside the page.
+     * Every user's sessions when `userId` is absent. By last update, ties by
+     * id, when an order is asked for; in the order the rows were created
+     * otherwise. Events are left out.
      */
-    async listSessions(request) {
-        const { limit, order } = request;
-        const offset = limit !== undefined && request.page !== undefined
-            ? (Math.max(1, request.page) - 1) * limit
-            : (request.offset ?? 0);
+    async list(request) {
+        const { offset, limit } = listWindow(request);
         const params = [request.appName];
         let where = 'app_name = $1';
         if (request.userId !== undefined) {
@@ -151,9 +178,18 @@ export class PostgresSessionService extends BaseSessionService {
             where += ` AND user_id = $${params.length}`;
         }
         const total = await this.pool.query(`SELECT count(*)::int AS n FROM adk_sessions WHERE ${where}`, params);
-        const orderBy = order ? `ORDER BY last_update_time ${order === 'asc' ? 'ASC' : 'DESC'}, id` : 'ORDER BY id';
-        const window = `${limit !== undefined ? `LIMIT ${Math.max(0, Math.floor(limit))}` : ''} OFFSET ${Math.max(0, Math.floor(offset))}`;
-        const rows = await this.pool.query(`SELECT id, app_name, user_id, state, last_update_time FROM adk_sessions WHERE ${where} ${orderBy} ${window}`, params);
+        const orderBy = request.order
+            ? `ORDER BY last_update_time ${request.order === 'asc' ? 'ASC' : 'DESC'}, id`
+            : 'ORDER BY created_at, id';
+        const paged = [...params];
+        let window = '';
+        if (limit !== undefined) {
+            paged.push(limit);
+            window += `LIMIT $${paged.length} `;
+        }
+        paged.push(offset);
+        window += `OFFSET $${paged.length}`;
+        const rows = await this.pool.query(`SELECT id, app_name, user_id, state, last_update_time FROM adk_sessions WHERE ${where} ${orderBy} ${window}`, paged);
         const sessions = rows.rows.map((row) => ({
             id: String(row.id).slice(String(row.app_name).length + String(row.user_id).length + 2),
             appName: row.app_name,
@@ -162,33 +198,32 @@ export class PostgresSessionService extends BaseSessionService {
             events: [],
             lastUpdateTime: Number(row.last_update_time ?? 0),
         }));
-        const totalItems = total.rows[0].n;
-        return {
-            sessions,
-            page: limit ? Math.floor(offset / limit) + 1 : 1,
-            limit: limit ?? totalItems,
-            totalItems,
-            totalPages: limit ? Math.max(1, Math.ceil(totalItems / limit)) : 1,
-        };
+        return { sessions, ...listPage(total.rows[0].n, request) };
     }
-    async deleteSession(request) {
+    async delete(key) {
         // Events go with it (ON DELETE CASCADE).
-        await this.pool.query('DELETE FROM adk_sessions WHERE id = $1', [
-            dbId(request.appName, request.userId, request.sessionId),
-        ]);
+        await this.pool.query('DELETE FROM adk_sessions WHERE id = $1', [dbId(key.appName, key.userId, key.sessionId)]);
     }
-    async appendEvent(request) {
-        const { session, event } = request;
+    async append(session, event) {
         // Streaming fragments are appended whole once complete.
         if (event.partial)
             return event;
-        // ADK's own merge: applies the state delta to the live session, strips
-        // temp: keys, pushes the event. Must run (see the Supabase service).
-        await super.appendEvent({ session, event });
-        session.lastUpdateTime = Date.now();
+        const replacing = holds(session, event);
+        const stored = applyEvent(session, event);
+        await this.record(session, stored, replacing);
+        return stored;
+    }
+    /**
+     * One event into the store, in one transaction: its row, the state delta
+     * merged into the stored state, and the times. Two copies of a session
+     * appending in turn both land, since each writes only its own event.
+     */
+    async record(session, event, replacing) {
         const id = dbId(session.appName, session.userId, session.id);
         const delta = persistedDelta(event.actions?.stateDelta);
-        const stored = JSON.parse(JSON.stringify(event));
+        const ts = typeof event.timestamp === 'number' ? event.timestamp : null;
+        const updated = rowTime(event.timestamp);
+        const json = JSON.stringify(event);
         const client = await this.pool.connect();
         try {
             await client.query('BEGIN');
@@ -198,19 +233,20 @@ export class PostgresSessionService extends BaseSessionService {
             if (locked.rowCount === 0) {
                 await client.query(`INSERT INTO adk_sessions (id, app_name, user_id, state, events, last_update_time, expire_at)
            VALUES ($1, $2, $3, '{}'::jsonb, '[]'::jsonb, $4, $5)
-           ON CONFLICT (id) DO NOTHING`, [id, session.appName, session.userId, session.lastUpdateTime, this.expireAt()]);
+           ON CONFLICT (id) DO NOTHING`, [id, session.appName, session.userId, updated, this.expireAt()]);
                 await client.query('SELECT 1 FROM adk_sessions WHERE id = $1 FOR UPDATE', [id]);
             }
             // A conversation the Supabase service wrote: its history first.
             await client.query(IMPORT_LEGACY_EVENTS, [id]);
-            await client.query(`INSERT INTO adk_session_events (session_id, seq, ts, event)
-         VALUES ($1, (SELECT coalesce(max(seq), 0) + 1 FROM adk_session_events WHERE session_id = $1), $2, $3::jsonb)`, [id, typeof event.timestamp === 'number' ? event.timestamp : null, JSON.stringify(stored)]);
+            const replaced = replacing ? await client.query(REPLACE_EVENT, [id, ts, json, event.id]) : undefined;
+            if (!replaced?.rowCount)
+                await client.query(INSERT_EVENT, [id, ts, json]);
             await client.query(`UPDATE adk_sessions
             SET state = coalesce(state, '{}'::jsonb) || $2::jsonb,
                 last_update_time = $3,
                 expire_at = $4,
                 updated_at = now()
-          WHERE id = $1`, [id, JSON.stringify(delta), session.lastUpdateTime, this.expireAt()]);
+          WHERE id = $1`, [id, JSON.stringify(delta), updated, this.expireAt()]);
             await client.query('COMMIT');
         }
         catch (err) {
@@ -220,6 +256,32 @@ export class PostgresSessionService extends BaseSessionService {
         finally {
             client.release();
         }
+    }
+    // ── ADK's BaseSessionService, for the ADK runtime ─────────────────────────
+    async createSession(request) {
+        return (await this.create(request));
+    }
+    async getSession(request) {
+        const key = { appName: request.appName, userId: request.userId, sessionId: request.sessionId };
+        return (await this.get(key, request.config));
+    }
+    async listSessions(request) {
+        return (await this.list(request));
+    }
+    async deleteSession(request) {
+        await this.delete(request);
+    }
+    async appendEvent(request) {
+        const { session, event } = request;
+        if (event.partial)
+            return event;
+        // ADK's own merge: applies the state delta to the live session, strips
+        // temp: keys, replaces or pushes the event. It must run: a bare push
+        // drops every state write (see the Supabase service).
+        const replacing = holds(session, event);
+        await super.appendEvent({ session, event });
+        session.lastUpdateTime = eventTime(event.timestamp);
+        await this.record(session, event, replacing);
         return event;
     }
 }

package/dist/lib/syndicateSchema.d.ts

@@ -24,6 +24,7 @@
 import { z } from 'zod';
 import type { SyndicateYamlConfig } from './loadSyndicate.ts';
 export declare const MEMORY_SYSTEMS: readonly ['internal-only', 'session-only', 'long-term'];
+export declare const REASONING_LEVELS: readonly ['none', 'low', 'medium', 'high'];
 export declare const SKILL_SCRIPT_MODES: readonly ['none', 'local'];
 export declare const agentSchema: z.ZodObject<{
     name: z.ZodString;
@@ -60,7 +61,16 @@ export declare const agentSchema: z.ZodObject<{
             thinkingBudget: z.ZodOptional<z.ZodNumber>;
             includeThoughts: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$loose>>;
+        reasoningEffort: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>>;
+    reasoning: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        high: "high";
+        low: "low";
+        medium: "medium";
+        none: "none";
+    }>, z.ZodObject<{
+        budget_tokens: z.ZodNumber;
+    }, z.core.$strict>]>>;
     outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     mcp_server_url: z.ZodOptional<z.ZodString>;
     mcp_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -71,6 +81,8 @@ export declare const agentSchema: z.ZodObject<{
             none: "none";
         }>>;
         tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        env: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        secret_env: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
     openapi: z.ZodOptional<z.ZodArray<z.ZodObject<{
         spec: z.ZodString;
@@ -146,7 +158,16 @@ export declare const subagentSchema: z.ZodObject<{
             thinkingBudget: z.ZodOptional<z.ZodNumber>;
             includeThoughts: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$loose>>;
+        reasoningEffort: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>>;
+    reasoning: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        high: "high";
+        low: "low";
+        medium: "medium";
+        none: "none";
+    }>, z.ZodObject<{
+        budget_tokens: z.ZodNumber;
+    }, z.core.$strict>]>>;
     outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     mcp_server_url: z.ZodOptional<z.ZodString>;
     mcp_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -157,6 +178,8 @@ export declare const subagentSchema: z.ZodObject<{
             none: "none";
         }>>;
         tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        env: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        secret_env: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
     openapi: z.ZodOptional<z.ZodArray<z.ZodObject<{
         spec: z.ZodString;
@@ -236,7 +259,16 @@ export declare const syndicateSchema: z.ZodObject<{
                 thinkingBudget: z.ZodOptional<z.ZodNumber>;
                 includeThoughts: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$loose>>;
+            reasoningEffort: z.ZodOptional<z.ZodString>;
         }, z.core.$loose>>;
+        reasoning: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            high: "high";
+            low: "low";
+            medium: "medium";
+            none: "none";
+        }>, z.ZodObject<{
+            budget_tokens: z.ZodNumber;
+        }, z.core.$strict>]>>;
         outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         mcp_server_url: z.ZodOptional<z.ZodString>;
         mcp_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -247,6 +279,8 @@ export declare const syndicateSchema: z.ZodObject<{
                 none: "none";
             }>>;
             tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            env: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            secret_env: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
         openapi: z.ZodOptional<z.ZodArray<z.ZodObject<{
             spec: z.ZodString;
@@ -316,7 +350,16 @@ export declare const syndicateSchema: z.ZodObject<{
                 thinkingBudget: z.ZodOptional<z.ZodNumber>;
                 includeThoughts: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$loose>>;
+            reasoningEffort: z.ZodOptional<z.ZodString>;
         }, z.core.$loose>>;
+        reasoning: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            high: "high";
+            low: "low";
+            medium: "medium";
+            none: "none";
+        }>, z.ZodObject<{
+            budget_tokens: z.ZodNumber;
+        }, z.core.$strict>]>>;
         outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         mcp_server_url: z.ZodOptional<z.ZodString>;
         mcp_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -327,6 +370,8 @@ export declare const syndicateSchema: z.ZodObject<{
                 none: "none";
             }>>;
             tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            env: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            secret_env: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
         openapi: z.ZodOptional<z.ZodArray<z.ZodObject<{
             spec: z.ZodString;
@@ -395,6 +440,8 @@ export declare const syndicateSchema: z.ZodObject<{
                 initial_delay: z.ZodOptional<z.ZodNumber>;
                 max_delay: z.ZodOptional<z.ZodNumber>;
                 backoff_factor: z.ZodOptional<z.ZodNumber>;
+                jitter: z.ZodOptional<z.ZodNumber>;
+                exceptions: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strict>>;
             timeout: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>>>;
@@ -423,6 +470,8 @@ export declare const syndicateSchema: z.ZodObject<{
  * snake/camel drift (`output_key` for `outputKey`) count as an exact match.
  */
 export declare function suggest(input: string, candidates: readonly string[]): string | undefined;
+/** The generateContentConfig keys `reasoning` replaces (ADR 0047). */
+export declare const REASONING_OLDER_SPELLING: readonly ['thinkingConfig', 'reasoningEffort'];
 /**
  * Thrown by validateSyndicateConfig. `problems` holds one `<file>: <path> —
  * <what>` line per problem (the message lists them all); `issues` holds the

package/dist/lib/syndicateSchema.js

@@ -23,6 +23,7 @@
  */
 import { z } from 'zod';
 import { DEFAULT_ROUTE_KEY, NODE_KINDS, ROUTE_STEP_SUFFIX, START_NAME, elementNames, nodeKind } from './workflowConfig.js';
+import { isSecretShapedEnvName } from './tools/skills/env.js';
 // ── Leaf rules ───────────────────────────────────────────────────────────────
 /**
  * ADK's own rule (validateAgentName in @google/adk base_agent): checked here
@@ -41,7 +42,25 @@ const thinkingConfig = z
     thinkingBudget: z.number().int().optional().describe('Reasoning token budget. 0 = off, -1 = dynamic.'),
     includeThoughts: z.boolean().optional().describe('Stream the thinking trace in the response.'),
 })
-    .describe('Gemini thinking controls (generateContentConfig.thinkingConfig).');
+    .describe('Older spelling of `reasoning` for Gemini and Claude (thinkingLevel or thinkingBudget). Cannot be combined with `reasoning`.');
+export const REASONING_LEVELS = ['none', 'low', 'medium', 'high'];
+/**
+ * The provider-neutral reasoning key (ADR 0047): a level, or a token budget.
+ * The compiler maps it per provider (lib/compile.ts reasoningConfig).
+ */
+const reasoningSchema = z
+    .union([
+    z.enum(REASONING_LEVELS),
+    z.strictObject({
+        budget_tokens: z.number().int().min(0).describe('Thinking tokens; 0 = none. Effort-only providers take the nearest level at or above it.'),
+    }),
+], {
+    error: (iss) => {
+        const hint = typeof iss.input === 'string' ? suggest(iss.input, REASONING_LEVELS) : undefined;
+        return `must be one of ${REASONING_LEVELS.join(' | ')}, or { budget_tokens: <integer ≥ 0> } (got ${describeValue(iss.input)}${hint ? ` — did you mean "${hint}"?` : ''})`;
+    },
+})
+    .describe('How hard this agent reasons, on any provider: none | low | medium | high, or { budget_tokens: <int> }. Replaces generateContentConfig.thinkingConfig and reasoningEffort (ADR 0047).');
 /**
  * Loose on purpose: provider-specific fields (e.g. `toolConfig`) pass through
  * to the SDK. Only the documented fields are typed, so `temperature: hot`
@@ -63,10 +82,15 @@ const generateContentConfig = z
         .array(z.looseObject({ category: z.string(), threshold: z.string() }))
         .optional(),
     thinkingConfig: thinkingConfig.optional(),
+    reasoningEffort: z
+        .string()
+        .optional()
+        .describe('Older spelling of `reasoning` for the chat-completions and Responses providers. Cannot be combined with `reasoning`.'),
 })
     .describe('Model generation config (@google/genai GenerateContentConfig). Do not set tools here.');
 // ── Skills ───────────────────────────────────────────────────────────────────
 export const SKILL_SCRIPT_MODES = ['none', 'local'];
+const envName = z.string().regex(/^[A-Z_][A-Z0-9_]*$/, 'an environment variable name (A–Z, 0–9, _)');
 /**
  * Agent Skills for one agent (lib/tools/skillToolset.ts): the frontmatter
  * index is injected into the instruction at compile time, a skill is read in
@@ -87,10 +111,27 @@ const skillsSchema = z
         .array(z.string().min(1))
         .optional()
         .describe('Registry tool names a skill may unlock through its `allowed-tools` frontmatter once it is loaded. Omitted, no skill unlocks anything.'),
+    env: z
+        .array(envName)
+        .optional()
+        .describe('Environment variable NAMES (never values) a skill script gets, beyond PATH, HOME, the temp directory, the locale and the OS essentials (ADR 0086). A name that looks like a secret (KEY, TOKEN, SECRET, PASSWORD, AUTH, DATABASE, …) belongs under secret_env.'),
+    secret_env: z
+        .array(envName)
+        .optional()
+        .describe('Secret-shaped environment variable names a skill script gets, listed here so passing a credential to a script is a deliberate, reviewable act (ADR 0086).'),
+})
+    .superRefine((skills, ctx) => {
+    (skills.env ?? []).forEach((name, j) => {
+        if (isSecretShapedEnvName(name)) {
+            ctx.addIssue({ code: 'custom', path: ['env', j], message: `'${name}' looks like it holds a secret; a script gets it only if you list it under skills.secret_env (ADR 0086)` });
+        }
+    });
+    if ((skills.env?.length || skills.secret_env?.length) && skills.scripts !== 'local') {
+        ctx.addIssue({ code: 'custom', path: [skills.env?.length ? 'env' : 'secret_env'], message: 'variables reach skill scripts only, which run only with scripts: "local"' });
+    }
 })
     .describe('Agent Skills (SKILL.md directories) this agent reads the way a coding harness does.');
 // ── OpenAPI ──────────────────────────────────────────────────────────────────
-const envName = z.string().regex(/^[A-Z_][A-Z0-9_]*$/, 'an environment variable name (A–Z, 0–9, _)');
 const openapiEntry = z
     .strictObject({
     spec: z.string().min(1).describe('An OpenAPI 3 spec file (.yaml, .yml, .json), relative to this syndicate file. Files only, never URLs.'),
@@ -151,6 +192,7 @@ const agentFields = {
     disallowTransferToPeers: z.boolean().optional(),
     outputKey: z.string().optional().describe('Session-state key the final reply is saved under.'),
     generateContentConfig: generateContentConfig.optional(),
+    reasoning: reasoningSchema.optional(),
     outputSchema: z
         .record(z.string(), z.unknown())
         .optional()
@@ -254,12 +296,20 @@ const edgeElement = z.union([
         .record(z.string().min(1), edgeTargets)
         .describe('A routing map after a node: `{ <route>: <node or nodes>, default: <node> }`, matched against that node\'s output.'),
 ]);
+/** An error class name, as ADK matches `exceptions` against one: an identifier. */
+const ERROR_NAME = /^[A-Za-z_$][\w$]*$/;
 const retrySchema = z
     .strictObject({
     max_attempts: z.number().int().positive().optional().describe('Attempts including the first; 1 = no retry. ADK default 5.'),
     initial_delay: z.number().nonnegative().optional().describe('Seconds before the first retry.'),
     max_delay: z.number().nonnegative().optional(),
     backoff_factor: z.number().positive().optional(),
+    jitter: z.number().nonnegative().optional().describe('Randomness of the backoff; 0 = none. ADK default 1.'),
+    exceptions: z
+        .array(z.string().regex(ERROR_NAME, 'an error name, such as TypeError or NodeTimeoutError'))
+        .min(1)
+        .optional()
+        .describe('Error names to retry on (the error\'s class or its `name`); every error when absent.'),
 })
     .describe('Retry a node on failure (lib/workflow.ts).');
 const workflowNodeSchema = z
@@ -271,8 +321,8 @@ const workflowNodeSchema = z
     max_parallel: z.number().int().positive().optional().describe('Concurrency of map. Default 8.'),
     tool: z.string().min(1).optional().describe('Run this registry tool with the node input as its arguments.'),
     route_key: z.string().min(1).optional().describe('Property of a JSON output holding the route. Default "route".'),
-    retry: retrySchema.optional(),
-    timeout: z.number().positive().optional().describe('Seconds this node may run before it fails.'),
+    retry: retrySchema.optional().describe('Retry this node on failure. Not on a map node: each item runs under its agent\'s own retry.'),
+    timeout: z.number().positive().optional().describe('Seconds this node may run before it fails. Not on a map node: each item runs under its agent\'s own timeout.'),
 })
     .describe('A declared node (exactly one of ask_user, join, map, tool) or modifiers for an agent node (retry, timeout, route_key).');
 const workflowSchema = z
@@ -479,13 +529,15 @@ function problemsFromIssues(issues, raw) {
             continue;
         }
         if (issue.code === 'too_small' && issue.origin === 'number') {
-            out.push({ path: p, message: `must be a positive integer (got ${describeValue(got)})` });
+            out.push({ path: p, message: `must be ${Number(issue.minimum) === 0 ? '0 or more' : 'a positive integer'} (got ${describeValue(got)})` });
             continue;
         }
         out.push({ path: p, message: issue.message });
     }
     return out;
 }
+/** The generateContentConfig keys `reasoning` replaces (ADR 0047). */
+export const REASONING_OLDER_SPELLING = ['thinkingConfig', 'reasoningEffort'];
 const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 /** Same normalisation lib/dispatch.ts uses to match a route to a subagent. */
 const routeNorm = (s) => s.replace(/[^a-z0-9]/gi, '').toLowerCase();
@@ -588,17 +640,45 @@ function crossFieldProblems(raw) {
     for (const [i, sub] of (Array.isArray(raw.subagents) ? raw.subagents : []).entries())
         if (isObj(sub))
             executionProblems(sub, ['subagents', i], false);
+    // One spelling per agent (ADR 0047): `reasoning` is mapped onto the very
+    // fields the older spelling sets, so the two together would leave which
+    // one wins to merge order.
+    const reasoningProblems = (agent, path) => {
+        if (agent.reasoning === undefined)
+            return;
+        if (typeof agent.yaml_reference === 'string' || typeof agent.a2a_agent_url === 'string') {
+            out.push({ path: [...path, 'reasoning'], message: 'applies to an inline agent; a nested syndicate (yaml_reference) or a remote agent (a2a_agent_url) sets its own' });
+        }
+        if (!isObj(agent.generateContentConfig))
+            return;
+        for (const key of REASONING_OLDER_SPELLING) {
+            if (agent.generateContentConfig[key] === undefined)
+                continue;
+            out.push({
+                path: [...path, 'reasoning'],
+                message: `cannot be combined with generateContentConfig.${key}; reasoning replaces it, so keep one (ADR 0047)`,
+            });
+        }
+    };
+    if (isObj(raw.orchestrator))
+        reasoningProblems(raw.orchestrator, ['orchestrator']);
+    for (const [i, sub] of subs.entries())
+        if (isObj(sub))
+            reasoningProblems(sub, ['subagents', i]);
     if (isObj(raw.orchestrator)) {
         gateProblems(raw.orchestrator, ['orchestrator'], true);
         skillProblems(raw.orchestrator, ['orchestrator'], true);
         questionProblems(raw.orchestrator, ['orchestrator'], true);
     }
     const dispatching = isObj(raw.dispatch);
+    // A workflow's subagents are its nodes, not delegated tools: a gated call pauses its node, and
+    // the walk resumes it (ADR 0098). Skill scripts stay refused inside a workflow (workflowProblems).
+    const pausing = dispatching || isObj(raw.workflow);
     subs.forEach((sub, i) => {
         if (!isObj(sub))
             return;
-        gateProblems(sub, ['subagents', i], dispatching);
-        skillProblems(sub, ['subagents', i], dispatching);
+        gateProblems(sub, ['subagents', i], pausing);
+        skillProblems(sub, ['subagents', i], pausing);
         questionProblems(sub, ['subagents', i], dispatching);
         const hasRef = typeof sub.yaml_reference === 'string';
         const hasRemote = typeof sub.a2a_agent_url === 'string';
@@ -714,6 +794,15 @@ function workflowProblems(raw, subs) {
         if (kind !== 'map' && entry.max_parallel !== undefined) {
             out.push({ path: ['workflow', 'nodes', name, 'max_parallel'], message: 'max_parallel applies to map only' });
         }
+        // A map item runs under its agent's own modifiers, as on ADK (ADR 0089, ADR 0103): the map entry's would be applied by neither runtime.
+        if (kind === 'map') {
+            for (const key of ['retry', 'timeout']) {
+                if (entry[key] === undefined)
+                    continue;
+                const target = entry.map;
+                out.push({ path: ['workflow', 'nodes', name, key], message: `${key} on a map node is not applied: each item runs under its agent's own ${key}; set it on nodes.${target}` });
+            }
+        }
     }
     for (const name of agentNames) {
         if (name.endsWith(ROUTE_STEP_SUFFIX))
@@ -785,8 +874,9 @@ function workflowProblems(raw, subs) {
     for (const [path, agent] of agents) {
         if (!isObj(agent))
             continue;
-        if (Array.isArray(agent.require_approval) && agent.require_approval.length) {
-            out.push({ path: [...path, 'require_approval'], message: 'approval gates are not supported inside a workflow yet' });
+        // A map item cannot pause: the walk resumes a paused agent node, not an item of a map (ADR 0094, ADR 0098).
+        if (typeof agent.name === 'string' && mapped.has(agent.name) && Array.isArray(agent.require_approval) && agent.require_approval.length) {
+            out.push({ path: [...path, 'require_approval'], message: 'approval gates are not supported on an agent a map node runs: a map item cannot pause the walk' });
         }
         if (isObj(agent.skills) && agent.skills.scripts === 'local') {
             out.push({ path: [...path, 'skills', 'scripts'], message: 'skill scripts (an approval pause) are not supported inside a workflow yet' });