melchizedek-agents 1.0.2 → 1.1.0

package/dist/lib/tools/openapiTools.js

@@ -32,7 +32,10 @@
  *     OPENAPI_CREDENTIAL_ENVS, when the operator sets it, is the exact list
  *     of variables an `auth` may name. A credential is held by the tool,
  *     never written to session state, and its value never appears in an
- *     error the model reads.
+ *     error the model reads. An `auth: { oauth2 }` sends an OAuth token
+ *     instead, fetched per call: the run's user's own (authorization_code,
+ *     through `ctx.accessToken` and the consent pause) or the server's own
+ *     (client_credentials), lib/tools/oauthTools.ts, ADR 0112.
  *   - THE SSRF GUARD. Every server URL the tools will call must be http(s)
  *     and pass lib/net/addressGuard.ts: its literal rules at compile time
  *     (offline), and the full check with DNS before each call (a name can
@@ -62,6 +65,10 @@ import { extname, resolve } from 'node:path';
 import { MAX_RESULT_CHARS as TOOL_RESULT_CHARS, capResult } from './tool.js';
 import { callOperation, hostProblem } from './openapi/call.js';
 import { MAX_SPEC_BYTES, operationNamed, parseOpenApiSpec } from './openapi/parse.js';
+import { ToolCredentialError } from './auth.js';
+import { readCredentialEnv } from './credentialEnv.js';
+import { oauthTokenSource, tokenTransportProblem } from './oauthTools.js';
+export { credentialEnvProblem } from './credentialEnv.js';
 export { namesTool, toSnake } from './openapi/parse.js';
 /** Characters a single API result may carry into the conversation: every tool's shared limit (lib/tools/tool.ts). */
 export const MAX_RESULT_CHARS = TOOL_RESULT_CHARS;
@@ -70,45 +77,17 @@ export const MAX_RESULT_CHARS = TOOL_RESULT_CHARS;
  * operationId (lib/compile.ts). Its value is the operationId.
  */
 export const OPENAPI_TOOL = Symbol.for('melchizedek.openapiTool');
-/** Prefixes and names of variables the framework itself reads: never an API credential. */
-const FRAMEWORK_ENV_PREFIXES = [
-    'A2A_', 'SUPABASE_', 'DATABASE_', 'MCP_', 'MODEL_', 'MEMORY_', 'OTEL_', 'TELEMETRY_', 'MELCHIZEDEK_',
-    'GOOGLE_', 'GEMINI_', 'ANTHROPIC_', 'OPENAI_', 'AZURE_', 'AWS_', 'XAI_', 'MOONSHOT_', 'OLLAMA_', 'WIKI_',
-    'ALLOW_', 'OPENAPI_',
-];
-const FRAMEWORK_ENV_NAMES = new Set(['PUBLIC_URL', 'HOST', 'PORT', 'PATH', 'HOME', 'NODE_OPTIONS', 'WEB_EXTRACT_CHAR_LIMIT']);
-/**
- * Why an `auth` may not read this variable, or null. With
- * OPENAPI_CREDENTIAL_ENVS set, only the names it lists are allowed; without
- * it, anything but the framework's own variables is.
- */
-export function credentialEnvProblem(name, env = process.env) {
-    const allow = env.OPENAPI_CREDENTIAL_ENVS?.split(',').map((s) => s.trim()).filter(Boolean);
-    if (allow?.length) {
-        return allow.includes(name) ? null : `${name} is not in OPENAPI_CREDENTIAL_ENVS (${allow.join(', ')})`;
-    }
-    if (FRAMEWORK_ENV_NAMES.has(name) || FRAMEWORK_ENV_PREFIXES.some((p) => name.startsWith(p))) {
-        return `${name} is one of the framework's own settings and may not be sent to an API; give the API its own variable (or list it in OPENAPI_CREDENTIAL_ENVS)`;
-    }
-    return null;
-}
 /**
  * The credential an `auth` names, read from the environment once, at
  * compile. Throws (failing the compile) on a variable the allowlist refuses
  * or one that is not set; the message names the variable, never its value.
+ * An `oauth2` block is not read here: its token is fetched per call
+ * (oauthTokenSource, lib/tools/oauthTools.ts).
  */
 function credentialFor(auth, spec) {
     if (!auth)
         return undefined;
-    const read = (env) => {
-        const refused = credentialEnvProblem(env);
-        if (refused)
-            throw new Error(`openapi ${spec}: ${refused}`);
-        const value = process.env[env]?.trim();
-        if (!value)
-            throw new Error(`openapi ${spec}: ${env} is not set (auth reads it from the environment)`);
-        return value;
-    };
+    const read = (env) => readCredentialEnv(env, `openapi ${spec}`);
     if (auth.bearer_env)
         return { kind: 'bearer', token: read(auth.bearer_env) };
     if (auth.api_key)
@@ -152,13 +131,28 @@ function readSpec(specPath, source) {
         closeSync(fd);
     }
 }
-/** An own Tool that calls one operation (lib/tools/openapi/call.ts), its result cut to MAX_RESULT_CHARS. */
-function operationTool(op, credential) {
+/**
+ * An own Tool that calls one operation (lib/tools/openapi/call.ts), its
+ * result cut to MAX_RESULT_CHARS. With `oauth`, each call fetches its token
+ * first; a token that cannot be had is answered as `{ error }` naming the
+ * provider and what to do, never a value (and, for a user who has not
+ * granted it, the run's consent step has already asked).
+ */
+function operationTool(op, credential, oauth) {
     const tool = {
         name: op.name,
         declaration: () => op.declaration,
         async execute(args, ctx) {
-            return capResult(await callOperation(op, args ?? {}, { credential, signal: ctx?.signal }));
+            let sent = credential;
+            if (oauth) {
+                try {
+                    sent = { kind: 'bearer', token: await oauth(ctx, op.baseUrl) };
+                }
+                catch (error) {
+                    return { error: error instanceof ToolCredentialError ? error.message : 'The authorization for this API could not be obtained.' };
+                }
+            }
+            return capResult(await callOperation(op, args ?? {}, { credential: sent, signal: ctx?.signal }));
         },
     };
     Object.defineProperty(tool, OPENAPI_TOOL, { value: op.operationId });
@@ -199,7 +193,17 @@ export async function buildOpenApiOwnTools(entry, baseDir = process.cwd()) {
         if (problem)
             throw new Error(`openapi ${entry.spec}: ${problem}`);
     }
-    return chosen.map((o) => operationTool(o, credential));
+    let oauth;
+    if (entry.auth?.oauth2 && chosen.length) {
+        // Every server the token goes to takes it over https (or loopback http).
+        for (const server of new Set(chosen.map((o) => o.baseUrl))) {
+            const problem = tokenTransportProblem(server);
+            if (problem)
+                throw new Error(`openapi ${entry.spec}: ${problem}`);
+        }
+        oauth = oauthTokenSource(entry.auth.oauth2, `openapi ${entry.spec}`, [...new Set(chosen.map((o) => o.baseUrl))], { allowPrivate: process.env.ALLOW_PRIVATE_OPENAPI === 'true' });
+    }
+    return chosen.map((o) => operationTool(o, credential, oauth));
 }
 /**
  * The tools one `openapi:` entry gives an agent: buildOpenApiOwnTools' own

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

@@ -10,7 +10,9 @@
  *   a list of records with a status — so both live in one store:
  *
  *     kind: todo        the user's own tasks. open → done | cancelled.
- *     kind: background  a job for the worker. queued → running → done | failed.
+ *     kind: background  a job for the worker. queued → running → done | failed,
+ *                       and cancelled from queued or running (a running job's
+ *                       worker sees it at its next renewal and stops).
  *
  *   The tools only WRITE the queue. They never run a job: a tool that
  *   orchestrates agents is exactly what the tool-contract doctrine refuses
@@ -28,11 +30,15 @@
  *     gitignored). Every operation re-reads the file, so the chat process
  *     and the worker see each other's writes. It is SINGLE-USER: every
  *     caller shares one list. Run ONE worker: the claim is a
- *     read-modify-write, not a lock.
+ *     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.
  *   - 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
- *     with FOR UPDATE SKIP LOCKED under a renewed lease (ADR 0021).
+ *     with FOR UPDATE SKIP LOCKED under a renewed lease (ADR 0021). The
+ *     checkpoint is a column beside the record (migration 0014).
  *
  * SECURITY:
  *   On the file store every caller of a shared endpoint shares one list: do
@@ -95,8 +101,13 @@ export interface TaskBackend {
     mutate<T>(owner: string, change: (store: TaskStore) => T): Promise<T>;
     /** The oldest queued background job of any owner, now running and leased. */
     claimNext(worker: WorkerLease): Promise<OwnedTask | null>;
-    /** Keeps a claimed job leased while it runs. */
-    renew(worker: WorkerLease, job: OwnedTask): Promise<void>;
+    /**
+     * Keeps a claimed job leased while it runs. Resolves false when the claim
+     * is gone (the job left `running`, for instance cancelled with
+     * task_update, or another worker holds it): the worker must stop the run.
+     * A backend that resolves void makes no such claim.
+     */
+    renew(worker: WorkerLease, job: OwnedTask): Promise<void | boolean>;
     /** Records a job's outcome; a record no longer running is left alone. */
     finish(job: OwnedTask, outcome: JobOutcome): Promise<void>;
     /** Jobs whose worker died: queued again, or failed after MAX_ATTEMPTS. */
@@ -104,6 +115,19 @@ export interface TaskBackend {
         requeued: string[];
         failed: string[];
     }>;
+    /**
+     * Durable runs (ADR 0113): stores the run's latest step checkpoint beside
+     * the job. Resolves false when the job is no longer this worker's running
+     * job (cancelled, finished, or re-leased): the run must stop.
+     *
+     * A checkpoint lives only while its job is `running` or `queued` (a job
+     * re-queued after an interruption keeps it, so the next claim resumes);
+     * any other status drops it, and so does a pruned or deleted record. It is
+     * kept beside the record, never in it, so task_get never shows it.
+     */
+    saveCheckpoint?(worker: WorkerLease, job: OwnedTask, checkpoint: object): Promise<boolean>;
+    /** The checkpoint a re-queued job left, or null. */
+    loadCheckpoint?(job: OwnedTask): Promise<object | null>;
 }
 /** Records kept at most; finished ones are pruned oldest-first to make room. */
 export declare const MAX_TASKS = 500;
@@ -112,6 +136,7 @@ export declare const MAX_RESULT_CHARS = 20000;
 /** A job interrupted this many times is marked failed instead of re-queued. */
 export declare const MAX_ATTEMPTS = 2;
 export declare function taskStorePath(): string;
+export declare function taskCheckpointPath(storePath?: string): string;
 /**
  * Called once at worker start: a record left `running` means a worker died
  * mid-job. It goes back to the queue, or fails once it has been tried

package/dist/lib/tools/taskTools.js

@@ -10,7 +10,9 @@
  *   a list of records with a status — so both live in one store:
  *
  *     kind: todo        the user's own tasks. open → done | cancelled.
- *     kind: background  a job for the worker. queued → running → done | failed.
+ *     kind: background  a job for the worker. queued → running → done | failed,
+ *                       and cancelled from queued or running (a running job's
+ *                       worker sees it at its next renewal and stops).
  *
  *   The tools only WRITE the queue. They never run a job: a tool that
  *   orchestrates agents is exactly what the tool-contract doctrine refuses
@@ -28,11 +30,15 @@
  *     gitignored). Every operation re-reads the file, so the chat process
  *     and the worker see each other's writes. It is SINGLE-USER: every
  *     caller shares one list. Run ONE worker: the claim is a
- *     read-modify-write, not a lock.
+ *     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.
  *   - 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
- *     with FOR UPDATE SKIP LOCKED under a renewed lease (ADR 0021).
+ *     with FOR UPDATE SKIP LOCKED under a renewed lease (ADR 0021). The
+ *     checkpoint is a column beside the record (migration 0014).
  *
  * SECURITY:
  *   On the file store every caller of a shared endpoint shares one list: do
@@ -73,18 +79,58 @@ function readStore(path = taskStorePath()) {
     }
     return { version: 1, next_id: parsed.next_id, tasks: parsed.tasks };
 }
-function writeStore(store, path = taskStorePath()) {
+/** Atomic JSON write: temp file + rename, so a reader never sees half a file. */
+function writeJson(value, path) {
     mkdirSync(dirname(path), { recursive: true });
     const tmp = `${path}.${process.pid}.tmp`;
-    writeFileSync(tmp, `${JSON.stringify(store, null, 2)}\n`);
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
     renameSync(tmp, path);
 }
+function writeStore(store, path = taskStorePath()) {
+    writeJson(store, path);
+}
+/** Statuses a job's checkpoint survives in. */
+const CHECKPOINTED = ['running', 'queued'];
+export function taskCheckpointPath(storePath = taskStorePath()) {
+    return `${storePath}.checkpoints.json`;
+}
+/** The sidecar, or empty when missing or unreadable (a checkpoint is an optimisation, never the record). */
+function readCheckpoints(storePath) {
+    const path = taskCheckpointPath(storePath);
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+const keepsCheckpoint = (t) => !!t && t.kind === 'background' && CHECKPOINTED.includes(t.status);
+/** Drops sidecar entries whose job is gone or no longer running/queued. */
+function pruneCheckpoints(store, storePath) {
+    if (!existsSync(taskCheckpointPath(storePath)))
+        return;
+    const entries = readCheckpoints(storePath);
+    const byId = new Map(store.tasks.map((t) => [t.id, t]));
+    let changed = false;
+    for (const id of Object.keys(entries)) {
+        if (!keepsCheckpoint(byId.get(id))) {
+            delete entries[id];
+            changed = true;
+        }
+    }
+    if (changed)
+        writeJson(entries, taskCheckpointPath(storePath));
+}
 /** Read, change, write — one synchronous step, so no await splits it. */
 function mutate(change) {
     const path = taskStorePath();
     const store = readStore(path);
     const out = change(store);
     writeStore(store, path);
+    pruneCheckpoints(store, path);
     return out;
 }
 const now = () => new Date().toISOString();
@@ -212,9 +258,26 @@ export const fileTaskBackend = {
         const job = claimNextJob();
         return job ? { ...job, owner: '' } : null;
     },
-    renew: async () => { },
+    // 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;
+    },
 };
 let activeBackend = fileTaskBackend;
 /** Plugs in where tasks live (postgresStorage().taskQueue); default the JSON file. */
@@ -318,7 +381,8 @@ export const taskGetContract = defineTool({
 export const taskUpdateContract = defineTool({
     name: 'task_update',
     description: 'Change a task: mark it done, cancel it, reopen it, or edit its title, notes, or due date. ' +
-        'For a background job, "cancelled" withdraws it before it runs and "queued" retries a failed or cancelled job. ' +
+        'For a background job, "cancelled" withdraws it before it runs, or stops it if it is running now ' +
+        '(the worker stops at its next step and keeps no result); "queued" retries a failed or cancelled job. ' +
         'Call task_list first if you do not have the id.',
     schema: z.object({
         id: taskId,
@@ -340,9 +404,9 @@ export const taskUpdateContract = defineTool({
                 return `Error: a ${task.kind} task cannot be set to "${status}". Allowed: ${allowed[task.kind].join(', ')}.`;
             }
             if (task.kind === 'background') {
-                if (task.status === 'running') {
-                    return `Error: ${id} is running now. Wait for it to finish, then read it with task_get.`;
-                }
+                // Cancelling a running job is allowed: its worker's next lease
+                // renewal or checkpoint sees the record left `running` and stops
+                // the run, and the worker's outcome is then left alone (applyFinish).
                 if (status === 'queued' && !['failed', 'cancelled'].includes(task.status)) {
                     return `Error: only a failed or cancelled job can be queued again; ${id} is ${task.status}.`;
                 }

package/dist/lib/workflow.d.ts

@@ -41,16 +41,20 @@
  * A delegated `yaml_reference` to a workflow syndicate is the whole graph,
  * walked under the subagent entry's name and description on a child
  * session (lib/compileNative.ts workflowSubagentOf); its answer is the
- * graph's last event's text. A nested workflow with an
- * `ask_user` node is refused by name (lib/compile.ts compileWorkflowSpec): a
- * pause inside a tool call cannot reach the caller (ADR 0028).
+ * graph's last event's text. A walk that pauses (an `ask_user` node, a
+ * gated agent node) leaves the call open, and the turn ends input-required
+ * with the agent path down to the node; the answer walks the graph again
+ * (lib/runtime/native/delegate.ts resumeWorkflowSubagent, ADR 0111).
  *
  * ── 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).
+ * (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).
  *
  * ── Approval gates (ADR 0098, ADR 0106) ──────────────────────────────────
  * A tool in a node agent's `require_approval`, and a skill script

package/dist/lib/workflow.js

@@ -41,16 +41,20 @@
  * A delegated `yaml_reference` to a workflow syndicate is the whole graph,
  * walked under the subagent entry's name and description on a child
  * session (lib/compileNative.ts workflowSubagentOf); its answer is the
- * graph's last event's text. A nested workflow with an
- * `ask_user` node is refused by name (lib/compile.ts compileWorkflowSpec): a
- * pause inside a tool call cannot reach the caller (ADR 0028).
+ * graph's last event's text. A walk that pauses (an `ask_user` node, a
+ * gated agent node) leaves the call open, and the turn ends input-required
+ * with the agent path down to the node; the answer walks the graph again
+ * (lib/runtime/native/delegate.ts resumeWorkflowSubagent, ADR 0111).
  *
  * ── 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).
+ * (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).
  *
  * ── Approval gates (ADR 0098, ADR 0106) ──────────────────────────────────
  * A tool in a node agent's `require_approval`, and a skill script

package/dist/lib/workflowConfig.d.ts

@@ -80,6 +80,12 @@ export interface PendingInput {
     payload?: unknown;
     /** JSON Schema a structured answer must satisfy, when the node declared one. */
     schema?: unknown;
+    /**
+     * For a question asked inside a delegated subagent (ADR 0110): the agents
+     * from the turn's own agent down to the one that asked, `node` last.
+     * Absent when the turn's own agent (or a workflow node) asked.
+     */
+    path?: string[];
 }
 /** ADK's function-call name for a workflow input request. */
 export declare const INPUT_REQUEST = "adk_request_input";

package/dist/scripts/a2a_server.d.ts

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
 import type { Server } from 'node:http';
 import { createA2AApp } from '../lib/a2a/app.ts';
+import type { SyndicateYamlConfig } from '../lib/loadSyndicate.ts';
+import type { OAuthServerSetup } from '../lib/a2a/oauthSetup.ts';
+import type { AuditSink } from '../lib/observability/audit.ts';
+import type { CredentialRows } from '../lib/tools/credentialStore.ts';
 export { describeTurnError } from '../lib/a2a/executor.ts';
 /**
  * What a deployment adds on top of the environment-driven server: its own
@@ -15,4 +19,36 @@ export interface ServerExtensions {
     /** Any other createA2AApp option; wins over what the environment sets. */
     options?: Partial<Parameters<typeof createA2AApp>[0]>;
 }
+/**
+ * The syndicates this server serves from FILES: the default (unless it is a
+ * registry row), each served id that is not a registry id, and, when every
+ * file is served (A2A_SERVED_AGENTS unset or *), every syndicate at the
+ * agents directory's root. The consent step's OAuth clients come from these
+ * only (ADR 0114): a registry row may name a provider they declare, never
+ * define one. A file that does not load is skipped with a warning (its route
+ * fails on its own).
+ */
+export declare function servedFileSyndicates(syndicateName: string, servedAgents: string[] | undefined, registryAgents: string[] | undefined, warn?: (m: string) => void): SyndicateYamlConfig[];
+/** The server's tool credentials, from the environment: what createA2AApp takes, and what to print. */
+export interface ServerOAuth extends OAuthServerSetup {
+    toolCredentials?: OAuthServerSetup['toolCredentials'] & {
+        requireCallerIdentity?: boolean;
+    };
+}
+/**
+ * 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
+ * variables only, on a configuration that is unsafe or cannot work.
+ */
+export declare function serverOAuth(options: {
+    syndicateName: string;
+    servedAgents?: string[];
+    registryAgents?: string[];
+    rows?: CredentialRows;
+    audit?: AuditSink;
+    env?: NodeJS.ProcessEnv;
+    fetch?: typeof fetch;
+    warn?: (m: string) => void;
+}): ServerOAuth;
 export declare function startServer(syndicateName?: string, extensions?: ServerExtensions): Promise<Server>;

package/dist/scripts/a2a_server.js

@@ -75,9 +75,24 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  *                             running turn (default 20). Behind a session-mode
  *                             pooler (Supabase :5432) keep the two sums under its
  *                             client limit, per instance.
+ *   MELCHIZEDEK_CREDENTIAL_KEY  32 random bytes (base64 or hex) that seal each user's
+ *                             third-party OAuth tokens (ADR 0072). Unset = no tool
+ *                             credentials. Rows live in Postgres with DATABASE_URL,
+ *                             else in process memory
+ *   OAUTH_REDIRECT_URI        the consent callback, exactly as registered at every
+ *                             provider (https://agents.example.com/oauth/callback);
+ *                             mounts the callback and lets a run ask a user to
+ *                             connect (ADR 0085). Needs MELCHIZEDEK_CREDENTIAL_KEY
+ *   OAUTH_CALLBACK_IDENTITY   required (default): the callback's browser must carry the
+ *                             flow's user's identity (A2A_AUTH=header behind a gateway);
+ *                             state: the single-use state nonce alone binds it (ADR 0114)
+ *   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)
  */
 import { randomBytes } from 'node:crypto';
-import { realpathSync, writeFileSync } from 'node:fs';
+import { readdirSync, realpathSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createA2AApp } from '../lib/a2a/app.js';
 import { callerTokens, firstOf, hashCallerToken, jwtIdentity, parseCallers, sharedSecret, trustedHeader, } from '../lib/a2a/identity.js';
@@ -90,6 +105,10 @@ 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';
+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';
 // 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. */
@@ -132,6 +151,87 @@ function fatal(message) {
     emit('error', `[A2A] ✗ FATAL: ${message}`);
     process.exit(1);
 }
+/**
+ * The syndicates this server serves from FILES: the default (unless it is a
+ * registry row), each served id that is not a registry id, and, when every
+ * file is served (A2A_SERVED_AGENTS unset or *), every syndicate at the
+ * agents directory's root. The consent step's OAuth clients come from these
+ * only (ADR 0114): a registry row may name a provider they declare, never
+ * define one. A file that does not load is skipped with a warning (its route
+ * fails on its own).
+ */
+export function servedFileSyndicates(syndicateName, servedAgents, registryAgents, warn = () => { }) {
+    const registry = new Set(registryAgents ?? []);
+    const files = new Set();
+    const add = (id) => {
+        if (id.startsWith('registry:') || registry.has(id))
+            return;
+        files.add(id.endsWith('.yaml') || id.endsWith('.yml') ? id : `${id}.yaml`);
+    };
+    add(syndicateName);
+    if (servedAgents) {
+        for (const id of servedAgents)
+            add(id);
+    }
+    else {
+        const agentsDir = path.resolve(process.env.MELCHIZEDEK_AGENTS_DIR ?? path.join(process.cwd(), 'config', 'agents'));
+        let names = [];
+        try {
+            names = readdirSync(agentsDir);
+        }
+        catch {
+            names = [];
+        }
+        for (const f of names.sort())
+            if ((f.endsWith('.yaml') || f.endsWith('.yml')) && f !== 'syndicateSchema.yaml')
+                files.add(f);
+    }
+    const out = [];
+    for (const file of files) {
+        try {
+            out.push(loadSyndicate(file, { shippedFallback: servedAgents !== undefined || file === syndicateName }));
+        }
+        catch (err) {
+            if (err?.code !== 'ENOENT')
+                warn(`OAuth setup skipped ${file}: ${err instanceof Error ? err.message.split('\n')[0] : String(err)}`);
+        }
+    }
+    return out;
+}
+/**
+ * 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
+ * variables only, on a configuration that is unsafe or cannot work.
+ */
+export function serverOAuth(options) {
+    const env = options.env ?? process.env;
+    const identity = callbackIdentity(env);
+    const setup = oauthServerSetup({
+        configs: servedFileSyndicates(options.syndicateName, options.servedAgents, options.registryAgents, options.warn),
+        load: (ref) => loadSyndicate(ref),
+        env,
+        ...(options.rows ? { rows: options.rows } : {}),
+        ...(options.audit ? { audit: options.audit } : {}),
+        allowPrivate: env.ALLOW_PRIVATE_OPENAPI === 'true' || env.ALLOW_PRIVATE_MCP === 'true',
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+    });
+    if (!setup.toolCredentials?.consent)
+        return setup;
+    const warnings = [...setup.warnings];
+    const refused = callbackIdentityProblem(env);
+    if (identity === 'state') {
+        warnings.push('OAUTH_CALLBACK_IDENTITY=state: the single-use state alone binds a consent callback to its user, so a forwarded authorization link can connect the forwarder\'s account to the user who was asked.');
+    }
+    else if (refused) {
+        warnings.push(`${refused.charAt(0).toUpperCase()}${refused.slice(1)}.`);
+    }
+    return {
+        ...setup,
+        warnings,
+        toolCredentials: { ...setup.toolCredentials, requireCallerIdentity: identity === 'required' },
+    };
+}
 export async function startServer(syndicateName = 'syndicate.yaml', extensions = {}) {
     loadEnv(import.meta.url);
     // Conversation content stays out of stdout unless the operator opts in:
@@ -319,6 +419,25 @@ export async function startServer(syndicateName = 'syndicate.yaml', extensions =
     if (metricsToken && (isPlaceholderValue(metricsToken) || metricsToken.length < 24)) {
         fatal('A2A_METRICS_TOKEN must be a long random value (openssl rand -hex 32).');
     }
+    // ── Tool credentials and the OAuth consent step (ADR 0072, 0085, 0114) ────
+    let oauth;
+    try {
+        // An extension's allowlist wins over the environment's here too, as createA2AApp applies it.
+        if (extensions.options?.oauthHosts)
+            setOAuthHosts(extensions.options.oauthHosts);
+        oauth = serverOAuth({
+            syndicateName,
+            servedAgents,
+            registryAgents,
+            ...(pgStorage ? { rows: postgresCredentialRows(pgStorage.pool), audit: pgStorage.audit } : {}),
+            warn: (m) => emit('warn', `[A2A] ⚠ ${m}`),
+        });
+    }
+    catch (err) {
+        fatal(err instanceof Error ? err.message : String(err));
+    }
+    for (const w of oauth.warnings)
+        emit('warn', `[A2A] ⚠ ${w}`);
     let built;
     try {
         built = await createA2AApp({
@@ -345,6 +464,7 @@ export async function startServer(syndicateName = 'syndicate.yaml', extensions =
             keyMode,
             ...(pgStorage ? { storage: pgStorage } : {}),
             ...(policy ? { policy } : {}),
+            ...(oauth.toolCredentials ? { toolCredentials: oauth.toolCredentials } : {}),
             metricsToken,
             log: (m) => emit('info', `[A2A] ${m}`),
             warn: (m) => emit('warn', `[A2A] ⚠ ${m}`),
@@ -388,6 +508,7 @@ export async function startServer(syndicateName = 'syndicate.yaml', extensions =
     }
     if (budgetLabel)
         emit('info', `[A2A]   budgets  ${budgetLabel}`);
+    emit('info', `[A2A]   oauth    ${oauth.summary}`);
     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

@@ -21,6 +21,16 @@
  *   instead of abandoning it while it keeps spending. Any syndicate and any
  *   subagent in it can serve as the worker.
  *
+ *   A run is durable (ADR 0113): runDurableTurn (lib/runtime/native/
+ *   checkpoint.ts) checkpoints the run's sessions at every step boundary
+ *   beside the job (TaskBackend.saveCheckpoint), and a job claimed again
+ *   after its worker stopped resumes from its last checkpoint instead of
+ *   starting over. SIGTERM aborts the step in flight and puts the job back
+ *   in the queue with its checkpoint; the next worker finishes it. A job
+ *   cancelled while it runs (task_update) loses its claim: the next lease
+ *   renewal or checkpoint save sees it, and the run is aborted without
+ *   writing a result over the cancellation.
+ *
  * Usage:
  *   npm run assistant:worker                      poll every 30 s until Ctrl-C
  *   npm run assistant:worker -- --once            drain the queue, then exit (cron)