melchizedek-agents 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -6,6 +6,119 @@ the starter pack and the templates), not the repo's full history.
 
 ## Unreleased
 
+## 1.8.0 — 2026-10-18
+
+A minor release that gives a repository a manifest (ADR 0138). A
+`melchizedek.json` at the root names the agents folder, the exact engine
+version the project is written for, and how each syndicate ships; the
+bins find it on their own, `melchizedek-doctor` checks the pin, and the
+desktop app opens a repository through it. Nothing changes for a
+deployment that sets `MELCHIZEDEK_AGENTS_DIR`.
+
+### Added
+
+- **The project manifest, `melchizedek.json` (ADR 0138).** A JSON file at
+  a repository's root naming its agents folder (`agents`), the engine
+  version it is written for (`engine`, an exact pin), an `ignore` list,
+  a `tests` folder, the env variable *names* it needs, and per-file
+  shipping records (`syndicates.<file>.deliverable`,
+  `publish: { kind: "registry", id }`). New subpath
+  `melchizedek-agents/project` and barrel exports: `findProject`,
+  `loadProject`, `parseProjectManifest`, `resolveAgentsDir`,
+  `listProjectSyndicates`, `checkProject`, `projectManifestSchema`.
+- **The agents directory reads the manifest.** Every loader and bin
+  resolves it as: explicit option, `MELCHIZEDEK_AGENTS_DIR`, the nearest
+  manifest's `agents` (not above the repository root), then
+  `<cwd>/config/agents`. A deployment that sets the variable is
+  unchanged.
+- **`melchizedek-doctor` reports the project**: the engine pin against
+  the running engine, a missing agents or tests folder, `ignore`
+  patterns that match nothing, unset env names, and `syndicates` keys
+  with no file. A pin mismatch or a missing folder fails `--check`.
+
+## 1.7.0 — 2026-10-17
+
+A minor release that lets a syndicate hold code (ADR 0137). A `script:`
+block is the fourth orchestration method: one JavaScript module, run in
+a QuickJS sandbox on a worker thread, calls the syndicate's agents, its
+allowed tools and the person as functions, so routing, per-call models
+and human-in-the-loop change with a YAML deploy instead of an engine
+release. Agents on any provider get `run_code`, the same sandbox as a
+registry tool. Both are off until the operator sets
+`MELCHIZEDEK_CODE_SANDBOX=on`; nothing changes for a deployment that
+does not.
+
+### Added
+
+- **`script:` orchestration (ADR 0137 Part B).** `script: { source,
+  models?, tools? }` at the root; cannot be combined with `dispatch` or
+  `workflow`. The default export is called with `{ message, transcript,
+  variables, agent, tool, askUser, parallel, now, random, log }` and its
+  return is the answer; guards run on it once. `agent(name, input, {
+  model?, reasoning?, temperature?, conversation? })` runs a declared
+  agent (parsed JSON when it has an output schema, else text; a failed run
+  throws into the script); `conversation: true` answers in the
+  conversation as a dispatch route does. `askUser(id, question, {
+  payload?, schema? })` pauses the turn `input-required` with the same
+  `result.input` an `ask_user` node writes; the next message resumes the
+  run by replaying its journal (one content-less event per call, stored in
+  the conversation only when the run pauses) on the source the pause pinned, so a redeploy never breaks
+  a waiting conversation. A resume whose calls no longer match fails
+  `SCRIPT_DIVERGED`; a run past 1,000 calls fails `SCRIPT_CALL_LIMIT`.
+  The schema refuses `require_approval`, the `ask_user` tool, local skill
+  scripts and authorization_code grants on a script's agents (a pause
+  inside a called agent cannot be replayed yet), `context:` and root
+  `max_concurrency`; `mode: task` is allowed (a pause reached inside a
+  called agent anyway fails `PAUSE_INSIDE_AGENT`). `{{token}}`
+  interpolation skips `script.source`; the script reads the bound
+  `variables`. `script.require_approval` gates `tool()` calls with the
+  standard approval request (`result.approval`). Every `script.models`
+  pairing is checked before the run (`SCRIPT_MODEL_INVALID`). Under
+  `runDurableTurn` each call's journal event is a checkpoint boundary, so
+  a stopped worker resumes mid-script. `agent()` calls report through
+  `events.onAgentEvent`; spans `script.invoke` and `script.call`
+  (exported to `adk_telemetry`, no arguments or results) trace a run, and
+  each agent call's turn span carries `script.run` and `script.call.seq`.
+  A `yaml_reference` to a script syndicate runs its whole script as a
+  subagent, route or node, its pauses reaching the turn; `agent()` may
+  call nested workflow, dispatch and script syndicates.
+  `startEngineSpan` takes an optional parent context.
+  `TurnStage` gains `'script'`; `SyndicateTurnResult.failedStage` may be
+  `'script'`.
+- **`run_code` (ADR 0137 Part A).** A registry tool: `{ code, input? }`,
+  an ES module whose default export is called with `input`, returning
+  `{ result, logs, error }`, each bounded at 20,000 characters. No
+  network, files, host, clock or randomness. An agent's
+  `run_code: { attach: true }` puts each run on the reply:
+  `SyndicateTurnResult.codeRuns` and, on the A2A server, a `code_runs`
+  artifact of `code_run` data parts. `DrainedRun` gains `codeRuns`.
+- **The sandbox.** QuickJS (`quickjs-emscripten-core` and
+  `@jitl/quickjs-wasmfile-release-sync`, both pinned at 0.32.0) on a
+  worker thread per run: 64 MB memory, 1 MB stack, 5 s of compute (waits
+  on the host not counted), a watchdog and the turn's signal terminate
+  it; `MELCHIZEDEK_CODE_SANDBOX_WORKERS` (default 16) caps concurrent
+  runs. A syndicate with a script or a `run_code` agent is refused with
+  `CodeSandboxOffError` when a turn starts while the switch is off.
+- **Package surface.** New subpaths `melchizedek-agents/script`
+  (`runScript`, `ScriptFatal`, `SCRIPT_CALL_LIMIT`, and the journal reader
+  `openRun` / `scriptPauseIn` with the `SCRIPT_*` marker keys and the
+  `JournalEntry`, `OpenRun`, `ScriptCallRecord`, `ScriptPauseRecord`,
+  `ScriptPinRecord` types) and
+  `melchizedek-agents/sandbox` (`runInSandbox`, `codeSandboxEnabled`,
+  `refuseWithoutSandbox`, `CodeSandboxOffError`, `SandboxHalt`,
+  `DEFAULT_SANDBOX_LIMITS`). The barrel adds those plus
+  `isScriptSyndicate`, `openRun`, `runCodeTool`, `RUN_CODE` and the types
+  `ScriptConfig`, `ScriptHost`, `ScriptCallSite`, `JournalEntry`, `OpenRun`,
+  `ScriptPauseRecord`, `ScriptPinRecord`, `ScriptRunInput`, `ScriptRunOutcome`,
+  `SandboxLimits`, `SandboxResult`, `SandboxRunOptions`, `CodeRun`,
+  `RunCodeOutput`.
+
+### For melch-app
+
+- An Electron build must list `quickjs-emscripten-core`,
+  `@jitl/quickjs-wasmfile-release-sync` and `melchizedek-agents/dist/lib/sandbox`
+  in `asarUnpack`: the wasm file and the worker script load from disk.
+
 ## 1.6.0 — 2026-10-15
 
 A minor release for applications that show a turn as it runs and account

package/DOCUMENTATION.md

@@ -35,6 +35,8 @@ lib/tools/mcpToolFactory.ts  MCP client: remote tools → the engine's own Tools
 scripts/demo_mcp_server.ts   demo MCP server (library catalog, SSE)
 lib/runtime/native/…      the native loop: steps, delegation, compaction, interrupts
 lib/workflow/…            the workflow scheduler for `workflow:` syndicates
+lib/script/…              the runner for `script:` syndicates: journal, replay, pause (ADR 0137)
+lib/sandbox/…             the QuickJS code sandbox on a worker thread (run_code, script:)
 lib/session/…             Supabase-backed session service
 lib/memory/…              pgvector long-term memory service
 lib/observability/…       OpenTelemetry run tracing
@@ -63,7 +65,7 @@ agent. The native runtime is the only runtime
 ([ADR 0107](./wiki/decisions/0107-release-1-0-0-removes-adk.md)): it owns the
 loop, the model contract and its adapters, the tools, the sessions and
 the workflow scheduler, and runs a single-agent, delegating,
-plan-dispatch or `workflow:` syndicate, `context:` compaction
+plan-dispatch, `workflow:` or `script:` syndicate, `context:` compaction
 ([ADR 0078](./wiki/decisions/0078-native-compaction-ports-adk-compactor.md)),
 `mode: task`, and pause and resume included
 ([ADR 0095](./wiki/decisions/0095-native-workflow-turn-drains-through-the-adk-reader.md)).
@@ -130,11 +132,13 @@ Field reference:
 | `memory_retention_days` | root | Days a fact in this syndicate's namespace is kept; the server deletes older facts when it loads the syndicate and daily after. Requires `memory_namespace` (never applied to the shared default namespace). |
 | `dispatch` | root | Switches the syndicate from DELEGATE to PLAN-DISPATCH routing (§6). `default_route` (required) names the fail-static subagent; `route_key` / `reason_key` name the router's JSON properties (defaults `route` / `reason`). Honoured by every surface (the CLI, the server, the worker, evals). |
 | `workflow` | root | Switches the syndicate to a WORKFLOW (§6): a graph whose nodes are its agents plus declared `join`, `map`, `tool` and `ask_user` nodes, and whose `edges` say what runs after what and on which route. The orchestrator is a node like any other; nothing delegates. Cannot be combined with `dispatch`. Contract: `lib/workflow.ts`; worked example: `examples/pipeline.yaml`. |
+| `script` | root | Switches the syndicate to a SCRIPT ([ADR 0137](./wiki/decisions/0137-script-orchestration-and-sandboxed-code.md)): `source` is one JavaScript module, run in the engine's QuickJS sandbox, whose default export gets `{ message, transcript, variables, agent, tool, askUser, parallel, now, random, log }` and returns the answer. `models` lists the models `agent(name, input, { model })` may move a call to; `tools` the registry tools `tool(name, args)` may run. `askUser` pauses the turn; the next message replays the run's journal on the source it pinned. Needs `MELCHIZEDEK_CODE_SANDBOX=on`; cannot be combined with `dispatch` or `workflow`; the agents may not pause inside themselves (no `require_approval`, `ask_user` tool, local skill scripts or authorization_code grants). `{{token}}` does not touch `source`. |
 | `retries` | root | Self-correction, on by default ([ADR 0034](./wiki/decisions/0034-self-correction.md)): `model_errors` (default 2) retries a model reply marked malformed (`MALFORMED_FUNCTION_CALL`) instead of failing the turn; `tool_errors` (default 3) answers a tool that threw with structured reflection guidance and caps its retries. `0` turns either off. Every retry is a model call under `max_steps`. |
 | `guards` | root | Optional list of post-answer guard NAMES (`lib/guards/index.ts`). Each runs after the answering turn and before the reply publishes, receiving the final text plus every tool-result text of that turn, and rewrites in place rather than re-asking the model; its notes land in the `[STATUS]` stream. Guards declared by a syndicate reached through `yaml_reference:` count too — the server resolves the union via `collectGuards()`. Resolved by name, never by module path, so adding one is a deliberate act in code; **the published registry ships one, `science`** (citation checks for `research.yaml`); `registerGuard()` adds your own from code, and an unregistered name is warned about and skipped. |
 | `name` / `model` / `instruction` | agent | The agent triple. Any Gemini id, `claude-*`, or `ollama/*` for open-weight local models (see §5). |
 | `description` | subagent | **The delegation API.** The orchestrator reads this when deciding to hand off — write it like a function signature ("Use this subagent to…, pass it…"). |
 | `tools` | agent | Names resolved by the tool registry (§3). Long-term memory agents add `preload_memory` / `load_memory`. |
+| `run_code` | agent | With `run_code` in `tools`, the agent runs JavaScript in the engine's sandbox on any provider (`{ code, input? }` → `{ result, logs, error }`; no network, host, clock or randomness; needs `MELCHIZEDEK_CODE_SANDBOX=on`, [ADR 0137](./wiki/decisions/0137-script-orchestration-and-sandboxed-code.md)). `run_code: { attach: true }` puts each run's code and result on the reply as a `code_run` data part (`result.codeRuns`). |
 | `reasoning` | agent | How hard the agent reasons, on any provider: `none`, `low`, `medium`, `high`, `xhigh`, `max`, or `{ budget_tokens: <int> }`. The compiler sends each provider the field it reads: a thinking level on Gemini 3, a thinking budget on Claude 4.6 and earlier (2,048 / 8,192 / 16,384 tokens for low / medium / high), adaptive thinking with that effort on later Claude models ([ADR 0049](./wiki/decisions/0049-claude-requests-by-model-generation.md)), an effort word on GPT, Grok, Kimi, Ollama and the gateway ([ADR 0047](./wiki/decisions/0047-provider-neutral-reasoning-key.md)). `xhigh` and `max` reach the models that take them (both on Claude from Opus 4.7 and Sonnet 5, `max` on Kimi K3, `xhigh` on GPT-5.2 and later and grok-4.7); elsewhere the model's highest setting is sent and the span carries `llm.reasoning.weakened` (`npm run doctor -- --matrix` lists each path, [ADR 0117](./wiki/decisions/0117-tool-choice-and-effort-above-high-in-v2.md)). Unset, each adapter keeps its own default. |
 | `sampling` | agent | `{ temperature, top_p, max_output_tokens, stop }`, the fields the engine sends to every provider; each adapter sends the ones its API takes ([ADR 0115](./wiki/decisions/0115-yaml-schema-v2-provider-neutral-keys.md)). |
 | `output` | agent | `{ schema, mime }`. `mime` is `application/json` (JSON mode, with or without a schema) or `text/plain` (the default). `schema` is the structured-JSON contract: the agent ends its turn on one JSON object matching it. An orchestrator may hold one beside its subagents: it delegates first, then answers in the schema itself. The schema travels in the provider's own structured-output field beside the tools on Claude from Opus 4.8, Sonnet 5 and Haiku 5.5, on OpenAI, and on Gemini 2+ through Vertex AI, and as a `set_model_response` tool elsewhere (the capability matrix's `structured_output_with_tools`, [ADR 0109](./wiki/decisions/0109-structured-output-beside-tools.md)). Worked example: `examples/structured_critic.yaml`. A leaf that holds the schema (`critic.yaml`) and plan-dispatch remain the choices when the answer should be a specialist's. |
@@ -1606,22 +1610,27 @@ subclass), and register it behind a model-id prefix.
 subagent. `scripts/demo_mcp_server.ts` is a complete server to copy —
 tool definitions, SSE wiring, and persistent state in ~250 lines.
 
-**Teach your coding agent the framework**: `skills/` holds six Agent
+**Teach your coding agent the framework**: `skills/` holds eleven Agent
 Skills (the open SKILL.md standard — a directory per skill, `name` and
 `description` frontmatter) that give Claude Code, Codex, Cursor,
 OpenCode or Gemini CLI the catalog of syndicates and the procedures in
 this document: `melchizedek` (find and run, delegate a task),
 `melchizedek-author`, `melchizedek-serve`, `melchizedek-memory`,
-`melchizedek-models`, `melchizedek-scribe`. `npx melchizedek-skills
+`melchizedek-models`, `melchizedek-scribe`, and five onboarding skills
+that route a person by the credentials they have — `melchizedek-onboard`
+(the triage) and `melchizedek-onboard-local`, `-keys`, `-cloud` and
+`-serve` (the authentication levels each owns). `npx melchizedek-skills
 install` copies them into `.claude/skills/` and `.agents/skills/` of the
 current project (`--for claude,codex,cursor,opencode,gemini,agents,all`,
 `--global`, `--dir <path>`, `--only <names>`, `--force`, `--dry-run`;
 `npm run skills:install` in a clone). The installer (`lib/skills.ts`)
 copies only from the package's own `skills/` directory, follows no
-symlinks, and never overwrites a differing file without `--force`. Each
-SKILL.md body was written by the Scribe syndicate
-(`config/agents/examples/scribe.yaml`) from a brief of facts and reviewed
-by a person; `skills/README.md` records the procedure.
+symlinks, and never overwrites a differing file without `--force`. The
+onboarding skills are short procedures written by hand that print their
+facts from `melchizedek-setup --level <id>`; every other SKILL.md body was
+written by the Scribe syndicate (`config/agents/examples/scribe.yaml`)
+from a brief of facts and reviewed by a person; `skills/README.md`
+records the procedure.
 
 ## 8. Security notes
 

package/config/agents/syndicate.schema.json

@@ -943,6 +943,17 @@
           "type": "string",
           "const": "gemini"
         },
+        "run_code": {
+          "description": "How this agent's run_code tool behaves (ADR 0137). Needs run_code in `tools`.",
+          "type": "object",
+          "properties": {
+            "attach": {
+              "description": "Put each run's code and result on the reply as a code_run data part. Default false.",
+              "type": "boolean"
+            }
+          },
+          "additionalProperties": false
+        },
         "context": {
           "description": "Summarize a long conversation instead of overflowing the window. The orchestrator of a delegate syndicate only.",
           "type": "object",
@@ -1967,6 +1978,17 @@
             "type": "string",
             "const": "gemini"
           },
+          "run_code": {
+            "description": "How this agent's run_code tool behaves (ADR 0137). Needs run_code in `tools`.",
+            "type": "object",
+            "properties": {
+              "attach": {
+                "description": "Put each run's code and result on the reply as a code_run data part. Default false.",
+                "type": "boolean"
+              }
+            },
+            "additionalProperties": false
+          },
           "context": {
             "description": "Summarize a long conversation instead of overflowing the window. The orchestrator of a delegate syndicate only.",
             "type": "object",
@@ -2302,6 +2324,47 @@
       "additionalProperties": false,
       "description": "Opts into a WORKFLOW: the syndicate as a graph (lib/workflow.ts). Cannot be combined with dispatch."
     },
+    "script": {
+      "type": "object",
+      "properties": {
+        "source": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 65536,
+          "description": "One JavaScript module whose default export is an async function of { message, variables, agent, tool, askUser, parallel, now, random, log }: the orchestration. Its return value is the answer. {{token}} interpolation does not touch it; it reads `variables`."
+        },
+        "models": {
+          "description": "The models agent(name, input, { model }) may move a call to; each agent is compiled and checked on every one at load.",
+          "maxItems": 16,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "tools": {
+          "description": "The registry tools tool(name, args) may run; the only path from the script to the network or the host.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "require_approval": {
+          "description": "Tools from script.tools whose every call waits for a person to approve the exact call (ADR 0028): the turn ends input-required; approved, the pinned arguments run, refused, the script gets { error }.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      },
+      "required": [
+        "source"
+      ],
+      "additionalProperties": false,
+      "description": "Opts into SCRIPT orchestration (lib/script/): the syndicate's logic as code run in the engine's sandbox. Needs MELCHIZEDEK_CODE_SANDBOX=on. Cannot be combined with dispatch or workflow."
+    },
     "retries": {
       "description": "Self-correction on model and tool errors: the engine's reflect-and-retry. On by default.",
       "type": "object",

package/config/agents/syndicateSchema.yaml

@@ -190,6 +190,48 @@ dispatch:
 #     Confirm: { ask_user: "Publish? Reply yes, or say what to change." }
 #   max_concurrency: 4
 
+# [optional] Switches this syndicate to a SCRIPT (ADR 0137): one
+# JavaScript module, run in the engine's QuickJS sandbox, is the
+# orchestration. It calls the agents below, the tools it lists and the
+# person as functions, so routing, per-call models and pauses live here
+# and change with a deploy. Needs MELCHIZEDEK_CODE_SANDBOX=on. Cannot be
+# combined with `dispatch` or `workflow`. Contract: lib/script/.
+#
+#   - The default export is called with { message, transcript, variables,
+#     agent, tool, askUser, parallel, now, random, log }; its return (text,
+#     or JSON) is the answer, and `guards` run on it once.
+#   - agent(name, input, { model?, reasoning?, temperature?,
+#     conversation? }) runs a declared agent seeing only `input` (null:
+#     the message); it returns parsed JSON when the agent has an output
+#     schema, else its text, and throws when the run fails. With
+#     `conversation: true` it answers in the conversation, as a dispatch
+#     route does. `model` must be in script.models.
+#   - tool(name, args) runs a registry tool listed in script.tools; one
+#     also in script.require_approval waits for a person to approve the
+#     exact call (refused, the script gets { error }).
+#   - askUser(id, question, { payload?, schema? }) pauses the turn
+#     input-required; the next message resumes it, returning
+#     { reply, input }. The run replays its journal from the top, so a
+#     script must make the same calls on every run: use now() and
+#     random(), never Date or Math.random (they throw), and never
+#     Promise.race.
+#   - require_approval, the ask_user tool, skills.scripts: local and
+#     authorization_code grants are refused on a script's agents in this
+#     version (a pause inside a called agent cannot be replayed).
+#   - {{token}} interpolation does not touch `source`; read `variables`.
+#   - A yaml_reference to a script syndicate runs its whole script as a
+#     subagent, a route or a node, its pauses reaching the turn.
+# script:
+#   models: ["gemini-3.8-flash", "claude-opus-5-5"]
+#   tools: ["web_extract", "publish"]
+#   require_approval: ["publish"]
+#   source: |
+#     export default async ({ message, agent, askUser, log }) => {
+#       const triage = await agent("OrchestratorName", message);
+#       log(`Routed to ${triage.route}`);
+#       return agent(triage.route, null, { conversation: true });
+#     };
+
 # ── Orchestrator ────────────────────────────────────────────
 # The turn's root agent: the engine's agent loop runs it. Its keys are
 # spelled after ADK's LlmAgentConfig.
@@ -293,6 +335,14 @@ orchestrator:
   # Google's server-side sandbox; nothing runs on this host. Gemini only.
   # code_execution: "gemini"
 
+  # [optional] With `run_code` in tools, the agent runs JavaScript in the
+  # engine's QuickJS sandbox on any provider and rests its answer on the
+  # result (no network, no host, no clock; needs MELCHIZEDEK_CODE_SANDBOX=on,
+  # ADR 0137). `attach: true` puts each run's code and result on the reply
+  # as a code_run data part. Default off.
+  # run_code:
+  #   attach: true
+
   # [optional] Summarize a long conversation instead of overflowing the
   # window: past `compact_after_tokens` (the last request's prompt), earlier
   # turns become one summary and the last `keep_recent_events` stay

package/dist/lib/a2a/executor.js

@@ -375,6 +375,24 @@ export function approvalAnswer(rawParts, pending) {
     }
     return undefined;
 }
+/** The `code_runs` artifact: one `code_run` data part per run an attaching agent made (ADR 0137 item 3). */
+function publishCodeRuns(eventBus, taskId, contextId, runs) {
+    eventBus.publish(AgentEvent.artifactUpdate({
+        taskId,
+        contextId,
+        artifact: {
+            artifactId: 'code_runs',
+            name: 'code_runs',
+            description: 'The code the answer rests on, and what it returned',
+            parts: runs.map((run) => ({ content: { $case: 'data', value: run }, metadata: undefined, filename: '', mediaType: 'application/json' })),
+            metadata: undefined,
+            extensions: [],
+        },
+        append: false,
+        lastChunk: true,
+        metadata: undefined,
+    }));
+}
 function publishFinal(eventBus, taskId, contextId, state, text) {
     eventBus.publish(AgentEvent.statusUpdate({
         taskId,
@@ -687,6 +705,9 @@ export class SyndicateExecutor {
                 return;
             }
             log(`✓ Task ${short} complete — ${result.text.length.toLocaleString()} chars, ${spent}`);
+            // run_code's attach (ADR 0137): the code an answer rests on, and its result, as data parts beside it.
+            if (result.codeRuns?.length)
+                publishCodeRuns(eventBus, taskId, contextId, result.codeRuns);
             publishFinal(eventBus, taskId, contextId, 'completed', result.text || undefined);
             await report(ctx, 'completed', undefined, u);
             // Long-term memory: there is no "session end" on a server, so ingest

package/dist/lib/compile.d.ts

@@ -115,9 +115,10 @@ export type SpecTool = {
     dispatch: DispatchSpec;
 };
 /**
- * A nested dispatch (plan-dispatch) syndicate (ADR 0120): it runs as it
- * runs at the top, as a turn of its own on its own conversation (its
- * classifier picks a route, the route answers), so what it compiles to is
+ * A nested dispatch (plan-dispatch) syndicate (ADR 0120), or a nested
+ * script syndicate (ADR 0137 item 15): it runs as it runs at the top, as a
+ * turn of its own on its own conversation (its classifier picks a route and
+ * the route answers, or its script runs), so what it compiles to is
  * the file and the options its turn loads its routes with. The turn runner
  * runs it (lib/runtime/syndicateTurn.ts, TurnControl.nestedDispatch), as a
  * delegated call, a dispatch route or a workflow node.

package/dist/lib/compile.js

@@ -37,6 +37,7 @@
 import { relative } from 'node:path';
 import { isDispatchSyndicate } from './dispatch.js';
 import { isWorkflowSyndicate, nodeKind } from './workflowConfig.js';
+import { isScriptSyndicate } from './script/config.js';
 import { loadSyndicate, nestedLoader } from './loadSyndicate.js';
 import { REASONING_OLDER_SPELLING } from './syndicateSchema.js';
 import { reasoningConfig } from './models/reasoning.js';
@@ -134,7 +135,7 @@ function gateTools(tools, names, agentName) {
 }
 /** True when any agent of a syndicate may pause for approval: a gated tool, or skill scripts. */
 export function declaresApprovals(config) {
-    return agentGates(config.orchestrator) || (config.subagents ?? []).some((s) => agentGates(s));
+    return agentGates(config.orchestrator) || (config.subagents ?? []).some((s) => agentGates(s)) || !!config.script?.require_approval?.length;
 }
 /**
  * An agent's `examples:` as their InstructionTool (lib/tools/examples.ts):
@@ -398,8 +399,9 @@ export async function compileEntrySpec(subCfg, opts = {}, delegated = false) {
         if (isWorkflowSyndicate(nested)) {
             return { kind: 'workflow', workflow: await compileWorkflowSpec(nested, nestedOpts, subCfg.name, subCfg.description, subCfg.yaml_reference, delegated) };
         }
-        // A nested dispatch syndicate classifies and routes as at the top (ADR 0120), wherever it runs.
-        if (isDispatchSyndicate(nested))
+        // A nested dispatch syndicate classifies and routes as at the top (ADR 0120), wherever it runs; a nested script
+        // syndicate runs its whole script the same way, as a turn of its own (ADR 0137 item 15).
+        if (isDispatchSyndicate(nested) || isScriptSyndicate(nested))
             return { kind: 'dispatch', dispatch: compileDispatchEntry(subCfg, nested, nestedOpts) };
         return { kind: 'agent', spec: await compileSpec(nested, nestedOpts, subCfg.name, subCfg.description) };
     }
@@ -437,6 +439,9 @@ export async function compileSubagentSpec(subCfg, opts = {}) {
         if (isDispatchSyndicate(nested)) {
             throw new Error(`${subCfg.yaml_reference}: '${subCfg.name}' is a dispatch syndicate, which runs as its own turn (its classifier, then a route), not as one agent; compile the entry with compileEntrySpec (ADR 0120).`);
         }
+        if (isScriptSyndicate(nested)) {
+            throw new Error(`${subCfg.yaml_reference}: '${subCfg.name}' is a script syndicate, which runs as its own turn (its script), not as one agent; compile the entry with compileEntrySpec (ADR 0137).`);
+        }
         return compileSpec(nested, nestedOpts, subCfg.name, subCfg.description);
     }
     // YAML v2 (ADR 0115): the engine form, for a config built in code (a loaded one already is).

package/dist/lib/doctor.d.ts

@@ -27,6 +27,7 @@ import type { Platform } from './models/endpoints.ts';
 import type { CapabilityGap, CapabilityReport } from './models/capabilities.ts';
 import type { ProviderId } from './models/providerMap.ts';
 import type { RuntimeName, RuntimeSource } from './runtime/runtimeFlag.ts';
+import { type ProjectCheck } from './project.ts';
 /**
  * What a file costs to run: `keyless` (all Ollama), a single provider's id
  * when every agent shares one (`gemini`, `anthropic`, `openai`, `xai` — one
@@ -169,7 +170,16 @@ export interface DoctorResult {
     serving?: DoctorServing;
     /** A stored Sign in with ChatGPT credential (ADR 0126), when one is present or its variables are set. */
     chatgpt?: DoctorChatGpt;
+    /** The project manifest (ADR 0138) found from the working directory, when there is one. */
+    project?: DoctorProject;
 }
+/** A `melchizedek.json` at or above the working directory: its checks, or why it does not load. */
+export type DoctorProject = ProjectCheck | {
+    root: string;
+    error: string;
+    problems: string[];
+    warnings: string[];
+};
 /**
  * A Sign in with ChatGPT credential (ADR 0126): where it is, whether it is
  * signed in and carries OpenAI ids here, and what stops it. Never a token.

package/dist/lib/doctor.js

@@ -42,6 +42,7 @@ import { OAUTH_HOSTS_ENV } from './tools/oauthHosts.js';
 import { CREDENTIAL_HOSTS_ENV, credentialHosts } from './tools/credentialHosts.js';
 import { syndicateCredentialUses } from './tools/credentialUses.js';
 import { credentialHostEnvProblems, unboundCredentialWarning } from './a2a/oauthSetup.js';
+import { checkProject, findProject, isIgnored, ProjectManifestError, resolveAgentsDir } from './project.js';
 /** The `gateway.id` the doctor reports when `MODEL_GATEWAY` names no known gateway; the value itself is never kept. */
 const UNRECOGNISED_GATEWAY = 'unrecognised';
 function resolvable(module) {
@@ -457,10 +458,11 @@ export function flagMemoryNamespaces(syndicates) {
     }
 }
 export function runDoctor(options = {}) {
-    const agentsDir = path.resolve(options.agentsDir ??
-        process.env.MELCHIZEDEK_AGENTS_DIR ??
-        path.join(process.cwd(), 'config', 'agents'));
-    const syndicates = listSyndicateFiles(agentsDir).map((f) => diagnoseSyndicate(f, agentsDir, options.scripts));
+    const agentsDir = resolveAgentsDir(options.agentsDir);
+    const { project, report: projectReport } = projectFromCwd();
+    // The manifest's ignore list applies when the doctor reads the project's own folder.
+    const listed = listSyndicateFiles(agentsDir).filter((f) => !project || agentsDir !== project.agentsDir || !isIgnored(project, path.relative(project.root, path.join(agentsDir, f))));
+    const syndicates = listed.map((f) => diagnoseSyndicate(f, agentsDir, options.scripts));
     // Which single variable unlocks what. A syndicate counts toward a
     // variable only when that variable is ALL it is missing.
     const byEnv = new Map();
@@ -541,8 +543,22 @@ export function runDoctor(options = {}) {
         providers: providerPaths(),
         ...(serving ? { serving } : {}),
         ...(chatgpt ? { chatgpt } : {}),
+        ...(projectReport ? { project: projectReport } : {}),
     };
 }
+/** The project at or above the working directory, checked; a broken manifest becomes a problem, not a throw. */
+function projectFromCwd() {
+    try {
+        const project = findProject();
+        return project ? { project, report: checkProject(project) } : {};
+    }
+    catch (e) {
+        if (!(e instanceof ProjectManifestError))
+            throw e;
+        const problem = `melchizedek.json: ${e.issues.join('; ')}`;
+        return { report: { root: path.dirname(e.file), error: problem, problems: [problem], warnings: [] } };
+    }
+}
 /**
  * The Sign in with ChatGPT line (ADR 0126), when a credential file is present
  * or one of its variables is set. `served`: a serving variable is set, so
@@ -613,6 +629,8 @@ export function checkProblems(result) {
         problems.push(`credentials: ${p}`);
     for (const p of result.chatgpt?.problems ?? [])
         problems.push(`chatgpt: ${p}`);
+    for (const p of result.project?.problems ?? [])
+        problems.push(`project: ${p}`);
     for (const s of result.syndicates) {
         for (const g of s.grants ?? [])
             for (const p of g.hostProblems ?? [])
@@ -635,6 +653,17 @@ export function renderDoctor(result, opts = {}) {
             : `${c.green}${text}${c.reset}`;
     lines.push(`${c.bold}melchizedek doctor${c.reset} ${c.dim}· ${result.agentsDir}${c.reset}`);
     lines.push('');
+    // The project manifest (ADR 0138): the engine pin, and what in it is stale.
+    if (result.project) {
+        const p = result.project;
+        const pin = 'engine' in p ? `${p.engine.matches ? c.green + '✓' : c.red + '✗'}${c.reset} engine ${p.engine.pinned}${p.engine.matches ? '' : `${c.red}, ${p.engine.running} running${c.reset}`} · ${p.syndicates.length} syndicate(s) ` : '';
+        lines.push(`project     ${pin}${c.dim}${p.root}${c.reset}`);
+        for (const x of p.problems)
+            if (!x.startsWith('engine:'))
+                lines.push(`            ${c.red}✗ ${x}${c.reset}`);
+        for (const x of p.warnings)
+            lines.push(`            ${c.yellow}! ${x}${c.reset}`);
+    }
     // The runtime a turn would run on, and where that came from (ADR 0107).
     if (result.runtime) {
         const rt = result.runtime;

package/dist/lib/index.d.ts

@@ -28,6 +28,14 @@ export type { AgentBranch, DrainedRun, MessagePart, TurnUsage, RouteDecision, Sy
 export type { CompileOptions } from './compile.ts';
 export { isWorkflowSyndicate, describeInput } from './workflow.ts';
 export type { WorkflowConfig, WorkflowNodeYaml, EdgeElement, PendingInput } from './workflow.ts';
+export { isScriptSyndicate } from './script/config.ts';
+export type { ScriptConfig } from './script/config.ts';
+export { openRun, runScript, ScriptFatal, SCRIPT_CALL_LIMIT } from './script/run.ts';
+export type { JournalEntry, OpenRun, ScriptCallSite, ScriptHost, ScriptPauseRecord, ScriptPinRecord, ScriptRunInput, ScriptRunOutcome } from './script/run.ts';
+export { CODE_SANDBOX_ENV, CodeSandboxOffError, DEFAULT_SANDBOX_LIMITS, SandboxHalt, codeSandboxEnabled, runInSandbox } from './sandbox/sandbox.ts';
+export type { SandboxLimits, SandboxResult, SandboxRunOptions } from './sandbox/sandbox.ts';
+export { RUN_CODE, runCodeTool } from './tools/runCodeTool.ts';
+export type { CodeRun, RunCodeOutput } from './tools/runCodeTool.ts';
 export { createA2AApp, compileAgentCard, currentRequestContext } from './a2a/app.ts';
 export type { A2AApp, A2AAppOptions, RequestIdentity } from './a2a/app.ts';
 export type { A2AContext } from './a2a/executor.ts';
@@ -59,3 +67,4 @@ export { PROVIDERS, providerForModel, providerKeyPresent, providerStatuses, logP
 export { loadEnv } from './loadEnv.ts';
 export { setCredentialSource, credentialValue } from './models/credentialSource.ts';
 export type { CredentialSource } from './models/credentialSource.ts';
+export { PROJECT_MANIFEST, projectManifestSchema, ProjectManifestError, findProject, findProjectRoot, loadProject, parseProjectManifest, resolveAgentsDir, listProjectSyndicates, checkProject, type Project, type ProjectManifest, type ProjectCheck, } from './project.ts';

package/dist/lib/index.js

@@ -23,6 +23,11 @@ export { DEFAULT_RUNTIME, describeRuntime, RuntimeRemovedError, UnsupportedOnRun
 export { InProcessSessionService } from './runtime/sessions.js';
 export { approvalResponsePart, pendingApproval, APPROVAL_REQUEST } from './runtime/approvals.js';
 export { isWorkflowSyndicate, describeInput } from './workflow.js';
+// SCRIPT orchestration and the code sandbox (ADR 0137).
+export { isScriptSyndicate } from './script/config.js';
+export { openRun, runScript, ScriptFatal, SCRIPT_CALL_LIMIT } from './script/run.js';
+export { CODE_SANDBOX_ENV, CodeSandboxOffError, DEFAULT_SANDBOX_LIMITS, SandboxHalt, codeSandboxEnabled, runInSandbox } from './sandbox/sandbox.js';
+export { RUN_CODE, runCodeTool } from './tools/runCodeTool.js';
 // ── Serve it over A2A, or call a remote A2A agent ───────────────────────────
 export { createA2AApp, compileAgentCard, currentRequestContext } from './a2a/app.js';
 export { callerTokens, firstOf, hashCallerToken, jwtIdentity, parseCallers, scopeSegment, sharedSecret, trustedHeader, } from './a2a/identity.js';
@@ -50,3 +55,5 @@ describeCapabilities, capabilitySummary, planTransport, gatewayConfig, gatewayPr
 export { loadEnv } from './loadEnv.js';
 // Where credentials are read, by environment variable name (ADR 0133).
 export { setCredentialSource, credentialValue } from './models/credentialSource.js';
+// Project manifest, melchizedek.json (ADR 0138).
+export { PROJECT_MANIFEST, projectManifestSchema, ProjectManifestError, findProject, findProjectRoot, loadProject, parseProjectManifest, resolveAgentsDir, listProjectSyndicates, checkProject, } from './project.js';

package/dist/lib/loadSyndicate.d.ts

@@ -11,6 +11,8 @@ export type { SkillsConfig } from './tools/skillToolset.ts';
 import type { WorkflowConfig } from './workflowConfig.ts';
 import type { ReasoningSetting } from './models/contract.ts';
 export type { WorkflowConfig } from './workflowConfig.ts';
+export type { ScriptConfig } from './script/config.ts';
+import type { ScriptConfig } from './script/config.ts';
 export interface ThinkingConfig {
     /** Token budget for internal reasoning. 0 = off, -1 = dynamic. */
     thinkingBudget?: number;
@@ -175,6 +177,10 @@ export interface AgentYamlConfig {
     openapi?: OpenApiConfig[];
     /** `gemini`: the model's Python runs in Gemini's server-side sandbox (ADR 0033). Gemini models only. */
     code_execution?: 'gemini';
+    /** How this agent's `run_code` tool behaves (ADR 0137): `attach` puts each run's code and result on the reply. Needs run_code in `tools`. */
+    run_code?: {
+        attach?: boolean;
+    };
     /** Compact a long conversation into a summary past a token threshold (ADR 0033). Delegate orchestrator only. */
     context?: ContextConfig;
     /** `task`: the agent works until it calls finish_task; its arguments are the node's output. Workflow nodes only. */
@@ -239,6 +245,13 @@ export interface SyndicateYamlConfig {
      * Contract: lib/workflow.ts.
      */
     workflow?: WorkflowConfig;
+    /**
+     * Opts this syndicate into SCRIPT orchestration (ADR 0137): one JavaScript
+     * module, run in the engine's sandbox, calls the agents, the allowed tools
+     * and a person as functions. Cannot be combined with `dispatch` or
+     * `workflow`. Needs MELCHIZEDEK_CODE_SANDBOX=on. Contract: lib/script/.
+     */
+    script?: ScriptConfig;
     /** Optional default variable definitions for {{token}} interpolation. */
     variables?: VariableMap;
     /** Defines the persistence and semantic memory layer for the syndicate. */