@dotdrelle/wiki-manager 0.15.43 → 0.15.48

package/src/core/skillCompiler.test.js

@@ -0,0 +1,91 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { compileSkillObjectives, createSkillCompilerFallback, deterministicObjectives, validateCompiledObjectives } from './skillCompiler.js';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseFrontmatter } from './skills.js';
+
+test('numbered and bullet lists are strong objective boundaries', () => {
+  assert.equal(deterministicObjectives('1. Export source\n2. Ingest files').objectives.length, 2);
+  assert.equal(deterministicObjectives('- Export source\n- Ingest files').objectives.length, 2);
+});
+
+test('paragraphs preserve one delegable intention while Puis splits', async () => {
+  assert.equal((await compileSkillObjectives({ body: 'Run the complete pipeline.\n\nInclude indexing.\n\nReport it.' })).length, 1);
+  assert.equal((await compileSkillObjectives({ body: 'Exporter la source.\n\nPuis ingérer les fichiers.' })).length, 2);
+});
+
+test('optional objectives continue on failure', async () => {
+  const result = await compileSkillObjectives({ body: 'Export source.\n\nOptionnellement, envoyer une notification.' });
+  assert.equal(result[1].optional, true);
+  assert.equal(result[1].continueOnFailure, true);
+});
+
+test('compiler appends natural parameters without teaching placeholders', async () => {
+  const [objective] = await compileSkillObjectives({ body: 'Build the deliverable.' }, { template: 'architecture' });
+  assert.match(objective.text, /User parameters:\ntemplate: architecture/);
+});
+
+test('validation rejects technical routing details', () => {
+  assert.throws(() => validateCompiledObjectives([{ text: 'agent: cme' }]), { code: 'skill_compile_failed' });
+});
+
+test('scaffold skills preserve existing capabilities and split only wiki-sync', async () => {
+  const expected = { pipeline: 1, 'wiki-ingest': 1, 'wiki-build': 1, deliver: 1, diagnose: 1, status: 1, 'new-template': 1, 'wiki-sync': 2 };
+  for (const [name, count] of Object.entries(expected)) {
+    const raw = readFileSync(resolve('../llm-wiki/scaffold/workspace/.wiki/skills', `${name}.md`), 'utf8');
+    const { meta, body } = parseFrontmatter(raw);
+    assert.equal((await compileSkillObjectives({ ...meta, body })).length, count, name);
+  }
+});
+
+test('LLM fallback degrades from missing tool calls to validated JSON text', async () => {
+  let calls = 0;
+  const fallback = createSkillCompilerFallback({ completeWithTools: async ({ tools }) => {
+    calls += 1;
+    return tools.length ? { content: null, tool_calls: null } : { content: '{"objectives":[{"text":"Do the coherent workflow."}]}' };
+  } });
+  assert.equal(await fallback({ body: 'ambiguous', maxObjectives: 12 }), '{"objectives":[{"text":"Do the coherent workflow."}]}');
+  assert.equal(calls, 2);
+});
+
+test('every objective of a chain carries the user parameters, not just the last', async () => {
+  // Appending the parameters before splitting attached `source` to the ingest
+  // step and left the export step — the one that consumes it — without it.
+  const skill = {
+    name: 'wiki-sync',
+    params: ['source'],
+    body: 'Export the requested source.\n\nThen ingest what was exported.',
+  };
+  const objectives = await compileSkillObjectives(skill, { source: 'ESPACE-CONF' });
+  assert.equal(objectives.length, 2);
+  for (const objective of objectives) {
+    assert.match(objective.text, /User parameters:\nsource: ESPACE-CONF/);
+  }
+  assert.match(objectives[0].text, /^Export the requested source\./);
+});
+
+test('a parameter named after a routing field does not fail validation', async () => {
+  // The routing guard judges the authored intention, not what the caller typed.
+  const objectives = await compileSkillObjectives(
+    { name: 'x', params: ['agent'], body: 'Do the thing.' },
+    { agent: 'production' },
+  );
+  assert.equal(objectives.length, 1);
+  assert.match(objectives[0].text, /agent: production/);
+});
+
+test('LLM fallback sees authored prose and parameters are appended exactly once', async () => {
+  let fallbackBody = null;
+  const objectives = await compileSkillObjectives(
+    { body: 'Please export the source. Please build the result. Please send the report.' },
+    { source: 'SPACE' },
+    { llmFallback: async ({ body }) => {
+      fallbackBody = body;
+      return [{ text: body }];
+    } },
+  );
+  assert.doesNotMatch(fallbackBody, /User parameters:/);
+  assert.equal(objectives[0].text.match(/User parameters:/g)?.length, 1);
+  assert.equal(objectives[0].text.match(/source: SPACE/g)?.length, 1);
+});

package/src/core/skillInvocation.js

@@ -0,0 +1,79 @@
+import { findSkill } from './skills.js';
+
+const INVOCATION_RE = /^\/([A-Za-z0-9_-]+)(?:\s+([\s\S]*))?$/;
+export const RESERVED_SLASH_COMMANDS = new Set(['status', 'stop', 'run', 'queue', 'skills', 'help', 'exit', 'quit', 'chat', 'agent']);
+
+export function explicitSkillReference(input, skillName, language = null) {
+  const name = escapeRegExp(String(skillName ?? '').trim());
+  if (!name) return false;
+  const primary = String(language ?? '').toLowerCase().split(/[-_]/)[0];
+  if (!['en', 'fr'].includes(primary)) return false;
+  const text = String(input ?? '').split(/[.!?\n]/).map((part) => part.trim()).filter(Boolean);
+  const keyword = '(?:skill|workflow)';
+  const patterns = [
+    new RegExp(`\\b${keyword}\\s+${name}\\b`, 'i'),
+    new RegExp(`\\b${name}\\s+${keyword}\\b`, 'i'),
+    new RegExp(`/skills\\s+run\\s+${name}\\b`, 'i'),
+    new RegExp(`/${name}\\s+(?:comme|as)\\s+${keyword}\\b`, 'i'),
+  ];
+  return text.some((sentence) => patterns.some((pattern) => pattern.test(sentence)));
+}
+
+export function matchSkillInvocation(session, input, { allowReserved = false } = {}) {
+  const match = INVOCATION_RE.exec(String(input ?? '').trim());
+  if (!match) return null;
+  if (!allowReserved && RESERVED_SLASH_COMMANDS.has(match[1].toLowerCase())) return null;
+  const skill = findSkill(session, match[1]);
+  return skill ? { skill, rawArgs: String(match[2] ?? '').trim(), input: String(input ?? '').trim() } : null;
+}
+
+export function parseSkillArguments(skill, rawArgs = '') {
+  const params = Array.isArray(skill?.params) ? skill.params : [];
+  if (params.length === 0) return {};
+  if (params.length === 1) return { [params[0]]: unquote(String(rawArgs).trim()) };
+  const tokens = tokenizeArguments(rawArgs);
+  return Object.fromEntries(params.map((param, index) => [param, index === params.length - 1 ? tokens.slice(index).join(' ') : (tokens[index] ?? '')]));
+}
+
+export function applyLegacySkillPlaceholders(body, args) {
+  let text = String(body ?? '');
+  const used = [];
+  for (const [name, value] of Object.entries(args ?? {})) {
+    const marker = `{${name}}`;
+    if (!text.includes(marker)) continue;
+    text = text.replaceAll(marker, String(value ?? ''));
+    used.push(name);
+  }
+  return { body: text, deprecatedPlaceholders: used };
+}
+
+function tokenizeArguments(raw) {
+  const tokens = [];
+  let current = '';
+  let quote = null;
+  let escaped = false;
+  for (const char of String(raw ?? '').trim()) {
+    if (escaped) { current += char; escaped = false; }
+    else if (char === '\\') escaped = true;
+    else if (quote) { if (char === quote) quote = null; else current += char; }
+    else if (char === '"' || char === "'") quote = char;
+    else if (/\s/.test(char)) { if (current) { tokens.push(current); current = ''; } }
+    else current += char;
+  }
+  if (escaped) current += '\\';
+  if (quote) {
+    const error = new Error('Unterminated quoted skill argument. Close the quote and retry.');
+    error.code = 'skill_arguments_invalid';
+    throw error;
+  }
+  if (current) tokens.push(current);
+  return tokens;
+}
+
+function unquote(value) {
+  return value.length >= 2 && ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) ? value.slice(1, -1) : value;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/core/skillInvocation.test.js

@@ -0,0 +1,73 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { applyLegacySkillPlaceholders, explicitSkillReference, matchSkillInvocation, parseSkillArguments } from './skillInvocation.js';
+import { formatSkillsForAgent, inspectSkills } from './skills.js';
+
+test('matchSkillInvocation resolves only a real workspace skill', () => {
+  const root = mkdtempSync(join(tmpdir(), 'skill-invocation-'));
+  mkdirSync(join(root, '.wiki', 'skills'), { recursive: true });
+  writeFileSync(join(root, '.wiki', 'skills', 'deliver.md'), '---\nname: deliver\nparams:\n  - template\n  - polish\n---\nDeliver.');
+  const match = matchSkillInvocation({ workspacePath: root }, '/deliver "architecture" "improve security"');
+  assert.equal(match.skill.name, 'deliver');
+  assert.equal(match.rawArgs, '"architecture" "improve security"');
+  assert.equal(matchSkillInvocation({ workspacePath: root }, '/status'), null);
+});
+
+test('parseSkillArguments preserves one free-form argument and parses quoted multi params', () => {
+  assert.deepEqual(parseSkillArguments({ params: ['files'] }, 'document A.md document B.md'), { files: 'document A.md document B.md' });
+  assert.deepEqual(parseSkillArguments({ params: ['template', 'polish'] }, '"architecture-juno" "améliorer la sécurité réseau"'), { template: 'architecture-juno', polish: 'améliorer la sécurité réseau' });
+});
+
+test('legacy placeholders remain supported and are reported', () => {
+  assert.deepEqual(applyLegacySkillPlaceholders('Sync {source}.', { source: 'CME' }), { body: 'Sync CME.', deprecatedPlaceholders: ['source'] });
+});
+
+test('reserved skill references require an explicit skill or workflow designation', () => {
+  assert.equal(explicitSkillReference('lance le skill status', 'status', 'fr-FR'), true);
+  assert.equal(explicitSkillReference('/status comme skill', 'status', 'fr-FR'), true);
+  assert.equal(explicitSkillReference('/skills run status', 'status', 'en-US'), true);
+  assert.equal(explicitSkillReference('What is the status of the current run?', 'status', 'en-US'), false);
+  assert.equal(explicitSkillReference('lance /status', 'status', 'fr-FR'), false);
+  assert.equal(explicitSkillReference('lance le skill status', 'status', 'de-DE'), false);
+  assert.equal(explicitSkillReference('run the status skill', 'status'), false);
+});
+
+test('inspectSkills rejects invalid parameters and case-insensitive name collisions with relative paths', () => {
+  const root = mkdtempSync(join(tmpdir(), 'skill-inspection-'));
+  const dir = join(root, '.wiki', 'skills');
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'one.md'), '---\nname: Build\ndescription: First\n---\nOne.');
+  writeFileSync(join(dir, 'two.md'), '---\nname: build\ndescription: Second\n---\nTwo.');
+  writeFileSync(join(dir, 'bad.md'), '---\nname: bad\nparams:\n  - __proto__\n---\nBad.');
+  const result = inspectSkills({ workspacePath: root });
+  assert.equal(result.skills.length, 0);
+  assert.deepEqual(result.rejected.map((item) => item.reason).sort(), ['duplicate_name', 'duplicate_name', 'invalid_param']);
+  assert.equal(result.rejected.every((item) => !item.relativePath.startsWith('/')), true);
+});
+
+test('skills declare whether execution is orchestrated or direct', () => {
+  const root = mkdtempSync(join(tmpdir(), 'skill-execution-'));
+  const dir = join(root, '.wiki', 'skills');
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'direct.md'), '---\nname: direct\ndescription: Direct action\nexecution: direct\n---\nAct directly.');
+  writeFileSync(join(dir, 'default.md'), '---\nname: default\ndescription: Delegated action\n---\nDelegate when needed.');
+  writeFileSync(join(dir, 'invalid.md'), '---\nname: invalid\ndescription: Invalid policy\nexecution: magical\n---\nNo.');
+
+  const result = inspectSkills({ workspacePath: root });
+  assert.equal(result.skills.find((skill) => skill.name === 'direct')?.execution, 'direct');
+  assert.equal(result.skills.find((skill) => skill.name === 'default')?.execution, 'orchestrated');
+  assert.equal(result.rejected.find((item) => item.name === 'invalid')?.reason, 'invalid_execution');
+});
+
+test('catalog renders declared parameters and marks a missing description explicit-only', () => {
+  const root = mkdtempSync(join(tmpdir(), 'skill-catalog-'));
+  const dir = join(root, '.wiki', 'skills');
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'deliver.md'), '---\nname: deliver\nparams:\n  - template\n  - polish\n---\nDeliver.');
+  const inspection = inspectSkills({ workspacePath: root });
+  assert.deepEqual(inspection.warnings.map((item) => item.reason), ['missing_description']);
+  assert.match(formatSkillsForAgent({ workspacePath: root }), /\/deliver \[<template> <polish>\]: workflow skill \[explicit name only\]/);
+});

package/src/core/skills.js

@@ -1,10 +1,38 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { basename, join } from 'node:path';
+import { basename, join, relative } from 'node:path';
 
-const SKILL_NAME_RE = /^[a-zA-Z0-9_-]{1,80}$/;
+const SKILL_NAME_RE = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+const SKILL_PARAM_RE = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+const DANGEROUS_PARAM_NAMES = new Set(['__proto__', 'prototype', 'constructor']);
 const DEFAULT_UI_SKILL_DIR = '.wiki/skills';
+// The CSI branch must come FIRST. `[` is 0x5B, inside the `[@-_]` range, so the
+// two-character alternative would otherwise consume `ESC [` alone and leave the
+// parameter bytes behind as literal text: "\x1B[31m" would become "31m".
+const ANSI_ESCAPE_RE = /\x1B(?:\[[0-?]*[ -/]*[@-~]|[@-_])/g;
+const CONTROL_CHARACTER_RE = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
+const MAX_SKILL_DESCRIPTION_LENGTH = 200;
 
-function parseFrontmatter(raw) {
+function descriptionMetadata(value) {
+  const normalized = String(value || '')
+    .replace(ANSI_ESCAPE_RE, '')
+    .replace(CONTROL_CHARACTER_RE, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return {
+    value: normalized.slice(0, MAX_SKILL_DESCRIPTION_LENGTH),
+    missing: normalized.length === 0,
+    truncated: normalized.length > MAX_SKILL_DESCRIPTION_LENGTH,
+  };
+}
+
+function escapePromptData(value) {
+  return String(value)
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
+
+export function parseFrontmatter(raw) {
   const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
   if (!match) return { meta: {}, body: raw.trim() };
   const meta = {};
@@ -30,19 +58,36 @@ function parseFrontmatter(raw) {
   return { meta, body: match[2].trim() };
 }
 
-function readSkillFile(filePath, fallbackName, scope) {
+function inspectSkillFile(filePath, fallbackName, scope, root) {
   const raw = readFileSync(filePath, 'utf8');
   const { meta, body } = parseFrontmatter(raw);
   const name = String(meta.name || fallbackName).trim();
-  if (!SKILL_NAME_RE.test(name)) return null;
-  return {
+  const relativePath = relative(root, filePath);
+  if (!SKILL_NAME_RE.test(name)) return { rejected: { relativePath, name: name || undefined, reason: 'invalid_name' } };
+  const params = Array.isArray(meta.params) ? meta.params.map((item) => String(item).trim()) : [];
+  if (params.length > 12) return { rejected: { relativePath, name, reason: 'too_many_params' } };
+  if (new Set(params).size !== params.length) return { rejected: { relativePath, name, reason: 'duplicate_param' } };
+  if (params.some((param) => !SKILL_PARAM_RE.test(param) || DANGEROUS_PARAM_NAMES.has(param))) {
+    return { rejected: { relativePath, name, reason: 'invalid_param' } };
+  }
+  const description = descriptionMetadata(meta.description);
+  const execution = String(meta.execution || 'orchestrated').trim().toLowerCase();
+  if (!['orchestrated', 'direct'].includes(execution)) {
+    return { rejected: { relativePath, name, reason: 'invalid_execution' } };
+  }
+  const skill = {
     name,
-    description: String(meta.description || '').trim(),
-    params: Array.isArray(meta.params) ? meta.params : [],
+    description: description.value,
+    params,
     body,
+    execution,
     scope,
     path: filePath,
   };
+  const warnings = [];
+  if (description.missing) warnings.push({ relativePath, name, reason: 'missing_description' });
+  else if (description.truncated) warnings.push({ relativePath, name, reason: 'description_truncated' });
+  return { skill, warnings };
 }
 
 export function readOptionalText(filePath) {
@@ -50,36 +95,53 @@ export function readOptionalText(filePath) {
   return readFileSync(filePath, 'utf8').trim();
 }
 
-function collectDirectorySkills(dir, scope) {
+function inspectDirectorySkills(dir, scope, root) {
   if (!existsSync(dir)) return [];
   return readdirSync(dir, { withFileTypes: true })
     .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
     .flatMap((entry) => {
       const filePath = join(dir, entry.name);
-      const skill = readSkillFile(filePath, basename(entry.name, '.md'), scope);
-      return skill ? [skill] : [];
+      return [inspectSkillFile(filePath, basename(entry.name, '.md'), scope, root)];
     });
 }
 
-export function listSkills(session = {}) {
-  const skills = [];
+export function inspectSkills(session = {}) {
+  const inspected = [];
   if (session.workspacePath) {
-    skills.push(...collectDirectorySkills(join(session.workspacePath, DEFAULT_UI_SKILL_DIR), 'workspace'));
+    const root = join(session.workspacePath, DEFAULT_UI_SKILL_DIR);
+    inspected.push(...inspectDirectorySkills(root, 'workspace', root));
   }
+  const rejected = inspected.flatMap((item) => item.rejected ? [item.rejected] : []);
+  const warnings = inspected.flatMap((item) => item.warnings ?? []);
+  const candidates = inspected.flatMap((item) => item.skill ? [item.skill] : []);
+  const groups = Map.groupBy(candidates, (skill) => skill.name.toLowerCase());
+  const duplicatePaths = new Set();
+  for (const group of groups.values()) {
+    if (group.length < 2) continue;
+    for (const skill of group) {
+      const relativePath = relative(join(session.workspacePath, DEFAULT_UI_SKILL_DIR), skill.path);
+      duplicatePaths.add(skill.path);
+      rejected.push({ relativePath, name: skill.name, reason: 'duplicate_name' });
+    }
+  }
+  const skills = candidates.filter((skill) => !duplicatePaths.has(skill.path))
+    .sort((a, b) => a.name.localeCompare(b.name));
+  return { skills, rejected, warnings };
+}
 
-  const byName = new Map();
-  for (const skill of skills) byName.set(skill.name, skill);
-  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+export function listSkills(session = {}) {
+  return inspectSkills(session).skills;
 }
 
 export function findSkill(session, name) {
-  return listSkills(session).find((skill) => skill.name === name) ?? null;
+  const normalized = String(name ?? '').toLowerCase();
+  return listSkills(session).find((skill) => skill.name.toLowerCase() === normalized) ?? null;
 }
 
 export function formatSkillsForAgent(session) {
   const skills = listSkills(session);
   if (!skills.length) return 'No skills discovered.';
   return skills
-    .map((skill) => `/${skill.name}: ${skill.description || 'workflow skill'} (${skill.scope})`)
+    .map((skill) => `/${skill.name}${skill.params.length ? ` [${skill.params.map((param) => `<${param}>`).join(' ')}]` : ''}: ${escapePromptData(skill.description || 'workflow skill')}${skill.description ? '' : ' [explicit name only]'} (${skill.scope})`)
     .join('\n');
 }

package/src/runtime/client.js

@@ -55,6 +55,7 @@ export async function postRuntimeRun(input, {
   evaluate = undefined,
   replans = undefined,
   capabilityPlan = undefined,
+  skillName = undefined,
 } = {}) {
   const response = await fetch(runtimeEndpoint(url, '/run', workspace), {
     method: 'POST',
@@ -62,14 +63,53 @@ export async function postRuntimeRun(input, {
       ...runtimeHeaders(token),
       'Content-Type': 'application/json',
     },
-    body: JSON.stringify(Object.assign({ input, workspace }, evaluate !== undefined && { evaluate }, replans !== undefined && { replans }, capabilityPlan !== undefined && { capabilityPlan })),
+    body: JSON.stringify(Object.assign({ input, workspace }, evaluate !== undefined && { evaluate }, replans !== undefined && { replans }, capabilityPlan !== undefined && { capabilityPlan }, skillName !== undefined && { skillName })),
   });
+  const payload = await response.json().catch(() => ({}));
   if (!response.ok) {
-    const err = new Error(`Runtime run failed: HTTP ${response.status}`);
+    const detail = payload.error ?? payload.message ?? payload.detail;
+    const err = new Error(detail
+      ? `Runtime run failed: HTTP ${response.status} — ${detail}`
+      : `Runtime run failed: HTTP ${response.status}`);
     err.status = response.status;
+    err.code = payload.code;
     throw err;
   }
-  return response.json();
+  return payload;
+}
+
+export async function postRuntimeSkill(skillName, args = {}, {
+  url = runtimeUrlFromEnv(),
+  token = runtimeToken(),
+  workspace = null,
+  idempotencyKey = undefined,
+  turnId = undefined,
+  selectionKind = undefined,
+  /** Compétences déjà en cours au-dessus de l'appelant, pour la détection de cycle. */
+  skillStack = undefined,
+} = {}) {
+  const response = await fetch(runtimeEndpoint(url, '/run', workspace), {
+    method: 'POST',
+    headers: { ...runtimeHeaders(token), 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      input: `/${skillName}`,
+      workspace,
+      skillName,
+      skillArguments: args,
+      ...(idempotencyKey ? { idempotencyKey } : {}),
+      ...(turnId ? { turnId } : {}),
+      ...(selectionKind ? { selectionKind } : {}),
+      ...(Array.isArray(skillStack) && skillStack.length ? { skillStack } : {}),
+    }),
+  });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    const error = new Error(payload.error ?? `Runtime skill failed: HTTP ${response.status}`);
+    error.status = response.status;
+    error.code = payload.code;
+    throw error;
+  }
+  return payload;
 }
 
 export async function postRuntimeTurn(input, {
@@ -120,6 +160,7 @@ export async function postRuntimeControl(action, {
   workspace = null,
   input = undefined,
   intent = undefined,
+  id = undefined,
 } = {}) {
   const response = await fetch(runtimeEndpoint(url, '/control', workspace), {
     method: 'POST',
@@ -127,7 +168,7 @@ export async function postRuntimeControl(action, {
       ...runtimeHeaders(token),
       'Content-Type': 'application/json',
     },
-    body: JSON.stringify(Object.assign({ action }, input !== undefined && { input }, intent !== undefined && { intent })),
+    body: JSON.stringify(Object.assign({ action }, input !== undefined && { input }, intent !== undefined && { intent }, id !== undefined && { id })),
   });
   if (!response.ok) {
     const err = new Error(`Runtime control failed: HTTP ${response.status}`);

package/src/runtime/controlCancellation.js

@@ -0,0 +1,33 @@
+export function cancelControlChain(session, { runId = null, itemId = null, reason = 'chain_cancelled', cancelItem } = {}) {
+  const queue = Array.isArray(session?.controlQueue) ? session.controlQueue : [];
+  const active = queue.find((item) => (itemId && item.id === itemId) || (runId && item.runId === runId));
+  if (!active) return { active: null, skipped: 0 };
+  // A standalone control item carries no chainId at all. Without this guard the
+  // sibling test below compares undefined to undefined, matches every queued
+  // standalone request, and turns `/run cancel` into a full queue wipe.
+  if (!active.chainId) return { active, skipped: 0 };
+  if (active.optional === true || active.continueOnFailure === true) return { active, skipped: 0 };
+  let skipped = 0;
+  for (const item of queue) {
+    if (item.id === active.id || item.chainId !== active.chainId || item.status !== 'queued') continue;
+    cancelItem?.(item, reason);
+    skipped += 1;
+  }
+  return { active, skipped };
+}
+
+export function cancelQueuedControlItem(session, itemId, { cancelItem, skipItem } = {}) {
+  const queue = Array.isArray(session?.controlQueue) ? session.controlQueue : [];
+  const item = queue.find((entry) => String(entry.id) === String(itemId));
+  if (!item || item.status !== 'queued') return { cancelled: false, reason: item ? 'not_queued' : 'not_found' };
+  cancelItem?.(item, 'item_cancelled');
+  let skipped = 0;
+  if (item.chainId && item.optional !== true && item.continueOnFailure !== true) {
+    for (const sibling of queue) {
+      if (sibling.chainId !== item.chainId || sibling.status !== 'queued' || Number(sibling.chainSequence) <= Number(item.chainSequence)) continue;
+      skipItem?.(sibling, 'required_predecessor_cancelled');
+      skipped += 1;
+    }
+  }
+  return { cancelled: true, item, skipped };
+}

package/src/runtime/controlCancellation.test.js

@@ -0,0 +1,49 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { cancelControlChain, cancelQueuedControlItem } from './controlCancellation.js';
+
+test('run cancellation skips queued siblings of the same chain only', () => {
+  const session = { controlQueue: [
+    { id: 'a1', runId: 'run-a', chainId: 'a', status: 'running' },
+    { id: 'a2', chainId: 'a', status: 'queued' },
+    { id: 'b1', chainId: 'b', status: 'queued' },
+  ] };
+  const result = cancelControlChain(session, { runId: 'run-a', cancelItem: (item) => { item.status = 'skipped'; } });
+  assert.equal(result.skipped, 1);
+  assert.equal(session.controlQueue[2].status, 'queued');
+});
+
+test('targeted cancellation propagates only after a required item', () => {
+  const session = { controlQueue: [
+    { id: 'a1', chainId: 'a', chainSequence: 0, status: 'queued' },
+    { id: 'a2', chainId: 'a', chainSequence: 1, status: 'queued' },
+  ] };
+  const result = cancelQueuedControlItem(session, 'a1', {
+    cancelItem: (item) => { item.status = 'cancelled'; },
+    skipItem: (item) => { item.status = 'skipped'; },
+  });
+  assert.deepEqual({ cancelled: result.cancelled, skipped: result.skipped }, { cancelled: true, skipped: 1 });
+});
+
+test('run cancellation of a standalone item never touches the rest of the queue', () => {
+  const session = { controlQueue: [
+    { id: 'a', runId: 'run-1', status: 'running', optional: false, continueOnFailure: false },
+    { id: 'b', status: 'queued', optional: false, continueOnFailure: false },
+    { id: 'c', status: 'queued', optional: false, continueOnFailure: false },
+  ] };
+  const cancelled = [];
+  const result = cancelControlChain(session, { runId: 'run-1', cancelItem: (item) => cancelled.push(item.id) });
+  assert.deepEqual(cancelled, []);
+  assert.equal(result.skipped, 0);
+  assert.deepEqual(session.controlQueue.map((item) => item.status), ['running', 'queued', 'queued']);
+});
+
+test('run cancellation on an optional active item preserves later chain steps', () => {
+  const session = { controlQueue: [
+    { id: 'optional', runId: 'run-optional', chainId: 'a', status: 'running', optional: true },
+    { id: 'next', chainId: 'a', status: 'queued' },
+  ] };
+  const result = cancelControlChain(session, { runId: 'run-optional', cancelItem: (item) => { item.status = 'skipped'; } });
+  assert.equal(result.skipped, 0);
+  assert.equal(session.controlQueue[1].status, 'queued');
+});

package/src/runtime/controlDrain.js

@@ -0,0 +1,50 @@
+/**
+ * @statuses-vocabulary
+ * Control items are queued run requests, not orchestrator tasks. Their
+ * terminal vocabulary deliberately includes chain-level `skipped` and is
+ * projected by core/agentEvents.js rather than taskStatuses.js.
+ */
+const TERMINAL = new Set(['done', 'failed', 'cancelled', 'skipped']);
+
+export function reconcileControlQueue(context, { startItem, skipItem } = {}) {
+  if (!context?.session || context.running || context.controlDrainActive) return false;
+  context.controlDrainActive = true;
+  try {
+    const queue = Array.isArray(context.session.controlQueue) ? context.session.controlQueue : [];
+    applySkipPropagation(queue, skipItem);
+    // Event dispatch replaces the projection array and its objects. Re-read it
+    // after propagation so eligibility never runs against stale queued items.
+    const refreshed = Array.isArray(context.session.controlQueue) ? context.session.controlQueue : [];
+    const next = refreshed.find((item) => isRunnableControlItem(item, refreshed));
+    if (!next) return false;
+    startItem?.(next);
+    return true;
+  } finally {
+    context.controlDrainActive = false;
+  }
+}
+
+export function isRunnableControlItem(item, queue) {
+  if (item?.status !== 'queued') return false;
+  if (!item.chainId) return true;
+  const predecessors = queue.filter((candidate) => candidate.chainId === item.chainId && Number(candidate.chainSequence) < Number(item.chainSequence));
+  if (predecessors.some((candidate) => !TERMINAL.has(candidate.status))) return false;
+  return !predecessors.some((candidate) => candidate.optional !== true && candidate.continueOnFailure !== true && ['failed', 'cancelled', 'skipped'].includes(candidate.status));
+}
+
+export function applySkipPropagation(queue, skipItem = null) {
+  let changed = 0;
+  for (const item of queue) {
+    if (item.status !== 'queued' || !item.chainId) continue;
+    const predecessors = queue.filter((candidate) => candidate.chainId === item.chainId && Number(candidate.chainSequence) < Number(item.chainSequence));
+    const blocker = predecessors.find((candidate) => candidate.optional !== true && candidate.continueOnFailure !== true && ['failed', 'cancelled', 'skipped'].includes(candidate.status));
+    if (!blocker) continue;
+    skipItem?.(item, blocker.status === 'cancelled' ? 'chain_cancelled' : 'required_predecessor_failed');
+    // Event dispatch replaces the projected queue instead of mutating this
+    // snapshot. Mirror the transition locally so later siblings in this same
+    // pass can observe the cascade (failed -> skipped -> skipped).
+    item.status = 'skipped';
+    changed += 1;
+  }
+  return changed;
+}

package/src/runtime/controlDrain.test.js

@@ -0,0 +1,38 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { applySkipPropagation, reconcileControlQueue } from './controlDrain.js';
+
+test('drain starts only the first runnable chain item', async () => {
+  const started = [];
+  const context = { running: false, session: { controlQueue: [
+    { id: 'a1', chainId: 'a', chainSequence: 0, status: 'queued' },
+    { id: 'a2', chainId: 'a', chainSequence: 1, status: 'queued' },
+  ] } };
+  assert.equal(await reconcileControlQueue(context, { startItem: (item) => { started.push(item.id); context.running = true; } }), true);
+  assert.deepEqual(started, ['a1']);
+});
+
+test('failed required predecessors skip remaining items but preserve another chain', () => {
+  const queue = [
+    { id: 'a1', chainId: 'a', chainSequence: 0, status: 'failed' },
+    { id: 'a2', chainId: 'a', chainSequence: 1, status: 'queued' },
+    { id: 'b1', chainId: 'b', chainSequence: 0, status: 'queued' },
+  ];
+  const skipped = [];
+  applySkipPropagation(queue, (item) => { item.status = 'skipped'; skipped.push(item.id); });
+  assert.deepEqual(skipped, ['a2']);
+  assert.equal(queue[2].status, 'queued');
+});
+
+test('one propagation pass skips every required descendant in a long chain', () => {
+  const queue = [
+    { id: 'a1', chainId: 'a', chainSequence: 0, status: 'failed' },
+    { id: 'a2', chainId: 'a', chainSequence: 1, status: 'queued' },
+    { id: 'a3', chainId: 'a', chainSequence: 2, status: 'queued' },
+    { id: 'a4', chainId: 'a', chainSequence: 3, status: 'queued' },
+  ];
+  const skipped = [];
+  assert.equal(applySkipPropagation(queue, (item) => skipped.push(item.id)), 3);
+  assert.deepEqual(skipped, ['a2', 'a3', 'a4']);
+  assert.deepEqual(queue.map((item) => item.status), ['failed', 'skipped', 'skipped', 'skipped']);
+});