melchizedek-agents 1.0.2 → 1.1.0

package/dist/scripts/assistant_worker.js

@@ -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)
@@ -34,12 +44,11 @@
 import { randomUUID } from 'node:crypto';
 import { loadEnv } from '../lib/loadEnv.js';
 import { loadSyndicate } from '../lib/loadSyndicate.js';
-import { runSyndicateTurn } from '../lib/runtime/syndicateTurn.js';
+import { runDurableTurn } from '../lib/runtime/native/checkpoint.js';
 import { runtimeSetting } from '../lib/runtime/runtimeFlag.js';
 import { setLogLevel } from '../lib/runtime/logging.js';
-import { InProcessSessionService } from '../lib/runtime/sessions.js';
 import { PROVIDERS, providerForModel, providerKeyPresent, } from '../lib/models/registry.js';
-import { getTaskBackend, setTaskBackend, taskStorePath } from '../lib/tools/taskTools.js';
+import { applyInterrupted, 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';
@@ -105,24 +114,43 @@ const workerConfig = !sub
         };
 /** The job in hand, so a signal can cancel it. */
 let current;
-// ── One job = one fresh single-turn session ─────────────────────────────────
+/** Set by SIGTERM: the job in hand goes back to the queue with its checkpoint. */
+let interrupted = false;
+/** The run lost its claim on the job (cancelled while it ran, or taken by another worker). */
+class ClaimLost extends Error {
+}
+/** SIGTERM stopped the run; the job is re-queued, not failed. */
+class Interrupted extends Error {
+}
+// ── One job = one durable single-turn run (ADR 0113) ────────────────────────
 async function runJob(job) {
-    current = new AbortController();
+    const controller = new AbortController();
+    current = controller;
     try {
-        const result = await runSyndicateTurn({
+        // A fresh in-process store per attempt, restored from the job's last
+        // checkpoint when an earlier attempt left one (ADR 0080, ADR 0113).
+        const result = await runDurableTurn({
             config: workerConfig,
             parts: [{ text: job.instruction ?? job.title }],
             appName: 'assistant-worker',
             userId: 'local-user',
-            sessionId: randomUUID(),
-            // A fresh in-process store per job, as the turn runner's signature
-            // names it (ADR 0080). The runtime follows MELCHIZEDEK_RUNTIME.
-            sessionService: new InProcessSessionService(),
+            runId: `${job.owner}:${job.id}`,
+            checkpoints: {
+                load: async () => ((await backend.loadCheckpoint?.(job)) ?? null),
+                save: async (checkpoint) => (backend.saveCheckpoint ? backend.saveCheckpoint(lease, job, checkpoint) : true),
+            },
+            onSaveError: (e) => log(`checkpoint not saved: ${e instanceof Error ? e.message : String(e)}`),
             compile: { log, onUnknownTool: (n) => log(`unknown tool '${n}' skipped`) },
-            signal: current.signal,
+            signal: controller.signal,
             deadlineMs: JOB_TIMEOUT_MS,
             events: { warn: (m) => log(`⚠ ${m}`) },
         });
+        if (result.resumedFromStep > 0)
+            log(`${job.id} resumed from step ${result.resumedFromStep}`);
+        if (result.lostClaim || controller.signal.reason instanceof ClaimLost)
+            throw new ClaimLost('the job was cancelled or claimed elsewhere');
+        if (interrupted)
+            throw new Interrupted('stopped by SIGTERM');
         if (result.status !== 'completed') {
             throw new Error(`${result.error?.code ?? 'ERROR'}: ${result.error?.message ?? ''}`.trim());
         }
@@ -142,10 +170,17 @@ async function drain() {
         const started = Date.now();
         const label = job.owner ? `${job.id} (${job.owner})` : job.id;
         log(`${label} started: ${job.title}`);
-        // Renew the lease while the job runs, so no other worker takes it back.
+        // Renew the lease while the job runs, so no other worker takes it back;
+        // a renewal that finds the claim gone (the job was cancelled) stops the run.
         const held = job;
         const heartbeat = setInterval(() => {
-            backend.renew(lease, held).catch((e) => log(`lease renewal failed: ${e instanceof Error ? e.message : e}`));
+            backend
+                .renew(lease, held)
+                .then((kept) => {
+                if (kept === false)
+                    current?.abort(new ClaimLost('claim lost'));
+            })
+                .catch((e) => log(`lease renewal failed: ${e instanceof Error ? e.message : e}`));
         }, Math.floor(lease.leaseMs / 3));
         try {
             const result = await runJob(job);
@@ -153,8 +188,22 @@ async function drain() {
             log(`${label} done in ${Math.round((Date.now() - started) / 1000)} s`);
         }
         catch (error) {
-            await backend.finish(job, { error: String(error?.message ?? error) });
-            log(`${label} failed: ${error?.message ?? error}`);
+            if (error instanceof ClaimLost) {
+                // Cancelled while it ran: the record already says so; nothing is written over it.
+                log(`${label} stopped: ${error.message}`);
+            }
+            else if (error instanceof Interrupted) {
+                // Back to the queue with its checkpoint, or failed after MAX_ATTEMPTS interruptions.
+                const outcome = await backend.mutate(job.owner, (store) => {
+                    const t = store.tasks.find((r) => r.id === held.id);
+                    return t && t.status === 'running' ? applyInterrupted(t) : 'left as is';
+                });
+                log(`${label} interrupted: ${outcome}`);
+            }
+            else {
+                await backend.finish(job, { error: String(error?.message ?? error) });
+                log(`${label} failed: ${error?.message ?? error}`);
+            }
         }
         finally {
             clearInterval(heartbeat);
@@ -183,12 +232,13 @@ process.on('SIGINT', () => {
     stopping = true;
     log('stopping after the current job (Ctrl-C again to quit now)');
 });
-// A container stop: cancel the job in hand (it is recorded as failed and the
-// store stays consistent), then exit.
+// A container stop: abort the step in flight and put the job back in the
+// queue with its checkpoint, so the next worker resumes it (ADR 0113).
 process.on('SIGTERM', () => {
     stopping = true;
-    log('SIGTERM — canceling the current job');
-    current?.abort();
+    interrupted = true;
+    log('SIGTERM — stopping the current job; it resumes from its last checkpoint');
+    current?.abort(new Interrupted('SIGTERM'));
 });
 while (!stopping) {
     await drain();

package/dist/scripts/doctor.d.ts

@@ -8,7 +8,10 @@
  * gateway stand-in, or local), which declared server-side tools it keeps or
  * drops, and one verdict per syndicate. Says first which runtime a turn runs
  * on (native; a leftover MELCHIZEDEK_RUNTIME=adk is a problem, since 1.0.0
- * removed that runtime). Closes with the env vars that would
+ * removed that runtime). Lists the tools that need an OAuth grant (an
+ * `auth: { oauth2 }` or `mcp_auth`, ADR 0112): each user's consent, or the
+ * server's own client credentials and whether their variables are set
+ * (names only). Closes with the env vars that would
  * unlock the most, where to get each, and the first command to try.
  *
  * Read-only: never edits .env, never sends a request, never prints a key

package/dist/scripts/doctor.js

@@ -8,7 +8,10 @@
  * gateway stand-in, or local), which declared server-side tools it keeps or
  * drops, and one verdict per syndicate. Says first which runtime a turn runs
  * on (native; a leftover MELCHIZEDEK_RUNTIME=adk is a problem, since 1.0.0
- * removed that runtime). Closes with the env vars that would
+ * removed that runtime). Lists the tools that need an OAuth grant (an
+ * `auth: { oauth2 }` or `mcp_auth`, ADR 0112): each user's consent, or the
+ * server's own client credentials and whether their variables are set
+ * (names only). Closes with the env vars that would
  * unlock the most, where to get each, and the first command to try.
  *
  * Read-only: never edits .env, never sends a request, never prints a key
@@ -88,5 +91,5 @@ if (json) {
 else {
     console.log(renderDoctor(result, { color: !noColor }));
 }
-if (check && (result.counts.blocked > 0 || result.runtime.problem))
+if (check && (result.counts.blocked > 0 || result.runtime.problem || result.oauth?.problems.length))
     process.exit(1);

package/dist/scripts/yaml_codemod.d.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * scripts/yaml_codemod.ts — the `melchizedek-codemod` bin and `npm run yaml:codemod`.
+ *
+ * Rewrites an agent's v1 spellings into the v2 keys (ADR 0115):
+ *
+ *   npm run yaml:codemod -- config/agents/my_syndicate.yaml   # rewrite in place
+ *   npm run yaml:codemod -- config/agents                     # every *.yaml below it
+ *   npm run yaml:codemod -- --check config/agents             # exit 1 if any file would change
+ *
+ * Per agent (the orchestrator and every inline subagent):
+ *
+ *   outputSchema                                    → output.schema
+ *   generateContentConfig.responseMimeType          → output.mime (application/json | text/plain)
+ *   generateContentConfig.temperature               → sampling.temperature
+ *   generateContentConfig.topP                      → sampling.top_p
+ *   generateContentConfig.maxOutputTokens           → sampling.max_output_tokens
+ *   generateContentConfig.stopSequences             → sampling.stop
+ *   generateContentConfig.thinkingConfig / reasoningEffort → reasoning:, ONLY
+ *     when the engine reads the same ReasoningSetting before and after for
+ *     the agent's model (reasoningOf over the old config equals reasoningOf
+ *     over what reasoningConfig makes of the new key).
+ *   generateContentConfig.thinkingConfig.includeThoughts: false → dropped (the default; read by nothing)
+ *
+ * Anything else stays under generateContentConfig with a note naming its key
+ * path (never its value); an emptied generateContentConfig is removed. An
+ * agent that already has the v2 key for a concept is left alone for that
+ * concept, with a note: the loader refuses an overlap.
+ *
+ * HOW: the file is parsed with the `yaml` package's Document API, which
+ * locates every key and value in the source. The edit splices whole lines:
+ * a moved key travels with its own lines (its leading and inline comments,
+ * its indentation and quoting); the comments of a key that is converted or
+ * dropped are kept as comment lines where the new key goes. Every line the
+ * codemod does not move is left byte for byte. The result is parsed again and
+ * must read back as the planned data, or the file is refused. Running it
+ * twice changes nothing the second time.
+ */
+export interface MigrateResult {
+    /** The migrated text; the input itself when nothing changed. */
+    text: string;
+    changed: boolean;
+    /** One line per key left in a v1 spelling, naming its key path (never a value). */
+    notes: string[];
+}
+/**
+ * Rewrites one YAML text's v1 agent keys into v2 (see the header). Throws on
+ * text that is not one YAML document, and on an edit that would not read
+ * back as planned (a bug, never a silent change).
+ */
+export declare function migrateYaml(text: string): MigrateResult;
+export declare function main(argv: string[]): number;