melchizedek-agents 0.18.0 → 0.19.0

package/dist/lib/workflow/turn.js

@@ -0,0 +1,216 @@
+/**
+ * lib/workflow/turn.ts — one turn of a workflow syndicate on the native
+ * runtime: the message stored, the graph walked by the engine's scheduler,
+ * and every event the walk stores yielded in the order it was stored, the
+ * node inputs aside, as ADK's Runner yields them (ADR 0095).
+ *
+ * WHY this file exists:
+ *   runSyndicateTurn (lib/runtime/syndicateTurn.ts) runs a workflow on ADK
+ *   by handing ADK's Workflow to its Runner and draining the events the
+ *   Runner yields (drainAgentStream). On the native runtime it hands this
+ *   generator to the same drain, under the same root span, so the progress
+ *   lines, onProgress calls, node errors, the paused input and the ledger
+ *   rows come out of one reader on both runtimes. Everything a node does is
+ *   the WS4 modules': the scheduler (scheduler.ts), agent nodes on the
+ *   native loop (agentNode.ts), tool nodes (toolNode.ts), ask_user nodes and
+ *   the workflow's pause record (pause.ts), and the resume rebuilt from the
+ *   session (resume.ts). This file wires them for one turn, as ADK's Runner
+ *   and Workflow wire theirs:
+ *
+ *   1. THE MESSAGE. Stored as the user's event under a new `e-` invocation
+ *      id, before the walk, as the Runner stores it (runNativeAgent does the
+ *      same for one agent). A turn whose signal aborted first stores nothing.
+ *   2. THE START. workflowResume rebuilds every node's prior runs and the
+ *      answers from the session, as ADK's rehydration does on every message:
+ *      with nothing paused every node runs fresh. The walk's input is the
+ *      message's text, not its content, as ADK hands its root workflow, and
+ *      that text is what the workflow's pause record keeps. A pause only ADK
+ *      can resume (UnsupportedWorkflowResumeError) fails the turn; it never
+ *      walks afresh and asks the person again.
+ *   3. THE WALK. runWorkflowGraph with the runners chained (ask_user, tool,
+ *      then agentNodeRuntime for agent nodes and map items), under the
+ *      turn's signal. Every event a runner stores goes through the agent
+ *      node runtime's one queue, in walk order: node inputs, the agents'
+ *      events, tool and ask_user events, route steps, joins and maps, and
+ *      the node-error event ADK writes for a node that gave up
+ *      (nodeErrorEvent, on the scheduler's `workflow` node_error). A node's
+ *      input turn is stored and not yielded, as ADK's Runner never yields
+ *      it; a node agent's partial (streamed) event is yielded and not
+ *      stored, as the Runner yields it.
+ *   4. THE END. A paused walk stores the workflow's own record
+ *      (workflowPauseEvent) after every node's event. A walk the turn
+ *      stopped (InvocationAbortedError, or any failure once the signal
+ *      fired) ends quietly, as ADK's Runner ends an aborted run: the turn
+ *      runner reads the stop reason from its control. A node that gave up
+ *      rethrows its error once every event is stored and yielded, as ADK's
+ *      Runner throws it.
+ *   5. THE SPANS. `workflow.invoke <name>` around the walk, `node.execute
+ *      <name>` around each node run (the scheduler's traceNode hook), and
+ *      `tool.execute <name>` around a tool node's call
+ *      (lib/runtime/native/telemetry.ts). An agent node's `agent.invoke`
+ *      opens inside its node's span, so each model call is attributed to
+ *      its node's agent in the ledger.
+ *
+ * WHAT IT REFUSES before any model call: refuseUnrunnableNodes throws, for
+ * a tool node, ADK's compile-time refusals (an unregistered tool, a
+ * long-running one). A pause raised inside an agent node is refused by
+ * runAgentNode by name.
+ *
+ * It imports nothing from ADK: the caller passes the tool lookup (the
+ * registry builds ADK's tools) and the store as the engine's interface.
+ * The message, the answers and every stored event are data the walk
+ * carries, never instructions this module acts on.
+ */
+import { randomUUID } from 'node:crypto';
+import { createTurnEvent } from '../runtime/events.js';
+import { traceNodeExecution, traceToolNodeCall, traceWorkflowInvocation } from '../runtime/native/telemetry.js';
+import { agentNodeRuntime } from './agentNode.js';
+import { askUserNodeRunner, workflowPauseEvent } from './pause.js';
+import { workflowResume } from './resume.js';
+import { InvocationAbortedError, nodeErrorEvent, runWorkflowGraph } from './scheduler.js';
+import { resolveToolNode, toolNodeRunner } from './toolNode.js';
+/**
+ * Throws, before any model call, what ADK's compileWorkflow throws for a
+ * tool node: an unregistered tool, or a long-running one (ADR 0091).
+ */
+export function refuseUnrunnableNodes(graph, resolveTool) {
+    for (const node of graph.nodes.values())
+        if (node.kind === 'tool')
+            resolveToolNode(node, { resolveTool });
+}
+const isAborted = (error) => error instanceof InvocationAbortedError || error?.name === 'InvocationAbortedError';
+/**
+ * Runs one turn of the workflow: stores the message, walks the graph (a
+ * resume when the session holds a paused walk), and yields every event the
+ * walk stores, in the order stored, but the node inputs (ADK's Runner
+ * yields none of them). Returns how the walk ended, or
+ * undefined when the signal fired before the message was stored. Throws
+ * the error a node gave up with (after its events), ADK's message for a
+ * reply that answers nothing, and UnsupportedWorkflowResumeError.
+ */
+export async function* runNativeWorkflow(params) {
+    const { graph, sessions, appName, userId, sessionId, signal } = params;
+    const session = await sessions.get({ appName, userId, sessionId });
+    if (!session)
+        throw new Error(`Session not found: ${sessionId} (appName=${appName}, userId=${userId})`);
+    if (signal?.aborted)
+        return undefined;
+    if (params.userParts.length === 0)
+        throw new Error('No parts in the newMessage.');
+    // 1. The message, as the Runner stores it.
+    const invocationId = `e-${randomUUID()}`;
+    const userContent = { role: 'user', parts: params.userParts };
+    await sessions.append(session, createTurnEvent({ invocationId, author: 'user', content: userContent }));
+    if (signal?.aborted)
+        return { stopped: true };
+    // 2. The start: the message's text as the input, and every node's prior runs.
+    const start = workflowResume({ events: session.events, invocationId, userContent, workflowPath: graph.name });
+    // 3. The walk, its events handed on in the order they are stored.
+    const queue = [];
+    let wake;
+    const runtime = agentNodeRuntime({
+        agents: params.agents,
+        session,
+        sessions,
+        invocationId,
+        userContent,
+        loop: {
+            adapterFor: params.adapterFor,
+            stream: params.stream ?? false,
+            ...(params.memory ? { memory: params.memory } : {}),
+            ...(params.log ? { log: params.log } : {}),
+            ...(params.selfCorrection ? { selfCorrection: params.selfCorrection } : {}),
+            ...(params.credentials ? { credentials: params.credentials } : {}),
+        },
+        onEvent: (event) => {
+            // A node's input turn is appended straight to the session, as ADK's runLlmAgentAsNode appends it: stored, never yielded.
+            if (event.author === 'user')
+                return;
+            queue.push(event);
+            wake?.();
+        },
+        // A node agent's streamed text, yielded as ADK's Runner yields its partial events.
+        onPartial: (event) => {
+            queue.push(event);
+            wake?.();
+        },
+    });
+    // Every event handed over is queued a microtask later (agentNodeRuntime.store); `stored` waits for all of them.
+    const handed = new Set();
+    const store = (event) => {
+        const queued = runtime.store(event).catch(() => { }); // a store error surfaces from settled()
+        handed.add(queued);
+        void queued.finally(() => handed.delete(queued));
+    };
+    const stored = async () => {
+        while (handed.size > 0)
+            await Promise.all([...handed]);
+        await runtime.settled();
+    };
+    const runNode = askUserNodeRunner({ invocationId, onEvent: store }, toolNodeRunner({
+        invocationId,
+        appName,
+        userId,
+        sessionId,
+        userContent,
+        resolveTool: params.resolveTool,
+        state: () => session.state,
+        ...(params.memory ? { memory: params.memory } : {}),
+        ...(params.credentials ? { credentials: params.credentials } : {}),
+        onEvent: store,
+        traceCall: traceToolNodeCall,
+    }, runtime.runNode));
+    const onEvent = (event) => {
+        runtime.onEvent(event);
+        // ADK's reportNodeError: the workflow's own event for a node that gave up.
+        if (event.type === 'node_error' && event.source === 'workflow')
+            store(nodeErrorEvent(event, invocationId));
+    };
+    let end;
+    let failure;
+    let finished = false;
+    const walk = traceWorkflowInvocation({ name: graph.name, path: graph.name }, { sessionId, invocationId }, async () => {
+        try {
+            const run = await runWorkflowGraph(graph, {
+                input: start.input,
+                resume: start.resume,
+                runNode,
+                onEvent,
+                traceNode: traceNodeExecution,
+                ...(signal ? { signal } : {}),
+            });
+            // 4. A paused walk: the workflow's own record, after every node's event.
+            if (run.interruptIds.length > 0)
+                store(workflowPauseEvent({ name: graph.name, invocationId, input: start.input, interruptIds: run.interruptIds }));
+            await stored();
+            return run;
+        }
+        catch (error) {
+            await stored().catch(() => { });
+            throw error;
+        }
+    }).then((run) => {
+        end = { run };
+    }, (error) => {
+        // ADK's Runner ends an aborted run without an error; the turn's control holds why.
+        if (isAborted(error) || signal?.aborted)
+            end = { stopped: true };
+        else
+            failure = { error };
+    }).finally(() => {
+        finished = true;
+        wake?.();
+    });
+    for (;;) {
+        while (queue.length > 0)
+            yield queue.shift();
+        if (finished)
+            break;
+        await new Promise((resolve) => (wake = resolve));
+        wake = undefined;
+    }
+    await walk;
+    if (failure)
+        throw failure.error;
+    return end;
+}

package/dist/lib/workflowConfig.d.ts

@@ -69,9 +69,10 @@ export declare function nodeSettings(node: WorkflowNodeYaml | undefined): {
 /**
  * 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.
+ * `default` key always has something to fall back from. One function for
+ * both runtimes; it lives in lib/workflow/route.ts.
  */
-export declare function routeOf(output: unknown, routeKey?: string): string;
+export { routeOf } from './workflow/route.ts';
 /** 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. */

package/dist/lib/workflowConfig.js

@@ -57,19 +57,10 @@ export function nodeSettings(node) {
 /**
  * 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.
+ * `default` key always has something to fall back from. One function for
+ * both runtimes; it lives in lib/workflow/route.ts.
  */
-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();
-}
+export { routeOf } from './workflow/route.js';
 /** 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. */

package/dist/scripts/a2a_server.js

@@ -79,7 +79,6 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { randomBytes } from 'node:crypto';
 import { realpathSync, writeFileSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
-import { setLogLevel, LogLevel } from '@google/adk';
 import { createA2AApp } from '../lib/a2a/app.js';
 import { callerTokens, firstOf, hashCallerToken, jwtIdentity, parseCallers, sharedSecret, trustedHeader, } from '../lib/a2a/identity.js';
 import { budgets, memoryUsageStore, parseBudgets, postgresUsageStore, supabaseUsageStore } from '../lib/a2a/policy.js';
@@ -90,6 +89,7 @@ import { dbSchema } from '../lib/storage/schema.js';
 import { postgresStorage } from '../lib/storage/postgres/index.js';
 import { isPlaceholderValue, loadEnv } from '../lib/loadEnv.js';
 import { flushTracing } from '../lib/observability/tracer.js';
+import { setLogLevel } from '../lib/runtime/logging.js';
 // Re-exported for existing importers (tests/failNarration.test.ts).
 export { describeTurnError } from '../lib/a2a/executor.js';
 /** Minimum bearer-secret length below which the server warns. */
@@ -138,8 +138,9 @@ export async function startServer(syndicateName = 'syndicate.yaml', extensions =
     // the root span carries the full user message and answer.
     if (process.env.OTEL_CONSOLE_SPANS === undefined)
         process.env.OTEL_CONSOLE_SPANS = 'false';
-    // ADK's INFO/DEBUG logs carry raw event JSON; keep them quiet.
-    setLogLevel(LogLevel.WARN);
+    // The engine's level, which ADK's logger follows: ADK's INFO/DEBUG logs
+    // carry raw event JSON, so keep them quiet.
+    setLogLevel('warn');
     const publicUrl = process.env.PUBLIC_URL?.trim() || undefined;
     const port = envInt('PORT', 4000);
     // ── Authentication posture ─────────────────────────────────────────────────

package/dist/scripts/assistant_worker.d.ts

@@ -13,7 +13,8 @@
  *   and writes the result (or the error) back to the store, where
  *   `task_get` reads it in a later conversation.
  *
- *   A job runs through lib/runtime/syndicateTurn.ts, the same runtime the
+ *   A job runs through lib/runtime/syndicateTurn.ts (on the runtime
+ *   MELCHIZEDEK_RUNTIME names, ADK by default), the same runtime the
  *   A2A server, the REPL and the observatory use, so it runs the exact agent
  *   the conversation would have called directly — with the same step cap —
  *   and the job timeout ABORTS the run (the model call in flight included)

package/dist/scripts/assistant_worker.js

@@ -13,7 +13,8 @@
  *   and writes the result (or the error) back to the store, where
  *   `task_get` reads it in a later conversation.
  *
- *   A job runs through lib/runtime/syndicateTurn.ts, the same runtime the
+ *   A job runs through lib/runtime/syndicateTurn.ts (on the runtime
+ *   MELCHIZEDEK_RUNTIME names, ADK by default), the same runtime the
  *   A2A server, the REPL and the observatory use, so it runs the exact agent
  *   the conversation would have called directly — with the same step cap —
  *   and the job timeout ABORTS the run (the model call in flight included)
@@ -31,17 +32,19 @@
  *   and must match the chat process's value. Run ONE worker per store.
  */
 import { randomUUID } from 'node:crypto';
-import { InMemorySessionService, LogLevel, setLogLevel } from '@google/adk';
 import { loadEnv } from '../lib/loadEnv.js';
 import { loadSyndicate } from '../lib/loadSyndicate.js';
 import { runSyndicateTurn } from '../lib/runtime/syndicateTurn.js';
+import { asAdkSessionService } from '../lib/runtime/adkSessionBridge.js';
+import { setLogLevel } from '../lib/runtime/logging.js';
+import { InProcessSessionService } from '../lib/runtime/sessions.js';
 import { PROVIDERS, providerForModel, providerKeyPresent, registerAvailableProviders, } from '../lib/models/registry.js';
 import { getTaskBackend, setTaskBackend, taskStorePath } from '../lib/tools/taskTools.js';
 import { postgresStorage } from '../lib/storage/postgres/index.js';
 import { dbSchema } from '../lib/storage/schema.js';
 import { hostname } from 'node:os';
 loadEnv(import.meta.url);
-setLogLevel(LogLevel.WARN);
+setLogLevel('warn');
 registerAvailableProviders();
 // ── CLI ──────────────────────────────────────────────────────────────────────
 const argv = process.argv.slice(2).filter((a) => a !== '--');
@@ -111,7 +114,9 @@ async function runJob(job) {
             appName: 'assistant-worker',
             userId: 'local-user',
             sessionId: randomUUID(),
-            sessionService: new InMemorySessionService(),
+            // A fresh in-process store per job, as the turn runner's signature
+            // names it (ADR 0080). The runtime follows MELCHIZEDEK_RUNTIME.
+            sessionService: asAdkSessionService(new InProcessSessionService()),
             compile: { log, onUnknownTool: (n) => log(`unknown tool '${n}' skipped`) },
             signal: current.signal,
             deadlineMs: JOB_TIMEOUT_MS,

package/dist/scripts/syndicate_chat.js

@@ -5,7 +5,11 @@ import { join } from 'node:path';
 import { loadSyndicate, parseCliBindings } from '../lib/loadSyndicate.js';
 import { isDispatchSyndicate } from '../lib/dispatch.js';
 import { approvalResponsePart, describeApproval, describeInput, ingestTurnMemory, runSyndicateTurn } from '../lib/runtime/syndicateTurn.js';
-import { InMemorySessionService, getFunctionCalls, getFunctionResponses, setLogLevel, LogLevel, } from '@google/adk';
+import { getFunctionCalls, getFunctionResponses } from '../lib/runtime/events.js';
+import { InProcessSessionService } from '../lib/runtime/sessions.js';
+import { asAdkSessionService, asSessionService } from '../lib/runtime/adkSessionBridge.js';
+import { asAdkMemoryService } from '../lib/runtime/adkMemoryBridge.js';
+import { setLogLevel } from '../lib/runtime/logging.js';
 import { randomUUID } from 'node:crypto';
 import { loadEnv } from '../lib/loadEnv.js';
 // ── LLM Provider Registration ─────────────────────────────────────────────────
@@ -18,8 +22,8 @@ import { registerAvailableProviders, providerForModel, providerKeyPresent, PROVI
 // ── Persistence Factory ───────────────────────────────────────────────────────
 // Supabase-specific initialization lives in supabaseProvider.ts.
 import { hasSupabaseCredentials, createSupabaseServices, } from '../lib/persistence/supabaseProvider.js';
-// Silence ADK verbose INFO logging natively
-setLogLevel(LogLevel.WARN);
+// The engine's level, which ADK's logger follows: no INFO chatter in the chat.
+setLogLevel('warn');
 const c = {
     reset: '\x1b[0m',
     bold: '\x1b[1m',
@@ -175,7 +179,10 @@ async function main() {
     // The same services the server would use for this syndicate's
     // memory_system: Supabase sessions (and the memory service for
     // long-term) when configured, process memory otherwise.
-    let sessionService = new InMemorySessionService();
+    // The engine's stores (ADR 0080): the in-process one, or Supabase's,
+    // which has both faces. The turn runner takes ADK's face (its signature
+    // is fixed), and follows MELCHIZEDEK_RUNTIME for the runtime.
+    let sessionService = new InProcessSessionService();
     let memoryService;
     if (persistence.sessionService === 'supabase') {
         const services = await createSupabaseServices({
@@ -188,7 +195,9 @@ async function main() {
         memoryService = services.memoryService;
     }
     const appName = config.syndicate_name || 'melchizedek-syndicate';
-    await sessionService.createSession({ appName, userId: SESSION_USER_ID, sessionId: SESSION_ID, state: {} });
+    await asSessionService(sessionService).create({ appName, userId: SESSION_USER_ID, sessionId: SESSION_ID, state: {} });
+    const turnSessions = asAdkSessionService(sessionService);
+    const turnMemory = memoryService ? asAdkMemoryService(memoryService) : undefined;
     banner(config, persistence, mergedBindings, SESSION_ID);
     // Plan-dispatch, nested yaml_reference syndicates, guards and the
     // max_steps cap run here exactly as the A2A server runs them: both call
@@ -227,8 +236,8 @@ async function main() {
                 appName,
                 userId: SESSION_USER_ID,
                 sessionId: SESSION_ID,
-                sessionService,
-                memoryService,
+                sessionService: turnSessions,
+                memoryService: turnMemory,
                 compile: {
                     onUnknownTool: (name) => console.warn(`${c.yellow}⚠ Unknown tool: '${name}' — skipping.${c.reset}`),
                     log: (message) => console.log(`${c.dim}  ${message}${c.reset}`),
@@ -276,12 +285,12 @@ async function main() {
         }
     }
     const ingest = async () => {
-        if (!memoryService)
+        if (!turnMemory)
             return;
         try {
             const ingested = await ingestTurnMemory({
-                memoryService,
-                sessionService,
+                memoryService: turnMemory,
+                sessionService: turnSessions,
                 appName,
                 userId: SESSION_USER_ID,
                 sessionId: SESSION_ID,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "melchizedek-agents",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "A multi-model, multi-agent orchestration framework on Google ADK — YAML-defined syndicates, Supabase session persistence, pgvector long-term memory. Companion repo to the lyceumagents.com curriculum.",
   "type": "module",
   "license": "MIT",
@@ -35,6 +35,7 @@
     "./storage/postgres": "./dist/lib/storage/postgres/index.js",
     "./grounding": "./dist/lib/grounding.js",
     "./config": "./dist/lib/config.js",
+    "./model": "./dist/lib/model.js",
     "./models/*": "./dist/lib/models/*.js",
     "./tools": "./dist/lib/toolRegistry.js",
     "./tools/*": "./dist/lib/tools/*.js",
@@ -102,6 +103,7 @@
     "assistant:worker": "node --disable-warning=DEP0040 --experimental-strip-types scripts/assistant_worker.ts",
     "demo:models": "node --disable-warning=DEP0040 --experimental-strip-types scripts/demo_model_optionality.ts",
     "demo:direct": "node --disable-warning=DEP0040 --experimental-strip-types scripts/direct_call.ts",
+    "parity": "node --disable-warning=DEP0040 --experimental-strip-types scripts/parity_check.ts",
     "mcp:demo": "node --disable-warning=DEP0040 --experimental-strip-types scripts/demo_mcp_server.ts",
     "mcp:wiki": "node --disable-warning=DEP0040 --experimental-strip-types scripts/wiki/mcp_server.ts",
     "mcp:science": "node --disable-warning=DEP0040 --experimental-strip-types scripts/science_mcp_server.ts",
@@ -111,6 +113,7 @@
     "schema:gen": "node --disable-warning=DEP0040 --experimental-strip-types scripts/gen_syndicate_schema.ts",
     "start:a2a": "node --disable-warning=DEP0040 --experimental-strip-types scripts/a2a_server.ts",
     "test": "node --disable-warning=DEP0040 --experimental-strip-types --test tests/**/*.test.ts",
+    "fixtures:sessions:check": "node --disable-warning=DEP0040 --experimental-strip-types tests/fixtures/sessions/generate.ts --check",
     "init": "node --disable-warning=DEP0040 --experimental-strip-types scripts/init.ts",
     "db": "node --disable-warning=DEP0040 --experimental-strip-types scripts/db.ts",
     "registry": "node --disable-warning=DEP0040 --experimental-strip-types scripts/registry.ts",

package/skills/briefs/melchizedek-author.md

@@ -38,7 +38,8 @@ Agent block keys (orchestrator and each subagent):
 - `code_execution: gemini` lets a Gemini agent write and run Python in Google's sandbox (nothing runs on your machine). `context: { compact_after_tokens: 60000 }` on a delegate orchestrator summarizes a long conversation instead of overflowing it. `mode: task` on a workflow node makes its output its `finish_task` arguments.
 - `openapi:` a list of OpenAPI 3 spec files (relative to the syndicate file) whose operations become the agent's tools; only GET operations unless `operations` names others; `auth` reads `bearer_env` or `api_key: {env, in, name}` from the environment. Read `weather.yaml` for the worked example.
 - `mcp_server_url:` on a subagent: tools discovered from that MCP server at start (the melchizedek-serve skill).
-- `generateContentConfig:` per agent: `temperature`, `maxOutputTokens`, `responseMimeType: "application/json"` for structured output, `thinkingConfig: { thinkingLevel: MEDIUM, includeThoughts: false }` on Gemini models that think. Thinking tokens count against `maxOutputTokens`, so a thinking agent with long output needs a high ceiling (the Scribe uses 24576).
+- `reasoning:` how hard the agent reasons, on any provider: `none`, `low`, `medium`, `high`, or `{ budget_tokens: 4096 }`. The compiler sends each provider the field it reads, so the setting survives a change to the `model:` line; unset keeps the provider's default. The templates in `config/agents/templates/` give a gathering or routing agent `none` and a synthesizing agent `low` or `medium`. What each level becomes per provider and per Claude model generation belongs to the melchizedek-models skill.
+- `generateContentConfig:` per agent: `temperature`, `maxOutputTokens`, `responseMimeType: "application/json"` for structured output. Thinking tokens count against `maxOutputTokens`, so a reasoning agent with long output needs a high ceiling (the Scribe uses 24576). `thinkingConfig` and `reasoningEffort` inside this block are the older, provider-specific spelling of `reasoning:`: some starter-pack examples still use them and they still load, but an agent that sets either beside `reasoning:` fails to load. New agents use `reasoning:`.
 - `outputSchema:` a JSON schema (types in upper case: `OBJECT`, `STRING`, `INTEGER`, `BOOLEAN`, `ARRAY`) the agent's reply must satisfy.
 - Subagents receive one string argument, `query`, and see nothing else of the conversation. The orchestrator's instruction must say what to pass them, in full, every time.
 
@@ -60,5 +61,5 @@ Validate and run:
 Editing a syndicate that is already serving:
 - `melchizedek-serve` compiles a syndicate when it is first requested and caches it for the life of the process; an edited file changes nothing until the server restarts. A deployment that boots agents from the Supabase agent registry (`registry:<id>`) serves the registry row, not the file, until the row is republished.
 
-IDENTIFIERS (verbatim): config/agents/, syndicateSchema.yaml, assets/minimal.yaml, syndicate_name, memory_system, internal-only, session-only, long-term, variables:, {{current_date}}, memory_extraction_rules:, dispatch:, default_route, route_overrides, workflow:, edges, nodes, ask_user, join, map, START, pipeline.yaml, orchestrator:, subagents:, description, model, instruction, tools:, mcp_server_url:, generateContentConfig:, outputSchema:, responseMimeType, thinkingConfig, maxOutputTokens, # tier:, npm test, npx melchizedek-doctor, npx melchizedek-chat --syndicate, loadSyndicate, gemini-3.8-flash, gemini-3.5-flash-lite, critic.yaml, scribe.yaml, tutor.yaml, patient_advocate.yaml
+IDENTIFIERS (verbatim): config/agents/, syndicateSchema.yaml, assets/minimal.yaml, syndicate_name, memory_system, internal-only, session-only, long-term, variables:, {{current_date}}, memory_extraction_rules:, dispatch:, default_route, route_overrides, workflow:, edges, nodes, ask_user, join, map, START, pipeline.yaml, orchestrator:, subagents:, description, model, instruction, tools:, mcp_server_url:, reasoning:, budget_tokens, config/agents/templates/, generateContentConfig:, outputSchema:, responseMimeType, thinkingConfig, reasoningEffort, maxOutputTokens, # tier:, npm test, npx melchizedek-doctor, npx melchizedek-chat --syndicate, loadSyndicate, gemini-3.8-flash, gemini-3.5-flash-lite, critic.yaml, scribe.yaml, tutor.yaml, patient_advocate.yaml
 LIMITS: the Node one-liner goes in a fenced bash block exactly as given. Body under 170 lines.

package/skills/briefs/melchizedek-models.md

@@ -6,19 +6,19 @@ STRUCTURE (exact):
 Frontmatter, verbatim:
 ---
 name: melchizedek-models
-description: "Choose and wire a model for a Melchizedek agent: how a model id routes to Gemini, Claude, GPT, Grok, or local Ollama, which environment variable each needs, the gateway fallback, the doctor, and per-agent generation settings. Use when the user changes a model line, adds a provider key, sees Model not found or a gateway error, or asks which keys a syndicate needs."
+description: "Choose and wire a model for a Melchizedek agent: how a model id routes to Gemini, Claude, GPT, Grok, Kimi, or local Ollama, which environment variable each needs, the gateway fallback, the doctor, and per-agent settings such as how hard an agent reasons. Use when the user changes a model line, adds a provider key, wants an agent to think more or less, sees Model not found or a gateway error, or asks which keys a syndicate needs."
 ---
 Then `##` sections in this order: "How a model id routes", "Which key unlocks what", "Run with no key at all", "One key for every cloud provider", "Settings per agent", "Mixing providers in one syndicate", "Reading the errors".
 
 FACTS:
 How a model id routes:
-- The `model:` string's prefix names the provider: `claude-*` to Anthropic, `gpt-*` and `o<digit>*` to OpenAI, `grok-*` to xAI, `ollama/<model>` to a local Ollama, and everything else to Gemini (the ADK-native default).
+- The `model:` string's prefix names the provider: `claude-*` to Anthropic, `gpt-*` and `o<digit>*` to OpenAI, `grok-*` to xAI, `kimi-*` to Moonshot AI (Kimi), `ollama/<model>` to a local Ollama, and everything else to Gemini (the ADK-native default).
 - There is no allowlist in the engine: any id a provider currently serves works as written. A new model is a one-line YAML change.
-- Ids verified in this deployment: `gemini-3.8-flash` (production), `gemini-3.5-flash-lite` (subagents, cost), `claude-sonnet-4-6`, `claude-opus-4-6`, `claude-haiku-4-5-20251001`, `gpt-5-mini`, `gpt-5`, `grok-4.7`, `ollama/qwen3:8b`.
+- Ids verified in this deployment: `gemini-3.8-flash` (production), `gemini-3.5-flash-lite` (subagents, cost), `claude-sonnet-4-6`, `claude-opus-4-6`, `claude-haiku-4-5-20251001`, `gpt-5-mini`, `gpt-5`, `grok-4.7`, `kimi-k3`, `ollama/qwen3:8b`.
 - `gemini-2.5-flash` returns a 400 about tool call context circulation with the server-side tool flag the framework sets; use `gemini-3.8-flash` or newer.
 - Subagents inherit the orchestrator's `model` when they set none.
 Which key unlocks what:
-- `GOOGLE_GENAI_API_KEY` for Gemini (also the embedding model behind long-term memory); `ANTHROPIC_API_KEY`; `OPENAI_API_KEY`; `XAI_API_KEY`; no key for `ollama/*`.
+- `GOOGLE_GENAI_API_KEY` for Gemini (also the embedding model behind long-term memory); `ANTHROPIC_API_KEY`; `OPENAI_API_KEY`; `XAI_API_KEY`; `MOONSHOT_API_KEY` for Kimi; no key for `ollama/*`.
 - A provider registers only when its key is present; a missing key logs the provider as disabled, and an agent on that provider fails with `Model not found`.
 - `npx melchizedek-doctor` (clone: `npm run doctor`) reads every syndicate, resolves each agent's model under the current `.env`, and prints per agent: model, provider, which server-side search tools the path keeps or drops, and whether it is funded; per syndicate a verdict; and the variables that would unlock the most. `--json`, `--check` (exit 1 when any syndicate is blocked). Read-only, no key value printed.
 - The `# tier:` first line of every starter-pack file states its cost class (`keyless`, one provider name, or `multi-provider`); the doctor checks the claim against the models.
@@ -32,16 +32,20 @@ One key for every cloud provider (the gateway fallback):
 - Dials: `MODEL_GATEWAY_MODEL_MAP=<your id>=<the gateway's id>` renames an id the gateway rejects; `MODEL_GATEWAY_BASE_URL` points at a self-hosted proxy.
 - Telemetry attributes the call to the upstream provider and records the transport separately.
 Settings per agent:
-- `generateContentConfig:` on any agent: `temperature` (where the provider still exposes it), `maxOutputTokens`, `thinkingConfig: { thinkingLevel: MEDIUM, includeThoughts: false }` on Gemini models that think. Thinking tokens count against `maxOutputTokens`.
-- The framework's own pattern: data-gathering subagents on a lite model with a tight output cap; synthesis on the stronger model with a thinking level and room to reason.
+- `reasoning:` on the agent block, beside `model:`, sets how hard the agent reasons: `none`, `low`, `medium`, `high`, or `{ budget_tokens: 4096 }`. It reads the same on every provider; unset keeps the provider's default. The compiler sends each provider the field it reads: Gemini 3 and later get a thinking level (`none` is `MINIMAL`, then `LOW`, `MEDIUM`, `HIGH`); Gemini 2.x, and Claude 4.6 or older, get a thinking budget of 0, 2048, 8192 or 16384 tokens; every later Claude model gets adaptive thinking at an effort of `low`, `medium` or `high`, and `none` is that model's own off switch, sent at `low` effort; every other provider, and the gateway, gets an effort word, and where the provider lacks that word, its nearest setting above.
+- A `budget_tokens` value goes as written to Gemini and to Claude 4.6 or older, and as the smallest level that covers it everywhere else, later Claude models included. The effort word is always sent too, because the gateway can serve any cloud id; a direct provider ignores the field it does not read. Changing the `model:` line keeps the setting. Unset, a later Claude model keeps its own default: it thinks, except Opus 4.7 and 4.8, which think only when asked.
+- Four provider limits: on Claude 4.6 or older, the adapter raises a budget under 1024 to 1024, the least Anthropic takes; on every Claude model, the Anthropic SDK refuses a non-streaming request whose output ceiling passes about 21000 tokens, and the adapter sets that ceiling to at least the thinking budget plus 2048, so a `budget_tokens` above about 19000 fails a non-streaming turn, while the levels stay under it; on Claude Opus 5 and 5.5, Fable and Mythos, `none` is adaptive thinking at `low` effort, so a little thinking remains, because Opus 5.5, Fable and Mythos cannot turn thinking off and Opus 5's off switch can write a tool call as text that never runs; Gemini 2.5 Pro rejects a budget of 0, so `none` fails on it.
+- `generateContentConfig:` on any agent: `temperature` (where the provider still exposes it; never sent to Claude), `maxOutputTokens`. Thinking tokens count against `maxOutputTokens`, so a reasoning agent with long output needs room; the Claude adapter raises its own ceiling to the thinking budget plus 2048 tokens, on every Claude model. A level counts as its budget (2048, 8192 or 16384), so `high`, or a later Claude model that thinks by default, gets at least 18432.
+- `thinkingConfig` and `reasoningEffort` inside `generateContentConfig:` are the older, provider-specific spelling of `reasoning:`. They still load, but each reaches only the providers that read it (a `thinkingLevel` written for Gemini does nothing on Claude). An agent that sets either beside `reasoning:` fails to load. `thinkingConfig` stays only for `includeThoughts: true`, which streams Gemini's thought trace and has no `reasoning:` form; such an agent sets its level inside `thinkingConfig` too (`thinkingLevel`) and leaves `reasoning:` out.
+- The framework's own pattern: data-gathering subagents on a lite model with `reasoning: none` and a tight output cap; synthesis on the stronger model with `reasoning: low` or higher and room to reason. The templates in `config/agents/templates/` follow it.
 Mixing providers in one syndicate:
 - Any agent in a graph can run on a different provider; `model_zoo.yaml` declares one lightweight agent per provider, and in a clone `npm run demo:models` sends one prompt through each.
 - In code, `registerAvailableProviders()` from `melchizedek-agents` registers every provider whose key is present so a plain ADK `LlmAgent` can take any of these ids; in a clone `npm run demo:direct -- --model ollama/qwen3:8b hello` runs one agent with no YAML.
 Reading the errors:
-- `Model not found` for a `claude-*`, `gpt-*` or `grok-*` id: the provider's key is unset. Set it, or set the gateway pair.
+- `Model not found` for a `claude-*`, `gpt-*`, `grok-*` or `kimi-*` id: the provider's key is unset. Set it, or set the gateway pair.
 - `GATEWAY_HTTP_ERROR ... 404/400`: the gateway rejected the mapped id; fix the name with `MODEL_GATEWAY_MODEL_MAP`.
 - `GATEWAY_KEY_MISSING`: `MODEL_GATEWAY` is set without `MODEL_GATEWAY_API_KEY`.
 - `OLLAMA_UNREACHABLE`: Ollama is not running (`ollama serve`) or the model is not pulled (`ollama list`).
 
-IDENTIFIERS (verbatim): model:, claude-*, gpt-*, grok-*, ollama/, gemini-3.8-flash, gemini-3.5-flash-lite, gemini-2.5-flash, ollama/qwen3:8b, GOOGLE_GENAI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY, npx melchizedek-doctor, --json, --check, # tier:, ollama pull qwen3:8b, http://localhost:11434/v1, MODEL_GATEWAY, MODEL_GATEWAY_API_KEY, MODEL_GATEWAY_MODEL_MAP, MODEL_GATEWAY_BASE_URL, X-API-Key, generateContentConfig:, maxOutputTokens, thinkingConfig, model_zoo.yaml, npm run demo:models, registerAvailableProviders, GATEWAY_HTTP_ERROR, GATEWAY_KEY_MISSING, OLLAMA_UNREACHABLE, Model not found
-LIMITS: the routing prefixes may be a short table. Body under 160 lines.
+IDENTIFIERS (verbatim): model:, claude-*, gpt-*, grok-*, kimi-*, ollama/, gemini-3.8-flash, gemini-3.5-flash-lite, gemini-2.5-flash, kimi-k3, ollama/qwen3:8b, GOOGLE_GENAI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY, MOONSHOT_API_KEY, npx melchizedek-doctor, --json, --check, # tier:, ollama pull qwen3:8b, http://localhost:11434/v1, MODEL_GATEWAY, MODEL_GATEWAY_API_KEY, MODEL_GATEWAY_MODEL_MAP, MODEL_GATEWAY_BASE_URL, X-API-Key, reasoning:, budget_tokens, generateContentConfig:, maxOutputTokens, thinkingConfig, reasoningEffort, thinkingLevel, includeThoughts, config/agents/templates/, model_zoo.yaml, npm run demo:models, registerAvailableProviders, GATEWAY_HTTP_ERROR, GATEWAY_KEY_MISSING, OLLAMA_UNREACHABLE, Model not found
+LIMITS: the routing prefixes and what `reasoning:` becomes per provider may each be a short table. Body under 160 lines.

package/skills/briefs/melchizedek.md

@@ -43,7 +43,7 @@ The starter pack (file → name → what it does → tier / extra requirement):
 Check the keys:
 - `npx melchizedek-doctor` (clone: `npm run doctor`) reads every syndicate the loader can see, resolves each agent's model to a provider under the current `.env`, and prints one table: agent, model, provider, which server-side tools the path keeps or drops, and whether the path is funded, with one verdict per syndicate and the variables that would unlock the most. Read-only; nothing sent, nothing written, no key value printed.
 - `--json` for machine-readable output; `--check` exits 1 when any syndicate is blocked.
-- Which key: GOOGLE_GENAI_API_KEY for gemini-* ids, ANTHROPIC_API_KEY for claude-*, OPENAI_API_KEY for gpt-*, XAI_API_KEY for grok-*, none for ollama/* (Ollama must be running, model pulled). Details and the gateway fallback: the melchizedek-models skill.
+- Which key: GOOGLE_GENAI_API_KEY for gemini-* ids, ANTHROPIC_API_KEY for claude-*, OPENAI_API_KEY for gpt-*, XAI_API_KEY for grok-*, MOONSHOT_API_KEY for kimi-*, none for ollama/* (Ollama must be running, model pulled). Details and the gateway fallback: the melchizedek-models skill.
 
 Run one:
 - Interactive: `npx melchizedek-chat --syndicate <name>` (clone: `npm run chat:syndicate -- --syndicate <name>`; every example also has an alias such as `npm run syndicate:tutor`). A banner shows the syndicate, orchestrator, subagents, and whether sessions and memory are in Supabase or in memory. Type `exit` to end the session; that is also when a long-term syndicate writes its memory.
@@ -60,7 +60,7 @@ Delegate a task from this agent:
 
 When something fails:
 - `Gemini API Key is not configured`: `.env` missing or GOOGLE_GENAI_API_KEY unset.
-- `Model not found` for a claude-*, gpt-* or grok-* id: that provider's key is not set, so the provider was not registered; the doctor names the variable.
+- `Model not found` for a claude-*, gpt-*, grok-* or kimi-* id: that provider's key is not set, so the provider was not registered; the doctor names the variable.
 - `OLLAMA_UNREACHABLE` for ollama/* ids: Ollama is not running, or the model is not pulled (`ollama list`).
 - `[400] Tool call context circulation is not enabled`: the agent's `model:` is too old for agent transfer; use `gemini-3.8-flash` or newer.
 - `Refusing to connect to private/loopback MCP host`: the SSRF guard; for a local MCP server set `ALLOW_PRIVATE_MCP=true` in `.env`.
@@ -68,5 +68,5 @@ When something fails:
 
 The other skills: melchizedek-author (design or edit a syndicate file), melchizedek-serve (A2A server and MCP in both directions), melchizedek-memory (Supabase sessions and long-term memory), melchizedek-models (model ids, providers, keys, the gateway), melchizedek-scribe (write documents from a brief with the Scribe).
 
-IDENTIFIERS (verbatim): config/agents/, config/agents/examples/, node_modules/melchizedek-agents/config/agents/examples/, MELCHIZEDEK_AGENTS_DIR, npx melchizedek-doctor, --json, --check, npx melchizedek-chat --syndicate, CHAT_STREAMING=false, --bind, --bindings, {{current_date}}, GOOGLE_GENAI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY, SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, ALLOW_PRIVATE_MCP=true, X_BEARER_TOKEN, scribe.yaml, tutor.yaml, augustin.yaml, syndicate.yaml
+IDENTIFIERS (verbatim): config/agents/, config/agents/examples/, node_modules/melchizedek-agents/config/agents/examples/, MELCHIZEDEK_AGENTS_DIR, npx melchizedek-doctor, --json, --check, npx melchizedek-chat --syndicate, CHAT_STREAMING=false, --bind, --bindings, {{current_date}}, GOOGLE_GENAI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY, MOONSHOT_API_KEY, SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, ALLOW_PRIVATE_MCP=true, X_BEARER_TOKEN, scribe.yaml, tutor.yaml, augustin.yaml, syndicate.yaml
 LIMITS: the starter-pack section is a bulleted list, one line per file, file name in backticks first. Body under 170 lines.

package/skills/melchizedek/SKILL.md

@@ -78,6 +78,7 @@ Provide keys in `.env` or in the environment:
 - `ANTHROPIC_API_KEY` for claude-* ids.
 - `OPENAI_API_KEY` for gpt-* ids.
 - `XAI_API_KEY` for grok-* ids.
+- `MOONSHOT_API_KEY` for kimi-* ids.
 - No key for ollama/* ids; start Ollama and pull the model.
 
 The `melchizedek-models` skill covers provider details and the gateway fallback.
@@ -147,7 +148,7 @@ CHAT_STREAMING=false npx melchizedek-chat --syndicate scribe -- "$(cat brief.md)
 ## When something fails
 
 - `Gemini API Key is not configured`: `.env` is missing or `GOOGLE_GENAI_API_KEY` is unset.
-- `Model not found` for a claude-*, gpt-*, or grok-* id: you did not set that provider's key, so the framework did not register the provider; run `npx melchizedek-doctor` to see the missing variable.
+- `Model not found` for a claude-*, gpt-*, grok-*, or kimi-* id: you did not set that provider's key, so the framework did not register the provider; run `npx melchizedek-doctor` to see the missing variable.
 - `OLLAMA_UNREACHABLE` for ollama/* ids: Ollama is not running, or you have not pulled the target model (`ollama list`).
 - `[400] Tool call context circulation is not enabled`: the agent uses a `model:` too old for agent transfer; update the agent to `gemini-3.8-flash` or newer.
 - `Refusing to connect to private/loopback MCP host`: the SSRF guard blocked the connection; for a local MCP server, set `ALLOW_PRIVATE_MCP=true` in `.env`.

package/skills/melchizedek-author/SKILL.md

@@ -45,7 +45,8 @@ Agent block keys for the orchestrator and each subagent:
 - `code_execution: gemini` lets a Gemini agent write and run Python in Google's sandbox (nothing runs on your machine). `context: { compact_after_tokens: 60000 }` on a delegate orchestrator summarizes a long conversation instead of overflowing it. `mode: task` on a workflow node makes its output its `finish_task` arguments.
 - `openapi:` a list of OpenAPI 3 spec files (relative to the syndicate file) whose operations become the agent's tools; only GET operations unless `operations` names others; `auth` reads `bearer_env` or `api_key: {env, in, name}` from the environment. Read `weather.yaml` for the worked example.
 - `mcp_server_url:`: URL on a subagent to discover MCP tools at start. The melchizedek-serve skill covers MCP servers.
-- `generateContentConfig:`: per-agent options: `temperature`, `maxOutputTokens`, `responseMimeType: "application/json"`, and `thinkingConfig: { thinkingLevel: MEDIUM, includeThoughts: false }` on Gemini models that think. Thinking tokens count against `maxOutputTokens`. The Scribe uses 24576 for `maxOutputTokens`.
+- `reasoning:`: how hard the agent reasons, on any provider: `none`, `low`, `medium`, `high`, or `{ budget_tokens: 4096 }`. The compiler sends each provider the field it reads, so the setting survives a change to the `model:` line. Leave it unset to keep the provider's default. The templates in `config/agents/templates/` give a gathering or routing agent `none` and a synthesizing agent `low` or `medium`. The melchizedek-models skill covers what each level becomes per provider and per Claude model generation.
+- `generateContentConfig:`: per-agent options: `temperature`, `maxOutputTokens`, `responseMimeType: "application/json"`. Thinking tokens count against `maxOutputTokens`, so a reasoning agent with long output needs a high ceiling. The Scribe uses 24576 for `maxOutputTokens`. `thinkingConfig` and `reasoningEffort` inside this block are the older, provider-specific spelling of `reasoning:`. Some starter-pack examples still use them and they still load, but an agent that sets either beside `reasoning:` fails to load. Write new agents with `reasoning:`.
 - `outputSchema:`: a JSON schema using uppercase types (`OBJECT`, `STRING`, `INTEGER`, `BOOLEAN`, `ARRAY`) that the agent reply must satisfy.
 
 Subagents receive one string argument, `query`, and see nothing else of the conversation. The orchestrator instruction must state what to pass them in full every time.

package/skills/melchizedek-author/assets/minimal.yaml

@@ -34,6 +34,7 @@ orchestrator:
         3. <Compose the reply from what came back.>
       </execution_framework>
     </prompt_instructions>
+  reasoning: low                    # none | low | medium | high, on any provider (melchizedek-models)
   generateContentConfig:
     maxOutputTokens: 4096
 
@@ -47,6 +48,7 @@ subagents:
     instruction: |
       You are Worker. <The one job, its inputs, and the exact shape of the
       report you return.>
+    reasoning: none                 # a gathering agent; raise it when the job is judgment
     generateContentConfig:
       maxOutputTokens: 2048
     # For structured output put the schema HERE, on a leaf with no tools —