@dotdrelle/wiki-manager 0.11.4 → 0.11.6

package/agents.docker-compose.yml

@@ -95,7 +95,7 @@ services:
       - MAILER_REQUIRE_CONFIRMATION=${MAILER_REQUIRE_CONFIRMATION:-true}
       - MAILER_DRY_RUN=${MAILER_DRY_RUN:-false}
       - MCP_AUTH_TOKEN=${MAILER_MCP_AUTH_TOKEN:-}
-    volumes:
-      # Optional: mount a CA bundle and set MAILERSEND_CA_CERT to its container path.
-      #- ${AGENTS_DATA_DIR:-./.agents-data}/certs:/certs:ro
+    # Optional: mount a CA bundle and set MAILERSEND_CA_CERT to its container path.
+    # volumes:
+    #   - ${AGENTS_DATA_DIR:-./.agents-data}/certs:/certs:ro
     restart: unless-stopped

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdrelle/wiki-manager",
-  "version": "0.11.4",
+  "version": "0.11.6",
   "description": "Agentic shell and orchestration cockpit for llm-wiki workspaces.",
   "license": "PolyForm-Noncommercial-1.0.0",
   "author": "dotrelle",
@@ -11,7 +11,7 @@
   },
   "scripts": {
     "start": "bun ./bin/wiki-manager.js",
-    "test": "node --test src/agent/graph.test.js src/contracts/schemas.test.js src/core/activity.test.js src/core/agentEvents.test.js src/core/workflow.test.js src/core/planPatch.test.js src/core/agentLoop.test.js src/core/plan.test.js src/core/mcp.test.js src/core/documentIntake.test.js src/core/dockerCompose.test.js src/core/wikiWorkspace.test.js src/core/wikirc.test.js src/core/modelFetch.test.js src/core/startupCheck.test.js src/core/queueStore.test.js src/commands/slash.test.js src/shell/repl.test.js src/runtime/store.test.js src/runtime/server.test.js src/runtime/supervisor.test.js src/runtime/runner.test.js src/runtime/runner.e2e.test.js src/runtime/auth.test.js",
+    "test": "node --test src/agent/graph.test.js src/contracts/schemas.test.js src/core/activity.test.js src/core/agentEvents.test.js src/core/workflow.test.js src/core/planPatch.test.js src/core/agentLoop.test.js src/core/plan.test.js src/core/mcp.test.js src/core/documentIntake.test.js src/core/dockerCompose.test.js src/core/wikiWorkspace.test.js src/core/wikirc.test.js src/core/modelFetch.test.js src/core/startupCheck.test.js src/core/queueStore.test.js src/commands/slash.test.js src/shell/repl.test.js src/runtime/store.test.js src/runtime/server.test.js src/runtime/supervisor.test.js src/runtime/runner.test.js src/runtime/runner.e2e.test.js src/runtime/donna-contract.test.js src/runtime/auth.test.js",
     "check-versions": "node scripts/check-versions.js",
     "prepack": "node scripts/check-versions.js",
     "prepublishOnly": "node scripts/check-versions.js",

package/src/agent/graph.js

@@ -14,6 +14,37 @@ import { enqueueProductionJob, ensureJobQueue, formatQueue, productionLockBusy }
 
 const MAX_TOOL_ITERATIONS = 80;
 const MAX_SPINNER_ARG_LENGTH = 96;
+
+// Deterministic guard: on the first turn of a fresh /agent input, only bind
+// job-starting/mutating MCP tools when the raw text actually looks like an
+// action request. Plain chat (greetings, thanks, small talk) never sees those
+// tools bound, so the LLM cannot start a production job/plan from a "salut" —
+// prompting alone was not reliable enough (see plan-directeur history).
+const ACTION_INTENT_RE = /\b(lance|lancer|lancez|d[ée]marre|d[ée]marrer|d[ée]marrez|ex[ée]cute|ex[ée]cuter|exporte|exporter|export|importe|importer|import|g[ée]n[èe]re|g[ée]n[ée]rer|g[ée]n[ée]ration|cr[ée]e|cr[ée]er|construis|build|run|start|launch|deploy|d[ée]ploie|d[ée]ployer|d[ée]ploiement|publie|publier|publish|publication|synchronise|synchroniser|sync|convertis|convertir|convert|envoie|envoyer|send|configure|configurer|ajoute|ajouter|add|planifie|planifier|schedule|ingest|ing[èe]re|ing[èe]rer|ingestion|polish|pipeline|skill|job|t[âa]che|workflow|refais|relance|retente|retry)\b/i;
+const READ_ONLY_TOOL_NAME_RE = /(^|_)(list|status|get|read|describe|show|search|find)(_|$)/i;
+
+function isReadOnlyToolName(name) {
+  return READ_ONLY_TOOL_NAME_RE.test(String(name ?? ''));
+}
+
+function filterToolsForChatOnlyTurn(tools) {
+  return [
+    SHELL_READ_COMMAND_TOOL,
+    ...tools.filter((tool) => isReadOnlyToolName(tool?.function?.name ?? '')),
+  ];
+}
+
+function toolsForDonnaTurn(input, tools, iterations) {
+  if (iterations !== 0) return tools;
+  const text = String(input ?? '');
+  if (ACTION_INTENT_RE.test(text)) return tools;
+  // Plain chat (no action, no read intent) still gets the minimal read-only
+  // set, never an empty array: the system prompt unconditionally describes
+  // the connected MCP tools regardless of what's actually bound this turn,
+  // and sending zero tools while the prompt talks about them confuses some
+  // models into an empty/malformed completion instead of a plain reply.
+  return filterToolsForChatOnlyTurn(tools);
+}
 const AGENT_SLASH_COMMANDS = new Set([
   'help',
   'version',
@@ -51,6 +82,29 @@ const SHELL_RUN_COMMAND_TOOL = {
   },
 };
 
+const SHELL_READ_COMMAND_TOOL = {
+  type: 'function',
+  function: {
+    name: 'shell__read_command',
+    description: [
+      'Run a read-only deterministic wiki-manager slash command inside the current shell session.',
+      'Allowed commands: /help, /version, /config, /config list, /config status, /status, /services, /skills, /skills list, /skills show <name>, /uploads, /uploads list, /queue.',
+      'Do not use for workspace creation/deletion, uploads conversion, service start/stop, MCP calls, wiki runs, or any mutation.',
+    ].join(' '),
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        command: {
+          type: 'string',
+          description: 'Read-only slash command to run, for example "/status", "/config status", or "/services".',
+        },
+      },
+      required: ['command'],
+    },
+  },
+};
+
 const WIKI_PLAN_SET_TOOL = {
   type: 'function',
   function: {
@@ -238,6 +292,24 @@ function assertAgentSlashCommandAllowed(commandLine) {
   }
 }
 
+function assertAgentReadSlashCommandAllowed(commandLine) {
+  const parts = commandLine.slice(1).trim().split(/\s+/).filter(Boolean);
+  const command = parts[0] ?? '';
+  const subcommand = parts[1] ?? '';
+  const allowed =
+    command === 'help' ||
+    command === 'version' ||
+    command === 'status' ||
+    command === 'services' ||
+    command === 'queue' ||
+    (command === 'config' && ['', 'list', 'status'].includes(subcommand)) ||
+    (command === 'skills' && ['', 'list', 'show'].includes(subcommand)) ||
+    (command === 'uploads' && ['', 'list'].includes(subcommand));
+  if (!allowed) {
+    throw new Error(`Read-only command is not available to the agent: /${parts.join(' ')}`);
+  }
+}
+
 function withActiveWorkspaceForExternalTool(session, server, tool, args) {
   const needsWorkspace =
     (server === 'documents' && tool.startsWith('documents_') && tool !== 'documents_status') ||
@@ -269,6 +341,21 @@ async function runShellCommandTool(session, commandLine) {
   return result.output ?? 'Command completed.';
 }
 
+async function runShellReadCommandTool(session, commandLine) {
+  const command = normalizeShellCommand(commandLine);
+  assertAgentReadSlashCommandAllowed(command);
+  session._onStep?.(`Shell: ${command}`);
+  const result = await handleSlashCommand(command, {
+    packageJson: session.packageJson ?? { version: '0.0.0' },
+    session,
+    onStep: session._onStep,
+  });
+  if (result.exit) {
+    throw new Error('/exit is not available to the agent.');
+  }
+  return result.output ?? 'Command completed.';
+}
+
 function rememberProductionProgress(session, payload, label) {
   const job = payload?.job;
   const jobId = payload?.jobId ?? job?.jobId;
@@ -434,6 +521,7 @@ export function buildAgentSystemPrompt(state) {
   const agentContext = [
     'You are Donna, the terminal orchestrator agent for llm-wiki-manager.',
     'The shell is agent-first: every input without a leading slash is routed to you.',
+    'Default to a plain conversational reply with no tool call. Only call a tool, create a plan, or start a job when the user\'s message clearly requests an action (ingest, build, export, configure, run a skill, check a concrete status, etc.). Greetings, small talk, thanks, and general questions do not warrant starting a job or calling a tool — just answer in text.',
     'Commands starting with / are deterministic primitives. You may run a safe subset through shell__run_command.',
     `Reply language: ${language}.`,
     `Current workspace: ${workspace}.`,
@@ -512,12 +600,17 @@ export function buildLimitedAgentResponse(state, reason = 'no workspace loaded w
   ].join('\n');
 }
 
+export function formatLlmUnavailableMessage(reason) {
+  const clean = String(reason ?? 'raison inconnue').replace(/\s+/g, ' ').trim();
+  return `⚠ LLM injoignable : ${clean || 'raison inconnue'}`;
+}
+
 export function createAgentGraph(options = {}) {
   async function orchestratorNode(state) {
     const llm = state.session.llm ?? options.llm ?? null;
 
     if (!llm) {
-      return { response: buildLimitedAgentResponse(state), pendingToolCalls: null, readyToStream: false };
+      return { response: formatLlmUnavailableMessage('aucun client LLM configure'), pendingToolCalls: null, readyToStream: false };
     }
 
     const iterations = state.toolIterations ?? 0;
@@ -535,12 +628,13 @@ export function createAgentGraph(options = {}) {
       state.session._onStep?.('Agent: planning next action…');
     }
 
-    const tools = [
+    const allTools = [
       SHELL_RUN_COMMAND_TOOL,
       WIKI_PLAN_SET_TOOL,
       WIKI_PLAN_DONE_TOOL,
       ...buildLlmTools(state.session.mcp),
     ];
+    const tools = toolsForDonnaTurn(state.input, allTools, iterations);
     const system = buildAgentSystemPrompt(state);
 
     // On iteration 0: prior history is in state.messages, user input must be appended.
@@ -619,7 +713,7 @@ export function createAgentGraph(options = {}) {
     } catch (err) {
       if (err.name === 'AbortError') throw err;
       const message = err instanceof Error ? err.message : String(err);
-      return { response: buildLimitedAgentResponse(state, `LLM unavailable: ${message}`), pendingToolCalls: null, readyToStream: false };
+      return { response: formatLlmUnavailableMessage(message), pendingToolCalls: null, readyToStream: false };
     }
   }
 
@@ -663,6 +757,8 @@ export function createAgentGraph(options = {}) {
         } else if (server === 'shell' && tool === 'run_command') {
           await awaitRunApproval(state.session, { runId, tool: toolName });
           resultText = await runShellCommandTool(state.session, args.command);
+        } else if (server === 'shell' && tool === 'read_command') {
+          resultText = await runShellReadCommandTool(state.session, args.command);
         } else if (server !== 'shell') {
           await awaitRunApproval(state.session, { runId, tool: toolName });
           await awaitToolApproval(state.session, {

package/src/agent/graph.test.js

@@ -99,6 +99,87 @@ test('agent graph waits for run-level approval before first MCP action', async (
   }
 });
 
+test('agent graph reports LLM unavailable without Donna active boilerplate', async () => {
+  const agent = createAgentGraph();
+  const result = await agent.invoke({ input: 'salut', session: sessionBase({ llm: null }) });
+
+  assert.equal(result.response, '⚠ LLM injoignable : aucun client LLM configure');
+  assert.doesNotMatch(result.response, /Donna is active/);
+});
+
+test('agent graph binds only the minimal read-only tool set for plain discussion, never an empty array', async () => {
+  const seenTools = [];
+  const session = sessionBase({
+    llm: {
+      async completeWithTools({ tools }) {
+        seenTools.push(...tools.map((tool) => tool.function.name));
+        return {
+          content: 'Salut, je suis là.',
+          message: { role: 'assistant', content: 'Salut, je suis là.' },
+          tool_calls: null,
+        };
+      },
+    },
+  });
+
+  const agent = createAgentGraph();
+  const result = await agent.invoke({ input: 'salut', session });
+
+  assert.equal(result.response, 'Salut, je suis là.');
+  // Never literally empty: the system prompt unconditionally describes the
+  // connected MCP tools, and sending zero tools while the prompt talks about
+  // them risks an empty/malformed completion from some models instead of a
+  // plain reply — this is what actually broke plain "salut" discussion.
+  assert.ok(seenTools.length > 0);
+  assert.deepEqual(seenTools, ['shell__read_command']);
+  assert.equal(session.headlessPlan ?? null, null);
+  assert.equal(Object.keys(session.activities ?? {}).length, 0);
+});
+
+test('agent graph binds read-only tools for config questions without plan tools', async () => {
+  const seenTools = [];
+  const session = sessionBase({
+    mcp: {
+      production: {
+        status: 'connected',
+        url: 'http://127.0.0.1:3000/mcp/',
+        tools: [
+          {
+            name: 'production_start_job',
+            description: 'Start production job',
+            inputSchema: { type: 'object', properties: { type: { type: 'string' } } },
+          },
+          {
+            name: 'production_job_status',
+            description: 'Read production job status',
+            inputSchema: { type: 'object', properties: { jobId: { type: 'string' } } },
+          },
+        ],
+      },
+    },
+    llm: {
+      async completeWithTools({ tools }) {
+        seenTools.push(...tools.map((tool) => tool.function.name));
+        return {
+          content: 'Le profil actif est docs.',
+          message: { role: 'assistant', content: 'Le profil actif est docs.' },
+          tool_calls: null,
+        };
+      },
+    },
+  });
+
+  const agent = createAgentGraph();
+  const result = await agent.invoke({ input: 'quel est le profil actif ?', session });
+
+  assert.equal(result.response, 'Le profil actif est docs.');
+  assert.ok(seenTools.includes('shell__read_command'));
+  assert.ok(seenTools.includes('production__production_job_status'));
+  assert.equal(seenTools.includes('wiki__plan_set'), false);
+  assert.equal(seenTools.includes('production__production_start_job'), false);
+  assert.equal(seenTools.includes('shell__run_command'), false);
+});
+
 test('agent graph waits for tool-level approval configured on endpoint', async () => {
   const originalFetch = globalThis.fetch;
   globalThis.fetch = async () => ({

package/src/cli/wiki-manager.js

@@ -29,6 +29,11 @@ function valueAfter(argv, flag) {
   return argv[index + 1];
 }
 
+function unavailableRuntime(err) {
+  const reason = err instanceof Error ? err.message : String(err);
+  return { url: null, error: reason };
+}
+
 function createSession() {
   return {
     workspace: null,
@@ -745,7 +750,8 @@ export async function runCli(argv) {
       const { ensureRuntime } = await import('../runtime/lifecycle.js');
       runtime = await ensureRuntime();
     } catch (err) {
-      console.error(`Runtime unavailable: ${err instanceof Error ? err.message : String(err)}`);
+      runtime = unavailableRuntime(err);
+      console.error(`Runtime unavailable: ${runtime.error}`);
     }
     await runOpenTuiShell({ agent, packageJson, runtime });
     return;
@@ -757,7 +763,8 @@ export async function runCli(argv) {
       const { ensureRuntime } = await import('../runtime/lifecycle.js');
       runtime = await ensureRuntime();
     } catch (err) {
-      console.error(`Runtime unavailable: ${err instanceof Error ? err.message : String(err)}`);
+      runtime = unavailableRuntime(err);
+      console.error(`Runtime unavailable: ${runtime.error}`);
     }
   }
   await runShell({ agent, packageJson, runtime });

package/src/core/agentLoop.js

@@ -1,8 +1,8 @@
-import { buildAgentSystemPrompt, buildLimitedAgentResponse } from '../agent/graph.js';
+import { buildAgentSystemPrompt, formatLlmUnavailableMessage } from '../agent/graph.js';
 import { createAgentEvent, dispatchAgentEvent } from './agentEvents.js';
 import { activitySnapshot, newNonTerminalActivities } from './activity.js';
 import { extractHeadlessPlan, formatCompletedActivities, formatPlanStatus } from './plan.js';
-import { formatReadyTaskPrompt, nextReadyPlanTask, readyPlanTasks } from './planPatch.js';
+import { formatReadyTaskPrompt, nextReadyPlanTask, readyPlanTasks, sanitizePlanForExecution } from './planPatch.js';
 
 export function abortError(message = 'Agent run cancelled.') {
   const err = new Error(message);
@@ -31,7 +31,7 @@ export async function runAgentTurn(agent, session, input, {
     if (session._abortSignal === signal) delete session._abortSignal;
   }
   if (result.streamedInline) {
-    return streamedContent.trim() || buildLimitedAgentResponse({ input, session }, 'LLM stream ended without content');
+    return streamedContent.trim() || formatLlmUnavailableMessage('flux vide');
   }
   if (result.response != null) return result.response;
   if (result.readyToStream && session.llm?.stream) {
@@ -44,9 +44,9 @@ export async function runAgentTurn(agent, session, input, {
     })) {
       content += delta;
     }
-    return content.trim() || buildLimitedAgentResponse({ input, session }, 'LLM stream ended without content');
+    return content.trim() || formatLlmUnavailableMessage('flux vide');
   }
-  return buildLimitedAgentResponse({ input, session });
+  return formatLlmUnavailableMessage('reponse vide');
 }
 
 export async function runAgenticLoop(agent, session, initialInput, {
@@ -109,6 +109,7 @@ export async function runAgenticLoop(agent, session, initialInput, {
         onPlanAlreadySet?.({ steps: session.headlessPlan });
       }
     }
+    sanitizeSessionPlan(session, { runId });
 
     const newPending = newNonTerminalActivities(snapshot, session);
     if (newPending.length === 0) {
@@ -158,6 +159,20 @@ export async function runAgenticLoop(agent, session, initialInput, {
   return { ok: false, maxTurns: true };
 }
 
+function sanitizeSessionPlan(session, { runId = null } = {}) {
+  if (!session.headlessPlan) return;
+  const sanitized = sanitizePlanForExecution(session.headlessPlan);
+  if (sanitized.warnings.length === 0) return;
+  session.headlessPlan = sanitized.plan;
+  dispatchAgentEvent(session, createAgentEvent('runtime_log', {
+    origin: 'runtime',
+    runId,
+    payload: {
+      message: `plan warning: ${sanitized.warnings.join('; ')}`,
+    },
+  }));
+}
+
 function pendingStepsPrompt(initialInput, plan, readyTask) {
   return [
     'Original task:',

package/src/core/agentLoop.test.js

@@ -1,7 +1,25 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 import { createAgentEvent, dispatchAgentEvent } from './agentEvents.js';
-import { runAgenticLoop } from './agentLoop.js';
+import { runAgentTurn, runAgenticLoop } from './agentLoop.js';
+
+test('runAgentTurn returns a one-line LLM error on empty stream', async () => {
+  const session = {
+    commands: [],
+    llm: {
+      async *stream() {},
+    },
+  };
+  const agent = {
+    async invoke() {
+      return { readyToStream: true, streamContext: { messages: [] } };
+    },
+  };
+
+  const response = await runAgentTurn(agent, session, 'salut');
+
+  assert.equal(response, '⚠ LLM injoignable : flux vide');
+});
 
 test('runAgenticLoop waits for new activities and continues with a completion summary', async () => {
   const session = {

package/src/core/mcp.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { managerEnvFile, managerMcpEndpointsFile, readEnvFile } from './env.js';
 
-const WIKI_MANAGER_VERSION = '0.11.4';
+const WIKI_MANAGER_VERSION = '0.11.6';
 
 function envValue(key) {
   const filePath = managerEnvFile();

package/src/core/planPatch.js

@@ -86,7 +86,7 @@ export function rebasePlanPatch(patch, { currentRevision = 0 } = {}) {
 }
 
 export function readyPlanTasks(plan) {
-  const tasks = (plan ?? []).map((step, index) => normalizeTask(step, index));
+  const { plan: tasks } = sanitizePlanForExecution(plan);
   const done = new Set(tasks.filter((task) => task.status === 'done').map(taskId));
   return tasks
     .filter((task) => task.status === 'pending')
@@ -125,6 +125,36 @@ export function normalizeTask(raw, index = 0) {
   };
 }
 
+export function sanitizePlanForExecution(plan) {
+  const tasks = (plan ?? []).map((step, index) => normalizeTask(step, index));
+  const warnings = [];
+  const ids = new Set(tasks.map(taskId));
+  for (const task of tasks) {
+    const before = task.dependsOn;
+    task.dependsOn = before.filter((dep) => ids.has(String(dep)));
+    if (task.dependsOn.length !== before.length) {
+      warnings.push(`unknown dependency removed from task ${taskId(task)}`);
+    }
+  }
+  const pending = tasks.filter((task) => task.status === 'pending');
+  const done = new Set(tasks.filter((task) => task.status === 'done').map(taskId));
+  const terminalBlocked = new Set(
+    tasks
+      .filter((task) => ['failed', 'cancelled', 'canceled'].includes(String(task.status).toLowerCase()))
+      .map(taskId),
+  );
+  const hasReady = pending.some((task) => task.dependsOn.every((dep) => done.has(String(dep))));
+  if (hasDependencyCycle(tasks)) {
+    warnings.push('dependency cycle broken by sequential fallback');
+    return { plan: sequentialize(tasks), warnings };
+  }
+  if (pending.length > 0 && !hasReady && !pending.some((task) => task.dependsOn.some((dep) => terminalBlocked.has(String(dep))))) {
+    warnings.push('no ready task after dependency cleanup; using sequential fallback');
+    return { plan: sequentialize(tasks), warnings };
+  }
+  return { plan: tasks, warnings };
+}
+
 function normalizePatchOperation(raw) {
   if (!raw || typeof raw !== 'object') return null;
   const op = String(raw.op ?? '');
@@ -198,6 +228,14 @@ function resequence(plan) {
   });
 }
 
+function sequentialize(plan) {
+  const next = plan.map((task) => ({ ...task, dependsOn: [] }));
+  for (let index = 1; index < next.length; index += 1) {
+    next[index].dependsOn = [taskId(next[index - 1])];
+  }
+  return next;
+}
+
 function hasDependencyCycle(plan) {
   const tasks = new Map(plan.map((task) => [taskId(task), task]));
   const visiting = new Set();

package/src/core/planPatch.test.js

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { applyPlanPatch, nextReadyPlanTask, readyPlanTasks, rebasePlanPatch } from './planPatch.js';
+import { applyPlanPatch, nextReadyPlanTask, readyPlanTasks, rebasePlanPatch, sanitizePlanForExecution } from './planPatch.js';
 
 test('applyPlanPatch adds a task and increments the plan revision', () => {
   const result = applyPlanPatch([
@@ -61,3 +61,25 @@ test('applyPlanPatch rejects dependency cycles', () => {
   assert.equal(result.ok, false);
   assert.equal(result.reason, 'dependency_cycle');
 });
+
+test('sanitizePlanForExecution removes unknown dependencies and keeps execution sequential', () => {
+  const result = sanitizePlanForExecution([
+    { step: 1, id: 'a', description: 'A', status: 'pending', dependsOn: ['missing'] },
+    { step: 2, id: 'b', description: 'B', status: 'pending', dependsOn: ['a'] },
+  ]);
+
+  assert.deepEqual(result.plan.map((task) => task.dependsOn), [[], ['a']]);
+  assert.match(result.warnings.join('\n'), /unknown dependency/);
+  assert.deepEqual(readyPlanTasks(result.plan).map((task) => task.id), ['a']);
+});
+
+test('sanitizePlanForExecution breaks cycles with declaration-order fallback', () => {
+  const result = sanitizePlanForExecution([
+    { step: 1, id: 'a', description: 'A', status: 'pending', dependsOn: ['b'] },
+    { step: 2, id: 'b', description: 'B', status: 'pending', dependsOn: ['a'] },
+  ]);
+
+  assert.deepEqual(result.plan.map((task) => task.dependsOn), [[], ['a']]);
+  assert.match(result.warnings.join('\n'), /cycle/);
+  assert.deepEqual(readyPlanTasks(result.plan).map((task) => task.id), ['a']);
+});

package/src/runtime/client.js

@@ -97,6 +97,18 @@ export async function postRuntimeCancel({
   return response.json();
 }
 
+export async function postRuntimeShutdown({
+  url = runtimeUrlFromEnv(),
+  token = runtimeToken(),
+} = {}) {
+  const response = await fetch(runtimeEndpoint(url, '/shutdown'), {
+    method: 'POST',
+    headers: runtimeHeaders(token),
+  });
+  if (!response.ok) throw new Error(`Runtime shutdown failed: HTTP ${response.status}`);
+  return response.json();
+}
+
 export async function postRuntimeResume({
   url = runtimeUrlFromEnv(),
   token = runtimeToken(),