melchizedek-agents 1.6.0 → 1.8.0

package/dist/lib/loadSyndicate.js

@@ -5,6 +5,7 @@ import { createClient } from '@supabase/supabase-js';
 import { hasSupabaseCredentials } from './persistence/supabaseProvider.js';
 import { validateSyndicateConfig } from './syndicateSchema.js';
 import { v1SpellingsOf } from './agentDialect.js';
+import { resolveAgentsDir } from './project.js';
 // ── Variable Injection (private) ──────────────────────────
 const TOKEN_RE = /\{\{(\w+)\}\}/g;
 const FULL_TOKEN_RE = /^\{\{(\w+)\}\}$/;
@@ -87,7 +88,12 @@ function resolveAndValidate(raw, label, options) {
         ...yamlVars,
         ...bindings,
     };
-    const interpolated = isPlainObject(raw) ? interpolateDeep(raw, merged) : raw;
+    // A script's source is code, not a template: `{{` is JavaScript there, and the script reads `variables` itself (ADR 0137 item 5).
+    const scriptSource = isPlainObject(raw) && isPlainObject(raw.script) && typeof raw.script.source === 'string' ? raw.script.source : undefined;
+    let interpolated = isPlainObject(raw) ? interpolateDeep(raw, merged) : raw;
+    if (scriptSource !== undefined && isPlainObject(interpolated) && isPlainObject(interpolated.script)) {
+        interpolated = { ...interpolated, script: { ...interpolated.script, source: scriptSource } };
+    }
     warnV1Spellings(interpolated, label, options.onWarning);
     const unresolved = findUnresolvedTokens(interpolated);
     if (unresolved.length > 0) {
@@ -96,6 +102,11 @@ function resolveAndValidate(raw, label, options) {
     const valid = validateSyndicateConfig(bundle !== undefined && isPlainObject(interpolated) ? { ...interpolated, bundled_references: bundle } : interpolated, label);
     const { variables: _stripped, ...clean } = valid;
     let config = clean;
+    // The script reads the bound variables (ADR 0137 item 6): the YAML's, then the caller's bindings, as {{token}} resolves them.
+    if (config.script) {
+        const yamlBound = isPlainObject(interpolated) && isPlainObject(interpolated.variables) ? interpolated.variables : {};
+        config = { ...config, script: { ...config.script, variables: { ...defaultBindings(), ...yamlBound, ...bindings } } };
+    }
     if (overrides) {
         config = applyOverrides(config, overrides);
     }
@@ -280,10 +291,8 @@ export function readSyndicateFile(filename, options = {}) {
     // Security: confine reads to the agents root. `filename` can originate from
     // a network-controlled path segment (see a2a_server dynamic routes), so we
     // must reject any value that resolves outside that root (e.g. "../../.env").
-    // The root itself is trusted configuration: option → env → cwd default.
-    const agentsDir = path.resolve(options.agentsDir ??
-        process.env.MELCHIZEDEK_AGENTS_DIR ??
-        path.join(process.cwd(), 'config', 'agents'));
+    // The root itself is trusted configuration: option → env → project manifest → cwd default (lib/project.ts).
+    const agentsDir = resolveAgentsDir(options.agentsDir);
     let filePath = path.resolve(agentsDir, filename);
     if (filePath !== agentsDir && !filePath.startsWith(agentsDir + path.sep)) {
         throw new Error(`Invalid syndicate path: '${filename}' resolves outside the agents directory`);

package/dist/lib/observability/supabaseSpanExporter.js

@@ -81,7 +81,8 @@ export function payloadDecision(policy, traceId, facts) {
 }
 // ── Span → row mapping (pure; tested offline) ───────────────────────────────
 const ROOT_PREFIX = 'Syndicate Execution: ';
-const EXPORTED_SPAN_NAMES = /^(llm\.request$|Syndicate Execution: )/;
+// A script's own spans (ADR 0137 item 16) carry its run, its calls' kinds, names, sequence and status, never an argument or a result.
+const EXPORTED_SPAN_NAMES = /^(llm\.request$|Syndicate Execution: |script\.(invoke|call) )/;
 function attrsOf(span) {
     return span.attributes;
 }

package/dist/lib/observability/tracer.d.ts

@@ -1,4 +1,4 @@
-import type { Span, SpanContext, SpanOptions } from '@opentelemetry/api';
+import type { Context, Span, SpanContext, SpanOptions } from '@opentelemetry/api';
 import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
 import type { LlmResponse } from '../models/genaiMapping.ts';
 import type { TurnEvent as Event } from '../runtime/events.ts';
@@ -67,7 +67,7 @@ export declare function initializeTracing(): void;
  * the engine opens inside a turn goes through here or checks turnUntraced
  * itself.
  */
-export declare function startEngineSpan(tracerName: string, name: string, options?: SpanOptions): Span;
+export declare function startEngineSpan(tracerName: string, name: string, options?: SpanOptions, parent?: Context): Span;
 export interface TraceMetadata {
     syndicateName: string;
     bindings?: Record<string, any>;

package/dist/lib/observability/tracer.js

@@ -345,11 +345,11 @@ function nonRecordingSpan() {
  * the engine opens inside a turn goes through here or checks turnUntraced
  * itself.
  */
-export function startEngineSpan(tracerName, name, options) {
+export function startEngineSpan(tracerName, name, options, parent) {
     if (turnUntraced())
         return nonRecordingSpan();
     initializeTracing();
-    return trace.getTracer(tracerName).startSpan(name, options);
+    return trace.getTracer(tracerName).startSpan(name, options, parent);
 }
 /** Turn identity by trace id, so llm.request children can carry it too. */
 const turnContexts = new Map();

package/dist/lib/project.d.ts

@@ -0,0 +1,116 @@
+/**
+ * lib/project.ts — the project manifest, `melchizedek.json` (ADR 0138).
+ *
+ * A project is a folder, usually a git repository, with a `melchizedek.json`
+ * at its root. The manifest records what the engine cannot infer from the
+ * files: which folder holds the syndicates, which engine version the project
+ * is written for, and how each file ships. It holds names, never values: an
+ * `env` entry is a variable name, and no field may carry a secret.
+ *
+ * `findProject()` walks up from a directory to the nearest manifest and stops
+ * at the repository root (the first directory holding `.git`) or the home
+ * directory, so a manifest outside the repository never steers it.
+ * `resolveAgentsDir()` is the one agents-directory chain every loader and bin
+ * uses: explicit option → MELCHIZEDEK_AGENTS_DIR → the manifest's `agents` →
+ * <cwd>/config/agents. A deployed server sets the variable, so the manifest
+ * only changes what a bare command run inside a project finds.
+ *
+ * Imports only node built-ins, zod and lib/paths.ts.
+ */
+import { z } from 'zod';
+export declare const PROJECT_MANIFEST = "melchizedek.json";
+export declare const MANIFEST_VERSION = 1;
+export declare const projectManifestSchema: z.ZodObject<{
+    manifest: z.ZodNumber;
+    engine: z.ZodString;
+    agents: z.ZodString;
+    ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tests: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    syndicates: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        deliverable: z.ZodOptional<z.ZodEnum<{
+            library: "library";
+            mcp: "mcp";
+            service: "service";
+        }>>;
+        publish: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodLiteral<"registry">;
+            id: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>>;
+    registry: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"supabase">;
+        url_env: z.ZodOptional<z.ZodString>;
+        restart: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    production: z.ZodOptional<z.ZodObject<{
+        ledger: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodLiteral<"postgres">;
+            url_env: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+    tools: z.ZodOptional<z.ZodObject<{
+        remote: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            mcp_env: z.ZodString;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type ProjectManifest = z.infer<typeof projectManifestSchema>;
+export interface Project {
+    /** The folder holding `melchizedek.json`. */
+    root: string;
+    /** Absolute path of the manifest. */
+    file: string;
+    manifest: ProjectManifest;
+    /** `agents`, resolved under the root. */
+    agentsDir: string;
+    /** `tests`, resolved under the root (default `tests/agents`). */
+    testsDir: string;
+}
+/** Thrown for a manifest that does not parse or validate; names the file and fields, never a value. */
+export declare class ProjectManifestError extends Error {
+    readonly file: string;
+    readonly issues: string[];
+    constructor(file: string, issues: string[]);
+}
+/**
+ * The nearest folder at or above `from` holding a manifest, without crossing
+ * the repository root or the home directory. Undefined when there is none.
+ */
+export declare function findProjectRoot(from?: string): string | undefined;
+/** Parse and validate a manifest's text. Throws `ProjectManifestError`. */
+export declare function parseProjectManifest(text: string, file?: string): ProjectManifest;
+/** Load the project rooted at `root` (the folder holding the manifest). Throws `ProjectManifestError`. */
+export declare function loadProject(root: string): Project;
+/** The project at or above `from`, or undefined when there is none. Throws on a broken manifest. */
+export declare function findProject(from?: string): Project | undefined;
+/** Forget cached manifest lookups (tests, and an embedder that edits the manifest in-process). */
+export declare function clearProjectCache(): void;
+/**
+ * The agents directory: `explicit` → MELCHIZEDEK_AGENTS_DIR → the nearest
+ * manifest's `agents` → <cwd>/config/agents. Always absolute.
+ */
+export declare function resolveAgentsDir(explicit?: string, env?: NodeJS.ProcessEnv): string;
+/** True when `relFromRoot` (a `/`-separated path relative to the project root) matches an `ignore` pattern. */
+export declare function isIgnored(project: Pick<Project, 'manifest'>, relFromRoot: string): boolean;
+/** The syndicate files directly in the agents folder, as names relative to it, minus `ignore`. */
+export declare function listProjectSyndicates(project: Project): string[];
+/** The installed engine's package version (no commit suffix). */
+export declare function enginePackageVersion(): string;
+export interface ProjectCheck {
+    root: string;
+    agentsDir: string;
+    /** The manifest's engine pin, and the engine running now. */
+    engine: {
+        pinned: string;
+        running: string;
+        matches: boolean;
+    };
+    syndicates: string[];
+    /** Stop `melchizedek-doctor --check`. */
+    problems: string[];
+    /** Shown, never fatal. */
+    warnings: string[];
+}
+/** What is wrong with a project: engine pin, missing folders, stale ignores, unset env names. Never reads a value. */
+export declare function checkProject(project: Project, running?: string, env?: NodeJS.ProcessEnv): ProjectCheck;

package/dist/lib/project.js

@@ -0,0 +1,274 @@
+/**
+ * lib/project.ts — the project manifest, `melchizedek.json` (ADR 0138).
+ *
+ * A project is a folder, usually a git repository, with a `melchizedek.json`
+ * at its root. The manifest records what the engine cannot infer from the
+ * files: which folder holds the syndicates, which engine version the project
+ * is written for, and how each file ships. It holds names, never values: an
+ * `env` entry is a variable name, and no field may carry a secret.
+ *
+ * `findProject()` walks up from a directory to the nearest manifest and stops
+ * at the repository root (the first directory holding `.git`) or the home
+ * directory, so a manifest outside the repository never steers it.
+ * `resolveAgentsDir()` is the one agents-directory chain every loader and bin
+ * uses: explicit option → MELCHIZEDEK_AGENTS_DIR → the manifest's `agents` →
+ * <cwd>/config/agents. A deployed server sets the variable, so the manifest
+ * only changes what a bare command run inside a project finds.
+ *
+ * Imports only node built-ins, zod and lib/paths.ts.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { z } from 'zod';
+import { enginePackageRoot } from './paths.js';
+export const PROJECT_MANIFEST = 'melchizedek.json';
+export const MANIFEST_VERSION = 1;
+/** A path relative to the project root: no absolute paths, no `..` segments. */
+const relPath = z
+    .string()
+    .min(1)
+    .refine((p) => !/^([a-zA-Z]:)?[\\/]/.test(p) && !p.split(/[\\/]/).includes('..'), 'must be relative to the project root and stay inside it');
+const envName = z.string().regex(/^[A-Z][A-Z0-9_]{0,63}$/, 'must be an environment variable name');
+const syndicateRecord = z
+    .object({
+    deliverable: z.enum(['service', 'library', 'mcp']).optional(),
+    publish: z.object({ kind: z.literal('registry'), id: z.string().min(1) }).passthrough().optional(),
+})
+    .passthrough();
+export const projectManifestSchema = z
+    .object({
+    manifest: z.number().int().min(1),
+    engine: z.string().regex(/^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/, 'must be an exact version, e.g. 1.8.0'),
+    agents: relPath,
+    ignore: z.array(z.string().min(1)).optional(),
+    tests: relPath.optional(),
+    env: z.array(envName).optional(),
+    syndicates: z.record(z.string(), syndicateRecord).optional(),
+    registry: z
+        .object({ kind: z.literal('supabase'), url_env: envName.optional(), restart: z.string().optional() })
+        .passthrough()
+        .optional(),
+    production: z
+        .object({ ledger: z.object({ kind: z.literal('postgres'), url_env: envName }).passthrough().optional() })
+        .passthrough()
+        .optional(),
+    tools: z
+        .object({ remote: z.record(z.string(), z.object({ mcp_env: envName }).passthrough()).optional() })
+        .passthrough()
+        .optional(),
+})
+    // Unknown keys are kept: a newer writer's fields survive an older reader.
+    .passthrough();
+/** Thrown for a manifest that does not parse or validate; names the file and fields, never a value. */
+export class ProjectManifestError extends Error {
+    file;
+    issues;
+    constructor(file, issues) {
+        super(`${file}: ${issues.join('; ')}`);
+        this.file = file;
+        this.issues = issues;
+        this.name = 'ProjectManifestError';
+    }
+}
+/**
+ * The nearest folder at or above `from` holding a manifest, without crossing
+ * the repository root or the home directory. Undefined when there is none.
+ */
+export function findProjectRoot(from = process.cwd()) {
+    const home = resolve(homedir());
+    let dir = resolve(from);
+    for (;;) {
+        if (existsSync(join(dir, PROJECT_MANIFEST)))
+            return dir;
+        if (existsSync(join(dir, '.git')) || dir === home)
+            return undefined;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/** Parse and validate a manifest's text. Throws `ProjectManifestError`. */
+export function parseProjectManifest(text, file = PROJECT_MANIFEST) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new ProjectManifestError(file, ['not valid JSON']);
+    }
+    const parsed = projectManifestSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new ProjectManifestError(file, parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`));
+    }
+    if (parsed.data.manifest > MANIFEST_VERSION) {
+        throw new ProjectManifestError(file, [`manifest: version ${parsed.data.manifest} is newer than this engine reads (${MANIFEST_VERSION}); upgrade melchizedek-agents`]);
+    }
+    return parsed.data;
+}
+/** A path under the root, or an error when it would leave it. */
+function under(root, rel, field, file) {
+    const abs = resolve(root, rel);
+    if (abs !== root && !abs.startsWith(root + sep))
+        throw new ProjectManifestError(file, [`${field}: resolves outside the project root`]);
+    return abs;
+}
+/** Load the project rooted at `root` (the folder holding the manifest). Throws `ProjectManifestError`. */
+export function loadProject(root) {
+    const r = resolve(root);
+    const file = join(r, PROJECT_MANIFEST);
+    const manifest = parseProjectManifest(readFileSync(file, 'utf-8'), file);
+    return {
+        root: r,
+        file,
+        manifest,
+        agentsDir: under(r, manifest.agents, 'agents', file),
+        testsDir: under(r, manifest.tests ?? join('tests', 'agents'), 'tests', file),
+    };
+}
+/** The project at or above `from`, or undefined when there is none. Throws on a broken manifest. */
+export function findProject(from = process.cwd()) {
+    const root = findProjectRoot(from);
+    return root ? loadProject(root) : undefined;
+}
+// The agents-directory chain runs on every syndicate read (an A2A route
+// reads per request), so the manifest lookup is cached per working
+// directory. A broken manifest is cached as "none" and reported by
+// `melchizedek-doctor`, never by a request path.
+const agentsDirCache = new Map();
+/** Forget cached manifest lookups (tests, and an embedder that edits the manifest in-process). */
+export function clearProjectCache() {
+    agentsDirCache.clear();
+}
+function manifestAgentsDir(cwd) {
+    if (!agentsDirCache.has(cwd)) {
+        let dir = null;
+        try {
+            dir = findProject(cwd)?.agentsDir ?? null;
+        }
+        catch {
+            dir = null;
+        }
+        agentsDirCache.set(cwd, dir);
+    }
+    return agentsDirCache.get(cwd) ?? undefined;
+}
+/**
+ * The agents directory: `explicit` → MELCHIZEDEK_AGENTS_DIR → the nearest
+ * manifest's `agents` → <cwd>/config/agents. Always absolute.
+ */
+export function resolveAgentsDir(explicit, env = process.env) {
+    const fromEnv = env.MELCHIZEDEK_AGENTS_DIR?.trim();
+    const cwd = process.cwd();
+    return resolve(explicit ?? (fromEnv || undefined) ?? manifestAgentsDir(cwd) ?? join(cwd, 'config', 'agents'));
+}
+/** Glob to RegExp for `*` (one segment), `**` (any depth) and `?`, on `/`-separated paths. */
+function globToRegExp(glob) {
+    let re = '';
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === '*') {
+            if (glob[i + 1] === '*') {
+                i++;
+                if (glob[i + 1] === '/') {
+                    i++;
+                    re += '(?:.*/)?';
+                }
+                else
+                    re += '.*';
+            }
+            else
+                re += '[^/]*';
+        }
+        else if (c === '?')
+            re += '[^/]';
+        else
+            re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+    return new RegExp(`^${re}$`);
+}
+/** True when `relFromRoot` (a `/`-separated path relative to the project root) matches an `ignore` pattern. */
+export function isIgnored(project, relFromRoot) {
+    const p = relFromRoot.split(sep).join('/');
+    return (project.manifest.ignore ?? []).some((g) => globToRegExp(g).test(p));
+}
+/** The syndicate files directly in the agents folder, as names relative to it, minus `ignore`. */
+export function listProjectSyndicates(project) {
+    if (!existsSync(project.agentsDir))
+        return [];
+    const rel = relative(project.root, project.agentsDir);
+    return readdirSync(project.agentsDir)
+        .filter((f) => (f.endsWith('.yaml') || f.endsWith('.yml')) && f !== 'syndicateSchema.yaml')
+        .filter((f) => statSync(join(project.agentsDir, f)).isFile())
+        .filter((f) => !isIgnored(project, rel ? `${rel}/${f}` : f))
+        .sort();
+}
+/** The installed engine's package version (no commit suffix). */
+export function enginePackageVersion() {
+    try {
+        const root = enginePackageRoot();
+        if (root)
+            return String(JSON.parse(readFileSync(join(root, 'package.json'), 'utf-8')).version);
+    }
+    catch {
+        /* fall through */
+    }
+    return '0.0.0';
+}
+/** What is wrong with a project: engine pin, missing folders, stale ignores, unset env names. Never reads a value. */
+export function checkProject(project, running = enginePackageVersion(), env = process.env) {
+    const problems = [];
+    const warnings = [];
+    const pinned = project.manifest.engine;
+    const matches = pinned === running;
+    if (!matches)
+        problems.push(`engine: the project pins melchizedek-agents ${pinned}; ${running} is running`);
+    if (!existsSync(project.agentsDir))
+        problems.push(`agents: ${project.manifest.agents} does not exist`);
+    if (project.manifest.tests && !existsSync(project.testsDir))
+        problems.push(`tests: ${project.manifest.tests} does not exist`);
+    for (const g of project.manifest.ignore ?? []) {
+        if (!anyPathMatches(project.root, globToRegExp(g)))
+            warnings.push(`ignore: "${g}" matches nothing`);
+    }
+    for (const name of project.manifest.env ?? [])
+        if (!env[name]?.trim())
+            warnings.push(`env: ${name} is not set`);
+    const syndicates = listProjectSyndicates(project);
+    for (const f of Object.keys(project.manifest.syndicates ?? {})) {
+        if (!syndicates.includes(f))
+            warnings.push(`syndicates: ${f} is not in ${project.manifest.agents}`);
+    }
+    return { root: project.root, agentsDir: project.agentsDir, engine: { pinned, running, matches }, syndicates, problems, warnings };
+}
+const SKIP_DIRS = new Set(['.git', 'node_modules', 'venv', '.venv', '__pycache__', 'dist']);
+/** Whether any path under root (depth-limited, skipping vendor folders) matches. */
+function anyPathMatches(root, re, rel = '', depth = 0) {
+    if (depth > 6)
+        return false;
+    let entries;
+    try {
+        entries = readdirSync(join(root, rel));
+    }
+    catch {
+        return false;
+    }
+    for (const e of entries) {
+        if (SKIP_DIRS.has(e))
+            continue;
+        const p = rel ? `${rel}/${e}` : e;
+        if (re.test(p))
+            return true;
+        let dir = false;
+        try {
+            dir = statSync(join(root, p)).isDirectory();
+        }
+        catch {
+            /* unreadable entry */
+        }
+        if (dir && anyPathMatches(root, re, p, depth + 1))
+            return true;
+    }
+    return false;
+}

package/dist/lib/runtime/native/checkpoint.d.ts

@@ -15,7 +15,8 @@
  *   runner, unchanged, continues where the snapshot stood. runDurableTurn
  *   is runSyndicateTurn with that store and a sink.
  *
- * A STEP BOUNDARY is an append that carries function responses after which
+ * A STEP BOUNDARY is an append that carries function responses, or a
+ * script's journal event (ADR 0137 item 8), after which
  * every function call any session of the run holds has its response (calls
  * listed in their event's longRunningToolIds, which wait on a person, aside).
  * So a parent waiting on a delegated subagent is never at a boundary, the

package/dist/lib/runtime/native/checkpoint.js

@@ -15,7 +15,8 @@
  *   runner, unchanged, continues where the snapshot stood. runDurableTurn
  *   is runSyndicateTurn with that store and a sink.
  *
- * A STEP BOUNDARY is an append that carries function responses after which
+ * A STEP BOUNDARY is an append that carries function responses, or a
+ * script's journal event (ADR 0137 item 8), after which
  * every function call any session of the run holds has its response (calls
  * listed in their event's longRunningToolIds, which wait on a person, aside).
  * So a parent waiting on a delegated subagent is never at a boundary, the
@@ -75,6 +76,7 @@
  */
 import { createHash, randomUUID } from 'node:crypto';
 import { getFunctionCalls, getFunctionResponses, parseTurnEvents } from '../events.js';
+import { JOURNAL_EVERY_CALL, isJournalEvent } from '../../script/journal.js';
 import { InProcessSessionService } from '../sessions.js';
 import { runSyndicateTurn } from '../syndicateTurn.js';
 // ── Shapes ───────────────────────────────────────────────────────────────────
@@ -127,6 +129,8 @@ export function usableCheckpoint(cp, runId, parts) {
 /** Content compared as stored JSON. */
 const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 class CheckpointingStore {
+    /** A script run stores each call's journal event as it ends, and each is a step boundary (ADR 0137 item 8). */
+    [JOURNAL_EVERY_CALL] = true;
     inner;
     opts;
     openingParts;
@@ -250,7 +254,7 @@ class CheckpointingStore {
         if (stored.author !== 'user' && this.firstAgentSeq === undefined)
             this.firstAgentSeq = order;
         this.track(stored);
-        if (getFunctionResponses(stored).length > 0 && this.openCalls.size === 0)
+        if ((getFunctionResponses(stored).length > 0 || isJournalEvent(stored)) && this.openCalls.size === 0)
             await this.boundary();
         return stored;
     }

package/dist/lib/runtime/native/interrupts.js

@@ -163,6 +163,7 @@ import { approvalRequestOf, pendingApproval } from '../approvals.js';
 import { consentFrom, pendingConsent } from '../credentials.js';
 import { getFunctionCalls, getFunctionResponses } from '../events.js';
 import { ASK_USER, pendingQuestion } from '../questions.js';
+import { isJournalEvent, scriptPauseIn } from '../../script/journal.js';
 import { childAppName, entryAppName, legacyChild, legacyEntry } from './delegate.js';
 import { REQUEST_CONFIRMATION_CALL, REQUEST_CREDENTIAL_CALL, REQUEST_INPUT_CALL, isSegmentPrefix } from './history.js';
 import { isToolset } from './request.js';
@@ -516,6 +517,12 @@ async function conversationPause(key, child, name, id, depth, seen = new Set())
             ...(routed.consent ? { consent: { ...routed.consent, path } } : {}),
         };
     }
+    // A nested script syndicate's own pause (ADR 0137 item 15): its askUser or a gated tool() call, authored by the script.
+    const scripted = scriptPauseIn(child.events, id);
+    if (scripted) {
+        const path = scripted.asker === name ? [name] : down([scripted.asker]);
+        return { path, ...(scripted.approval ? { approval: { ...scripted.approval, path } } : {}), ...(scripted.question ? { question: { ...scripted.question, path } } : {}) };
+    }
     const approval = pendingApproval(child.events);
     if (approval && approval.agent && approval.agent !== 'user' && approval.agent !== name && wanted(approval.id)) {
         const path = down([approval.agent]);
@@ -543,8 +550,8 @@ async function conversationPause(key, child, name, id, depth, seen = new Set())
         ...(first.consent ? { consent: { ...first.consent, path } } : {}),
     };
 }
-/** A walk's session: its node events carry a dotted node path (`<workflow>.<node>`). */
-const isWalk = (session) => session.events.some((e) => typeof e.nodeInfo?.path === 'string' && e.nodeInfo.path.includes('.'));
+/** A walk's session: its node events carry a dotted node path (`<workflow>.<node>`); a script's journal events do not count. */
+const isWalk = (session) => session.events.some((e) => typeof e.nodeInfo?.path === 'string' && e.nodeInfo.path.includes('.') && !isJournalEvent(e));
 /**
  * The pause a nested workflow's walk holds in its child session (ADR 0111):
  * the workflow's own pause record, the last event, authored by the

package/dist/lib/runtime/nativeTurn.d.ts

@@ -18,7 +18,8 @@
  * feature (UnsupportedOnRuntimeError): a caller's `transformAgent` (it
  * transformed ADK agents, and ADK left in 1.0.0), and an `ask_user` tool on
  * a workflow's agent (the schema refuses it; a config that skipped
- * validation is refused here, ADR 0095). A workflow syndicate runs on the
+ * validation is refused here, ADR 0095), and a script or a `run_code`
+ * tool while MELCHIZEDEK_CODE_SANDBOX is off (CodeSandboxOffError, ADR 0137). A workflow syndicate runs on the
  * engine's scheduler (lib/workflow/turn.ts, ADR 0095). An answer to an
  * approval resumes the call (lib/runtime/native/interrupts.ts), an answer
  * to a question resumes the agent that asked (lib/runtime/questions.ts, ADR

package/dist/lib/runtime/nativeTurn.js

@@ -18,7 +18,8 @@
  * feature (UnsupportedOnRuntimeError): a caller's `transformAgent` (it
  * transformed ADK agents, and ADK left in 1.0.0), and an `ask_user` tool on
  * a workflow's agent (the schema refuses it; a config that skipped
- * validation is refused here, ADR 0095). A workflow syndicate runs on the
+ * validation is refused here, ADR 0095), and a script or a `run_code`
+ * tool while MELCHIZEDEK_CODE_SANDBOX is off (CodeSandboxOffError, ADR 0137). A workflow syndicate runs on the
  * engine's scheduler (lib/workflow/turn.ts, ADR 0095). An answer to an
  * approval resumes the call (lib/runtime/native/interrupts.ts), an answer
  * to a question resumes the agent that asked (lib/runtime/questions.ts, ADR
@@ -30,6 +31,7 @@ import { createTurnEvent } from './events.js';
 import { runAgentLoop } from './native/agentLoop.js';
 import { ASK_USER } from './questions.js';
 import { unsupportedOnNative } from './runtimeFlag.js';
+import { refuseWithoutSandbox } from '../sandbox/sandbox.js';
 // ── What native refuses before a turn starts ─────────────────────────────────
 /**
  * Throws UnsupportedOnRuntimeError for a syndicate or a call the runtime
@@ -39,6 +41,8 @@ export function refuseOnNative(config, call) {
     const where = config.syndicate_name || config.orchestrator?.name || 'syndicate';
     if (call.transformAgent)
         throw unsupportedOnNative('transformAgent (it transformed ADK agents; the ADK runtime was removed in 1.0.0)', where);
+    // A script, or an agent listing run_code, runs code: only once the operator turned the sandbox on (ADR 0137 item 4).
+    refuseWithoutSandbox(config);
     if (call.isWorkflow) {
         // A pause inside an agent node cannot be resumed by the native walk (lib/workflow/resume.ts).
         const asking = [config.orchestrator, ...(config.subagents ?? [])].find((agent) => (agent?.tools ?? []).includes(ASK_USER));

package/dist/lib/runtime/syndicateTurn.d.ts

@@ -64,6 +64,8 @@ export { ASK_USER, pendingQuestion, questionAnswerPart } from './questions.ts';
 import type { PendingApproval } from './approvals.ts';
 export { approvalResponsePart, describeApproval, pendingApproval } from './approvals.ts';
 export type { PendingApproval } from './approvals.ts';
+import type { CodeRun } from '../tools/runCodeTool.ts';
+export type { CodeRun } from '../tools/runCodeTool.ts';
 import type { AgentBranch, TurnStopReason } from './turnControl.ts';
 export type { AgentBranch } from './turnControl.ts';
 /** One part of the user's message. Text is the common case; the genai part
@@ -222,8 +224,10 @@ export interface DrainedRun {
         code: string;
         message: string;
     }>;
+    /** Every run_code call that got its result, with the agent that made it (ADR 0137). */
+    codeRuns: CodeRun[];
 }
-export type TurnStage = 'classify' | 'dispatch' | 'delegate' | 'workflow';
+export type TurnStage = 'classify' | 'dispatch' | 'delegate' | 'workflow' | 'script';
 export interface RouteDecision extends RouteResolution {
     /** `approval`: the turn resumed the route that asked for an approval (ADR 0028).
      *  `answer`: the message answered the route's open `ask_user` question.
@@ -272,6 +276,12 @@ export interface SyndicateTurnResult {
     usage: TurnUsage;
     /** Set when a control (cancel, deadline, step limit) stopped the turn. */
     stopReason?: TurnStopReason;
+    /**
+     * The run_code runs of agents whose YAML sets `run_code: { attach: true }`
+     * (ADR 0137 item 3), in order: the reply's `code_run` data parts. Absent
+     * when there are none.
+     */
+    codeRuns?: CodeRun[];
 }
 /** A turn's spend: model calls and the tokens the providers reported. */
 export interface TurnUsage {