melchizedek-agents 1.1.0 → 1.2.0

package/dist/lib/tools/taskTools.d.ts

@@ -33,7 +33,10 @@
  *     read-modify-write, not a lock. A running job's step checkpoints
  *     (ADR 0113) sit in a sidecar, <store>.checkpoints.json, keyed by id;
  *     every write of the store drops those of jobs no longer running or
- *     queued.
+ *     queued. A checkpoint above the cap (TaskBackendOptions.
+ *     checkpointMaxBytes, default 5 MiB of JSON) is not saved, on either
+ *     store: the job keeps its previous one and one line names the job id
+ *     and the sizes.
  *   - With Postgres (postgresStorage().taskQueue, migration 0009) each
  *     caller has its own list, scoped by the caller the tool call carries
  *     (the A2A server's scope key), and any number of workers claim jobs
@@ -129,6 +132,31 @@ export interface TaskBackend {
     /** The checkpoint a re-queued job left, or null. */
     loadCheckpoint?(job: OwnedTask): Promise<object | null>;
 }
+/**
+ * The largest checkpoint a backend stores by default: 5 MiB of serialized
+ * JSON (ADR 0113). A save above the cap is skipped and the job's previous
+ * checkpoint kept, so a huge run resumes from an older step boundary instead
+ * of failing or bloating the table.
+ */
+export declare const DEFAULT_CHECKPOINT_MAX_BYTES: number;
+/** The worker's variable that moves the cap, in bytes (scripts/assistant_worker.ts). */
+export declare const CHECKPOINT_MAX_BYTES_ENV = "MELCHIZEDEK_CHECKPOINT_MAX_BYTES";
+/** How a backend stores checkpoints (fileTaskBackendWith, postgresTaskBackend). */
+export interface TaskBackendOptions {
+    /** The largest checkpoint stored, in bytes of serialized JSON. Default DEFAULT_CHECKPOINT_MAX_BYTES; a value that is not a positive integer is the default. */
+    checkpointMaxBytes?: number;
+    /** Where a skipped save is reported: one line naming the job id and the sizes, never the checkpoint. Default console.warn. */
+    log?: (line: string) => void;
+}
+/** The cap a variable's value sets: a positive whole number of bytes, else the default. */
+export declare function checkpointMaxBytesSetting(raw: string | undefined): number;
+/**
+ * The checkpoint serialized once, as the backend stores it, or null when it
+ * is above the cap: then one line is logged with the job id and the sizes
+ * only (the checkpoint carries the user's text and tool results), and the
+ * caller keeps the previous checkpoint.
+ */
+export declare function checkpointJson(job: Pick<OwnedTask, 'id'>, checkpoint: object, options?: TaskBackendOptions): string | null;
 /** Records kept at most; finished ones are pruned oldest-first to make room. */
 export declare const MAX_TASKS = 500;
 /** A worker result is stored up to this length, then cut with a marker. */
@@ -154,7 +182,9 @@ export declare function finishJob(id: string, outcome: JobOutcome): void;
 export declare function applyFinish(store: TaskStore, id: string, outcome: JobOutcome): void;
 /** The interrupted-job rule for one record: back to the queue, or failed. */
 export declare function applyInterrupted(t: TaskRecord): 'requeued' | 'failed';
-/** The single-user JSON file (the default backend). */
+/** The single-user JSON file, its checkpoints capped by `options` (the default backend is fileTaskBackend). */
+export declare function fileTaskBackendWith(options?: TaskBackendOptions): TaskBackend;
+/** The single-user JSON file (the default backend), checkpoints capped at DEFAULT_CHECKPOINT_MAX_BYTES. */
 export declare const fileTaskBackend: TaskBackend;
 /** Plugs in where tasks live (postgresStorage().taskQueue); default the JSON file. */
 export declare function setTaskBackend(backend: TaskBackend): void;

package/dist/lib/tools/taskTools.js

@@ -33,7 +33,10 @@
  *     read-modify-write, not a lock. A running job's step checkpoints
  *     (ADR 0113) sit in a sidecar, <store>.checkpoints.json, keyed by id;
  *     every write of the store drops those of jobs no longer running or
- *     queued.
+ *     queued. A checkpoint above the cap (TaskBackendOptions.
+ *     checkpointMaxBytes, default 5 MiB of JSON) is not saved, on either
+ *     store: the job keeps its previous one and one line names the job id
+ *     and the sizes.
  *   - With Postgres (postgresStorage().taskQueue, migration 0009) each
  *     caller has its own list, scoped by the caller the tool call carries
  *     (the A2A server's scope key), and any number of workers claim jobs
@@ -54,6 +57,43 @@ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from '
 import { dirname, join, resolve } from 'node:path';
 import { z } from 'zod';
 import { defineTool } from './toolContract.js';
+/**
+ * The largest checkpoint a backend stores by default: 5 MiB of serialized
+ * JSON (ADR 0113). A save above the cap is skipped and the job's previous
+ * checkpoint kept, so a huge run resumes from an older step boundary instead
+ * of failing or bloating the table.
+ */
+export const DEFAULT_CHECKPOINT_MAX_BYTES = 5 * 1024 * 1024;
+/** The worker's variable that moves the cap, in bytes (scripts/assistant_worker.ts). */
+export const CHECKPOINT_MAX_BYTES_ENV = 'MELCHIZEDEK_CHECKPOINT_MAX_BYTES';
+const validCap = (n) => typeof n === 'number' && Number.isSafeInteger(n) && n > 0;
+/** The cap a variable's value sets: a positive whole number of bytes, else the default. */
+export function checkpointMaxBytesSetting(raw) {
+    const value = raw?.trim() ?? '';
+    if (!/^\d+$/.test(value))
+        return DEFAULT_CHECKPOINT_MAX_BYTES;
+    const n = Number(value);
+    return validCap(n) ? n : DEFAULT_CHECKPOINT_MAX_BYTES;
+}
+/**
+ * The checkpoint serialized once, as the backend stores it, or null when it
+ * is above the cap: then one line is logged with the job id and the sizes
+ * only (the checkpoint carries the user's text and tool results), and the
+ * caller keeps the previous checkpoint.
+ */
+export function checkpointJson(job, checkpoint, options = {}) {
+    const cap = validCap(options.checkpointMaxBytes) ? options.checkpointMaxBytes : DEFAULT_CHECKPOINT_MAX_BYTES;
+    const json = JSON.stringify(checkpoint);
+    // One UTF-16 unit is at most three UTF-8 bytes: a short string is under the cap without counting.
+    if (json.length * 3 <= cap)
+        return json;
+    const bytes = Buffer.byteLength(json, 'utf8');
+    if (bytes <= cap)
+        return json;
+    const log = options.log ?? ((line) => console.warn(`[tasks] ${line}`));
+    log(`checkpoint for job ${job.id} not saved: ${bytes} bytes is over the ${cap}-byte cap; the previous checkpoint is kept`);
+    return null;
+}
 /** Records kept at most; finished ones are pruned oldest-first to make room. */
 export const MAX_TASKS = 500;
 /** A worker result is stored up to this length, then cut with a marker. */
@@ -79,13 +119,17 @@ function readStore(path = taskStorePath()) {
     }
     return { version: 1, next_id: parsed.next_id, tasks: parsed.tasks };
 }
-/** Atomic JSON write: temp file + rename, so a reader never sees half a file. */
-function writeJson(value, path) {
+/** Atomic write: temp file + rename, so a reader never sees half a file. */
+function writeText(text, path) {
     mkdirSync(dirname(path), { recursive: true });
     const tmp = `${path}.${process.pid}.tmp`;
-    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+    writeFileSync(tmp, text);
     renameSync(tmp, path);
 }
+/** Atomic JSON write. */
+function writeJson(value, path) {
+    writeText(`${JSON.stringify(value, null, 2)}\n`, path);
+}
 function writeStore(store, path = taskStorePath()) {
     writeJson(store, path);
 }
@@ -250,35 +294,51 @@ export function applyInterrupted(t) {
     t.status = 'queued';
     return 'requeued';
 }
-/** The single-user JSON file (the default backend). */
-export const fileTaskBackend = {
-    read: async () => readStore(),
-    mutate: async (_owner, change) => mutate(change),
-    claimNext: async () => {
-        const job = claimNextJob();
-        return job ? { ...job, owner: '' } : null;
-    },
-    // No leases on the single-user file: the claim holds while the record is running.
-    renew: async (_worker, job) => readStore().tasks.find((t) => t.id === job.id)?.status === 'running',
-    finish: async (job, outcome) => finishJob(job.id, outcome),
-    recover: async () => recoverInterruptedJobs(),
-    saveCheckpoint: async (_worker, job, checkpoint) => {
-        const path = taskStorePath();
-        const record = readStore(path).tasks.find((t) => t.id === job.id);
-        if (!record || record.kind !== 'background' || record.status !== 'running')
-            return false;
-        const entries = readCheckpoints(path);
-        entries[job.id] = { checkpoint, at: now() };
-        writeJson(entries, taskCheckpointPath(path));
-        return true;
-    },
-    loadCheckpoint: async (job) => {
-        const path = taskStorePath();
-        if (!keepsCheckpoint(readStore(path).tasks.find((t) => t.id === job.id)))
-            return null;
-        return readCheckpoints(path)[job.id]?.checkpoint ?? null;
-    },
-};
+/**
+ * The sidecar with one job's checkpoint set from its serialized JSON, which
+ * is spliced in as it is rather than parsed and serialized again. The other
+ * entries are written compact; both shapes read back the same.
+ */
+function writeCheckpointEntry(storePath, id, json) {
+    const { [id]: _replaced, ...rest } = readCheckpoints(storePath);
+    const others = JSON.stringify(rest);
+    const entry = `${JSON.stringify(id)}:{"checkpoint":${json},"at":${JSON.stringify(now())}}`;
+    writeText(`${others === '{}' ? `{${entry}}` : `${others.slice(0, -1)},${entry}}`}\n`, taskCheckpointPath(storePath));
+}
+/** The single-user JSON file, its checkpoints capped by `options` (the default backend is fileTaskBackend). */
+export function fileTaskBackendWith(options = {}) {
+    return {
+        read: async () => readStore(),
+        mutate: async (_owner, change) => mutate(change),
+        claimNext: async () => {
+            const job = claimNextJob();
+            return job ? { ...job, owner: '' } : null;
+        },
+        // No leases on the single-user file: the claim holds while the record is running.
+        renew: async (_worker, job) => readStore().tasks.find((t) => t.id === job.id)?.status === 'running',
+        finish: async (job, outcome) => finishJob(job.id, outcome),
+        recover: async () => recoverInterruptedJobs(),
+        saveCheckpoint: async (_worker, job, checkpoint) => {
+            const path = taskStorePath();
+            const record = readStore(path).tasks.find((t) => t.id === job.id);
+            if (!record || record.kind !== 'background' || record.status !== 'running')
+                return false;
+            // Over the cap: nothing written, the previous checkpoint kept, the claim still held.
+            const json = checkpointJson(job, checkpoint, options);
+            if (json !== null)
+                writeCheckpointEntry(path, job.id, json);
+            return true;
+        },
+        loadCheckpoint: async (job) => {
+            const path = taskStorePath();
+            if (!keepsCheckpoint(readStore(path).tasks.find((t) => t.id === job.id)))
+                return null;
+            return readCheckpoints(path)[job.id]?.checkpoint ?? null;
+        },
+    };
+}
+/** The single-user JSON file (the default backend), checkpoints capped at DEFAULT_CHECKPOINT_MAX_BYTES. */
+export const fileTaskBackend = fileTaskBackendWith();
 let activeBackend = fileTaskBackend;
 /** Plugs in where tasks live (postgresStorage().taskQueue); default the JSON file. */
 export function setTaskBackend(backend) {

package/dist/lib/workflow/turn.d.ts

@@ -63,6 +63,7 @@
  */
 import type { ModelAdapter } from '../models/contract.ts';
 import type { TurnEvent } from '../runtime/events.ts';
+import type { WorkflowSubagentEnd } from '../runtime/native/delegate.ts';
 import type { MemoryService } from '../runtime/memoryService.ts';
 import type { NativeAgent } from '../runtime/native/request.ts';
 import type { SelfCorrection } from '../runtime/native/selfCorrection.ts';
@@ -93,15 +94,33 @@ export interface NativeWorkflowParams {
     selfCorrection?: SelfCorrection;
     /** The run's tool credentials, pinned to its app (ADR 0072). */
     credentials?: Pick<CredentialStore, 'get'>;
-    /** The agent nodes that are a nested workflow syndicate, by YAML name (ADR 0106). */
-    workflows?: ReadonlyMap<string, NestedWorkflow>;
+    /** The agent nodes that are a nested workflow syndicate (ADR 0106) or a nested dispatch syndicate (ADR 0120), by YAML name. */
+    workflows?: ReadonlyMap<string, NestedWorkflow | NestedRun>;
 }
 /** A workflow syndicate run as a node of another (ADR 0106): its graph, its agents, its tool nodes' lookup, and its own nested nodes. */
 export interface NestedWorkflow {
     graph: WorkflowGraph;
     agents: ReadonlyMap<string, NativeAgent>;
     resolveTool: (name: string) => unknown;
-    workflows?: ReadonlyMap<string, NestedWorkflow>;
+    workflows?: ReadonlyMap<string, NestedWorkflow | NestedRun>;
+}
+/** Where a node's own run goes: its child session, the message, the turn's signal. */
+export interface NestedRunParams {
+    sessions: SessionService;
+    appName: string;
+    userId: string;
+    sessionId: string;
+    userParts: unknown[];
+    signal?: AbortSignal;
+}
+/**
+ * A node that runs as something other than a graph (ADR 0120): a nested
+ * dispatch syndicate, its own turn (lib/runtime/native/delegate.ts
+ * nestedDispatchWalk). It runs where a nested workflow's walk runs, on the
+ * same child session, and ends as a walk ends.
+ */
+export interface NestedRun {
+    walk(run: NestedRunParams): AsyncGenerator<TurnEvent, WorkflowSubagentEnd | undefined>;
 }
 /** How the walk ended. */
 export interface NativeWorkflowEnd {

package/dist/lib/workflow/turn.js

@@ -62,7 +62,10 @@
  * carries, never instructions this module acts on.
  */
 import { randomUUID } from 'node:crypto';
-import { createTurnEvent } from '../runtime/events.js';
+import { APPROVAL_REQUEST } from '../runtime/approvals.js';
+import { createTurnEvent, getFunctionCalls } from '../runtime/events.js';
+import { entrySession } from '../runtime/native/delegate.js';
+import { INPUT_REQUEST } from '../workflowConfig.js';
 import { traceNodeExecution, traceToolNodeCall, traceWorkflowInvocation } from '../runtime/native/telemetry.js';
 import { TEMP_STATE_PREFIX } from '../runtime/sessions.js';
 import { NodeStoppedError, agentNodeRuntime, nodeInputContent } from './agentNode.js';
@@ -78,41 +81,150 @@ function lastText(event) {
         .filter((t) => t)
         .join('\n');
 }
+/** The requests a walk's interrupts are, as a node raises them: an approval request or an input request. */
+const RAISED = new Set([APPROVAL_REQUEST, INPUT_REQUEST]);
+/** The latest request call, by id, among `ids` that `events` hold (an agent's or a node's, never the user's). */
+function requestCalls(events, ids, author) {
+    const wanted = new Set(ids);
+    const calls = new Map();
+    for (let i = events.length - 1; i >= 0 && calls.size < wanted.size; i--) {
+        const event = events[i];
+        if (!event.author || event.author === 'user' || (author !== undefined && event.author !== author))
+            continue;
+        for (const call of getFunctionCalls(event)) {
+            if (call.id && call.name && RAISED.has(call.name) && wanted.has(call.id) && !calls.has(call.id))
+                calls.set(call.id, call);
+        }
+    }
+    return calls;
+}
+/**
+ * Whether a resumed walk's answer to `call` answers it: a decision for an
+ * approval request (a ToolConfirmation, or ADK's `{ response: <json> }`
+ * form, as lib/workflow/agentNode.ts reads one), any answer for an input
+ * request.
+ */
+function answers(call, value) {
+    if (value === undefined || !call)
+        return false;
+    if (call.name !== APPROVAL_REQUEST)
+        return true;
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const answer = value;
+    return typeof answer.confirmed === 'boolean' || typeof answer.response === 'string';
+}
+/** The part that carries `value` down to the nested walk, as the answer to `call`: its explicit reply, under the request's name. */
+function answerPart(call, value) {
+    const response = call.name === APPROVAL_REQUEST ? value : { result: value };
+    return { functionResponse: { id: call.id, name: call.name, response } };
+}
+/**
+ * A node whose answered interrupts an earlier resume already carried down
+ * (another node's answer was the one since): the output it stored after
+ * the last event that raised them, else undefined.
+ */
+function outputAfterRaise(events, path, ids) {
+    const open = new Set(ids);
+    let start = -1;
+    events.forEach((event, i) => {
+        if (event.nodeInfo?.path === path && (event.longRunningToolIds ?? []).some((id) => open.has(id)))
+            start = i;
+    });
+    if (start === -1)
+        return undefined;
+    for (let i = events.length - 1; i > start; i--) {
+        const event = events[i];
+        if (event.nodeInfo?.path === path && event.output !== undefined && !event.partial)
+            return event.output;
+    }
+    return undefined;
+}
+/**
+ * The node's pause on its caller's walk (ADR 0119): every request its own
+ * walk waits on, raised again as one event of the node's (a copy of each
+ * call, stamped with the node's path, the ids in `longRunningToolIds`, the
+ * node's input recorded for the resume), so the caller's walk pauses on
+ * the same ids, its resume reruns the node with their answers, and the
+ * turn finds the request (lib/runtime/native/interrupts.ts follows it down
+ * by id to the node that asked). Carries the walk's state writes so far.
+ */
+function raiseAgain(name, run, invocationId, calls, stateDelta) {
+    const event = createTurnEvent({
+        author: name,
+        invocationId,
+        content: { role: 'model', parts: calls.map((call) => ({ functionCall: structuredClone(call) })) },
+        ...(Object.keys(stateDelta).length ? { actions: { stateDelta } } : {}),
+    });
+    event.longRunningToolIds = calls.map((call) => call.id);
+    enrichNodeEvent(event, run, { invocationId });
+    event.actions = { ...event.actions, agentState: { ...(event.actions?.agentState ?? {}), input: run.input } };
+    return event;
+}
 /**
  * Runs `workflow` as the node `run` names (ADR 0106), as a delegated nested
  * workflow runs (ADR 0098): the whole graph walked on the child session
- * under the node's name (created from the caller's state the first time,
- * `temp:` keys dropped, and kept), the node's input as its message, its last
- * yielded event's text the node's output. The caller stores one event for
- * the node, carrying that output and the walk's state writes, so a resumed
- * walk completes the node from it. A walk that ends paused is refused by
- * name: a pause cannot reach the caller's walk yet (WS6-2).
+ * filed under the walk's app name and the node's behind its kind
+ * (`<walk's app>/node:<node>`, entryAppName, ADR 0119, ADR 0120; the one
+ * under an older key is continued when it ran there before), created from the caller's state the first time, `temp:` keys
+ * dropped, and kept; the node's input as its message, its last yielded
+ * event's text the node's output. The caller stores one event for the
+ * node, carrying that output and the walk's state writes, so a resumed
+ * walk completes the node from it.
+ *
+ * A walk that ends paused (an ask_user node, a gated agent node, a node of
+ * its own that is a nested workflow) pauses the node on the same ids
+ * (raiseAgain), and the caller's walk with it. Rerun on the resume, the
+ * node walks its graph again on the answers among its ids, each as its
+ * explicit reply (an approval decision as it came, an input request's
+ * answer as `{ result }`), which the nested walk's resume reads as a
+ * top-level one's; with none of them answered it waits again without
+ * walking; once an earlier resume finished it, its stored output is the
+ * node's.
  */
 async function runWorkflowNode(name, workflow, run, params, parent) {
-    const { sessions, userId, sessionId } = params;
-    const key = { appName: name, userId, sessionId };
+    const { sessions } = params;
+    const resumed = run.resumedInterruptIds ?? [];
+    let userParts;
+    if (resumed.length > 0) {
+        const raised = requestCalls(parent.session.events, resumed, name);
+        const answered = resumed.filter((id) => answers(raised.get(id), run.resumeInputs?.[id]));
+        if (answered.length === 0) {
+            parent.store(raiseAgain(name, run, parent.invocationId, resumed.map((id) => raised.get(id)).filter((c) => !!c), {}));
+            return { interruptIds: [...resumed] };
+        }
+        const finished = answered.length === resumed.length ? outputAfterRaise(parent.session.events, run.path, resumed) : undefined;
+        if (finished !== undefined)
+            return { output: finished };
+        userParts = answered.map((id) => answerPart(raised.get(id), run.resumeInputs[id]));
+    }
+    else {
+        const input = run.input === undefined || run.input === null ? parent.userContent : nodeInputContent(run.input);
+        userParts = input.parts ?? [];
+    }
     const state = Object.fromEntries(Object.entries(parent.session.state ?? {}).filter(([k]) => !k.startsWith(TEMP_STATE_PREFIX)));
-    if (!(await sessions.get(key)))
-        await sessions.create({ ...key, state });
-    const input = run.input === undefined || run.input === null ? parent.userContent : nodeInputContent(run.input);
-    const walk = runNativeWorkflow({
-        graph: workflow.graph,
-        agents: workflow.agents,
-        resolveTool: workflow.resolveTool,
-        ...(workflow.workflows ? { workflows: workflow.workflows } : {}),
-        sessions,
-        appName: name,
-        userId,
-        sessionId,
-        userParts: input.parts ?? [],
-        adapterFor: params.adapterFor,
-        signal: run.signal,
-        stream: false,
-        ...(params.memory ? { memory: params.memory } : {}),
-        ...(params.log ? { log: params.log } : {}),
-        ...(params.selfCorrection ? { selfCorrection: params.selfCorrection } : {}),
-        ...(params.credentials ? { credentials: params.credentials } : {}),
-    });
+    const child = await entrySession(sessions, { appName: parent.session.appName, userId: parent.session.userId, sessionId: parent.session.id, events: parent.session.events }, name, 'node', state, resumed.length > 0);
+    // A nested dispatch syndicate runs its own turn there (ADR 0120); a nested workflow walks its graph.
+    const walk = 'walk' in workflow
+        ? workflow.walk({ sessions, appName: child.appName, userId: child.userId, sessionId: child.id, userParts, ...(run.signal ? { signal: run.signal } : {}) })
+        : runNativeWorkflow({
+            graph: workflow.graph,
+            agents: workflow.agents,
+            resolveTool: workflow.resolveTool,
+            ...(workflow.workflows ? { workflows: workflow.workflows } : {}),
+            sessions,
+            appName: child.appName,
+            userId: child.userId,
+            sessionId: child.id,
+            userParts,
+            adapterFor: params.adapterFor,
+            signal: run.signal,
+            stream: false,
+            ...(params.memory ? { memory: params.memory } : {}),
+            ...(params.log ? { log: params.log } : {}),
+            ...(params.selfCorrection ? { selfCorrection: params.selfCorrection } : {}),
+            ...(params.credentials ? { credentials: params.credentials } : {}),
+        });
     let last;
     const stateDelta = {};
     let end;
@@ -133,7 +245,15 @@ async function runWorkflowNode(name, workflow, run, params, parent) {
         throw new NodeStoppedError(name, undefined);
     const paused = end.run?.interruptIds ?? [];
     if (paused.length > 0) {
-        throw new Error(`Node '${name}': the workflow it runs paused on ${paused.join(', ')}; a pause inside a workflow run as a node cannot reach the walk yet.`);
+        const walked = (await sessions.get({ appName: child.appName, userId: child.userId, sessionId: child.id }))?.events ?? [];
+        // A nested dispatch syndicate names the calls it waits on: they may sit in a route's delegation below its conversation (ADR 0120).
+        const named = 'requests' in end && end.requests ? new Map(end.requests.map((call) => [call.id, call])) : undefined;
+        const raised = named ?? requestCalls(walked, paused);
+        const missing = paused.filter((id) => !raised.has(id));
+        if (missing.length > 0)
+            throw new Error(`Node '${name}': the ${'walk' in workflow ? 'syndicate' : 'workflow'} it runs paused on ${missing.join(', ')}, which is not an approval request or a question.`);
+        parent.store(raiseAgain(name, run, parent.invocationId, paused.map((id) => raised.get(id)), stateDelta));
+        return { interruptIds: [...paused] };
     }
     const output = lastText(last);
     const event = createTurnEvent({

package/dist/lib/workflow.d.ts

@@ -48,13 +48,16 @@
  *
  * ── As a dispatch route or a workflow node (ADR 0106) ────────────────────
  * A `yaml_reference` to a workflow syndicate runs its whole graph there too,
- * on the child session filed under the entry's name, as a subagent does. A
- * route's answer is what the graph would answer as its own syndicate
- * (lib/runtime/syndicateTurn.ts); a node's is the nested walk's
- * (lib/workflow/turn.ts). A map over one is refused (lib/compile.ts), and
- * so are its pauses (an `ask_user` node, a gate): they cannot reach the
- * turn from a route or a node yet (lib/compile.ts compileWorkflowSpec,
- * loadNestedSyndicate).
+ * on the child session filed under the agent path and its kind
+ * (`<app>/route:<entry>`, `<walk's app>/node:<entry>`, ADR 0119, ADR 0120),
+ * as a subagent does. A route's answer is what the graph would
+ * answer as its own syndicate (lib/runtime/syndicateTurn.ts); a node's is
+ * the nested walk's (lib/workflow/turn.ts). A map over one is refused
+ * (lib/compile.ts). Its pauses (an `ask_user` node, a gate) reach the turn
+ * with the path from the entry down to the node that asked: a route's
+ * through the route's pause record in the conversation, a node's through
+ * its own pause on the caller's walk; the answer walks the nested graph
+ * again (ADR 0119).
  *
  * ── Approval gates (ADR 0098, ADR 0106) ──────────────────────────────────
  * A tool in a node agent's `require_approval`, and a skill script

package/dist/lib/workflow.js

@@ -48,13 +48,16 @@
  *
  * ── As a dispatch route or a workflow node (ADR 0106) ────────────────────
  * A `yaml_reference` to a workflow syndicate runs its whole graph there too,
- * on the child session filed under the entry's name, as a subagent does. A
- * route's answer is what the graph would answer as its own syndicate
- * (lib/runtime/syndicateTurn.ts); a node's is the nested walk's
- * (lib/workflow/turn.ts). A map over one is refused (lib/compile.ts), and
- * so are its pauses (an `ask_user` node, a gate): they cannot reach the
- * turn from a route or a node yet (lib/compile.ts compileWorkflowSpec,
- * loadNestedSyndicate).
+ * on the child session filed under the agent path and its kind
+ * (`<app>/route:<entry>`, `<walk's app>/node:<entry>`, ADR 0119, ADR 0120),
+ * as a subagent does. A route's answer is what the graph would
+ * answer as its own syndicate (lib/runtime/syndicateTurn.ts); a node's is
+ * the nested walk's (lib/workflow/turn.ts). A map over one is refused
+ * (lib/compile.ts). Its pauses (an `ask_user` node, a gate) reach the turn
+ * with the path from the entry down to the node that asked: a route's
+ * through the route's pause record in the conversation, a node's through
+ * its own pause on the caller's walk; the answer walks the nested graph
+ * again (ADR 0119).
  *
  * ── Approval gates (ADR 0098, ADR 0106) ──────────────────────────────────
  * A tool in a node agent's `require_approval`, and a skill script

package/dist/scripts/a2a_server.d.ts

@@ -37,8 +37,8 @@ export interface ServerOAuth extends OAuthServerSetup {
 }
 /**
  * Tool credentials and the consent step for the served syndicates, from
- * MELCHIZEDEK_CREDENTIAL_KEY, OAUTH_REDIRECT_URI, OAUTH_CALLBACK_IDENTITY
- * and MELCHIZEDEK_OAUTH_HOSTS (lib/a2a/oauthSetup.ts). Throws, naming
+ * MELCHIZEDEK_CREDENTIAL_KEY, OAUTH_REDIRECT_URI, OAUTH_CALLBACK_IDENTITY,
+ * MELCHIZEDEK_OAUTH_HOSTS and MELCHIZEDEK_CREDENTIAL_HOSTS (lib/a2a/oauthSetup.ts). Throws, naming
  * variables only, on a configuration that is unsafe or cannot work.
  */
 export declare function serverOAuth(options: {

package/dist/scripts/a2a_server.js

@@ -89,6 +89,11 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  *   MELCHIZEDEK_OAUTH_HOSTS   provider=host,host;…: the hosts each provider's tokens may
  *                             be sent to. Unset: authorization_code grants are refused,
  *                             client_credentials allowed (ADR 0114)
+ *   MELCHIZEDEK_CREDENTIAL_HOSTS  VARIABLE=host,host;…: the hosts each static credential
+ *                             variable a YAML sends (bearer_env, api_key.env,
+ *                             client_secret_env) may be sent to. Set, it is the whole
+ *                             list. Unset: sent where the YAML says, and the boot names
+ *                             each unbound variable (ADR 0122)
  */
 import { randomBytes } from 'node:crypto';
 import { readdirSync, realpathSync, writeFileSync } from 'node:fs';
@@ -109,6 +114,7 @@ import { loadSyndicate } from '../lib/loadSyndicate.js';
 import { callbackIdentity, callbackIdentityProblem, oauthServerSetup } from '../lib/a2a/oauthSetup.js';
 import { postgresCredentialRows } from '../lib/storage/postgres/credentialStore.js';
 import { setOAuthHosts } from '../lib/tools/oauthHosts.js';
+import { setCredentialHosts } from '../lib/tools/credentialHosts.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. */
@@ -200,8 +206,8 @@ export function servedFileSyndicates(syndicateName, servedAgents, registryAgents
 }
 /**
  * Tool credentials and the consent step for the served syndicates, from
- * MELCHIZEDEK_CREDENTIAL_KEY, OAUTH_REDIRECT_URI, OAUTH_CALLBACK_IDENTITY
- * and MELCHIZEDEK_OAUTH_HOSTS (lib/a2a/oauthSetup.ts). Throws, naming
+ * MELCHIZEDEK_CREDENTIAL_KEY, OAUTH_REDIRECT_URI, OAUTH_CALLBACK_IDENTITY,
+ * MELCHIZEDEK_OAUTH_HOSTS and MELCHIZEDEK_CREDENTIAL_HOSTS (lib/a2a/oauthSetup.ts). Throws, naming
  * variables only, on a configuration that is unsafe or cannot work.
  */
 export function serverOAuth(options) {
@@ -425,6 +431,8 @@ export async function startServer(syndicateName = 'syndicate.yaml', extensions =
         // An extension's allowlist wins over the environment's here too, as createA2AApp applies it.
         if (extensions.options?.oauthHosts)
             setOAuthHosts(extensions.options.oauthHosts);
+        if (extensions.options?.credentialHosts)
+            setCredentialHosts(extensions.options.credentialHosts);
         oauth = serverOAuth({
             syndicateName,
             servedAgents,
@@ -509,6 +517,7 @@ export async function startServer(syndicateName = 'syndicate.yaml', extensions =
     if (budgetLabel)
         emit('info', `[A2A]   budgets  ${budgetLabel}`);
     emit('info', `[A2A]   oauth    ${oauth.summary}`);
+    emit('info', `[A2A]   creds    ${oauth.credentialSummary}`);
     if (metricsToken)
         emit('info', `[A2A]   metrics  ${base}/metrics (bearer A2A_METRICS_TOKEN)`);
     emit('info', `[A2A]   health   ${base}/healthz  ${base}/readyz`);

package/dist/scripts/assistant_worker.d.ts

@@ -40,5 +40,7 @@
  *   --agent names a subagent of the syndicate, or its orchestrator.
  *   MELCHIZEDEK_TASKS_FILE moves the store (default: outputs/tasks.json),
  *   and must match the chat process's value. Run ONE worker per store.
+ *   MELCHIZEDEK_CHECKPOINT_MAX_BYTES caps a stored checkpoint (bytes of
+ *   JSON, default 5 MiB); a larger one is skipped and the previous kept.
  */
 export {};

package/dist/scripts/assistant_worker.js

@@ -40,6 +40,8 @@
  *   --agent names a subagent of the syndicate, or its orchestrator.
  *   MELCHIZEDEK_TASKS_FILE moves the store (default: outputs/tasks.json),
  *   and must match the chat process's value. Run ONE worker per store.
+ *   MELCHIZEDEK_CHECKPOINT_MAX_BYTES caps a stored checkpoint (bytes of
+ *   JSON, default 5 MiB); a larger one is skipped and the previous kept.
  */
 import { randomUUID } from 'node:crypto';
 import { loadEnv } from '../lib/loadEnv.js';
@@ -48,7 +50,7 @@ import { runDurableTurn } from '../lib/runtime/native/checkpoint.js';
 import { runtimeSetting } from '../lib/runtime/runtimeFlag.js';
 import { setLogLevel } from '../lib/runtime/logging.js';
 import { PROVIDERS, providerForModel, providerKeyPresent, } from '../lib/models/registry.js';
-import { applyInterrupted, getTaskBackend, setTaskBackend, taskStorePath } from '../lib/tools/taskTools.js';
+import { CHECKPOINT_MAX_BYTES_ENV, applyInterrupted, checkpointMaxBytesSetting, fileTaskBackendWith, 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';
@@ -90,10 +92,17 @@ if (!providerKeyPresent(provider)) {
 const log = (message) => console.log(`[worker] ${message}`);
 // The queue: the JSON file, or Postgres when DATABASE_URL is set, where any
 // number of workers may run (each claim is FOR UPDATE SKIP LOCKED).
+// A checkpoint above MELCHIZEDEK_CHECKPOINT_MAX_BYTES (bytes of JSON, default
+// 5 MiB) is not saved: the job keeps its previous one (ADR 0113).
+const rawCap = process.env[CHECKPOINT_MAX_BYTES_ENV];
+const checkpointMaxBytes = checkpointMaxBytesSetting(rawCap);
+if (rawCap?.trim() && Number(rawCap.trim()) !== checkpointMaxBytes) {
+    log(`${CHECKPOINT_MAX_BYTES_ENV} is not a positive whole number of bytes; using ${checkpointMaxBytes}`);
+}
+const taskQueue = { checkpointMaxBytes, log };
 const databaseUrl = process.env.DATABASE_URL?.trim();
-const pg = databaseUrl ? postgresStorage({ connectionString: databaseUrl, schema: dbSchema() }) : undefined;
-if (pg)
-    setTaskBackend(pg.taskQueue);
+const pg = databaseUrl ? postgresStorage({ connectionString: databaseUrl, schema: dbSchema(), taskQueue }) : undefined;
+setTaskBackend(pg ? pg.taskQueue : fileTaskBackendWith(taskQueue));
 const backend = getTaskBackend();
 /** A claimed job stays this worker's while it renews; the job timeout bounds a turn. */
 const lease = { workerId: `${hostname()}:${process.pid}:${randomUUID().slice(0, 8)}`, leaseMs: 60_000 };