@dotdrelle/wiki-manager 0.15.43 → 0.15.48

package/src/runtime/server.js

@@ -1,5 +1,5 @@
 import { createServer } from 'node:http';
-import { randomUUID, timingSafeEqual } from 'node:crypto';
+import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
 import { conversationEventSequences, createAgentEvent, dispatchAgentEvent, resetSessionProjection, reduceAgentEvents } from '../core/agentEvents.js';
 import { activeCacertPath } from '../core/cacert.js';
 import { normalizePlanPatch, rebasePlanPatch } from '../core/planPatch.js';
@@ -8,6 +8,23 @@ import { runtimeTokenFromEnv } from './auth.js';
 import { controlMessage } from './controlMessages.js';
 import { tasksAwaitingApproval } from '../orchestrator/dependencyResolver.js';
 import { approvalClassForTask } from '../orchestrator/approvalPolicy.js';
+import { matchSkillInvocation } from '../core/skillInvocation.js';
+import { reconcileControlQueue } from './controlDrain.js';
+import { cancelControlChain, cancelQueuedControlItem } from './controlCancellation.js';
+import { runSkillChain } from './skillRun.js';
+import { findSkill, listSkills } from '../core/skills.js';
+
+const PRIVATE_CONTROL_INPUTS = new WeakMap();
+
+function privateControlInputsFor(session) {
+  if (!session || (typeof session !== 'object' && typeof session !== 'function')) return new Map();
+  let inputs = PRIVATE_CONTROL_INPUTS.get(session);
+  if (!inputs) {
+    inputs = new Map();
+    PRIVATE_CONTROL_INPUTS.set(session, inputs);
+  }
+  return inputs;
+}
 
 export function startRuntimeServer({
   host = '127.0.0.1',
@@ -31,6 +48,8 @@ export function startRuntimeServer({
   exitOnShutdown = process.env.WIKI_MANAGER_RUNTIME_CHILD === '1',
 } = {}) {
   const clients = new Set();
+  // Compiled objectives are private execution material. They deliberately do
+  // not enter events, projections, SSE, audit output or the runs table.
   // When this runtime process started — used by ensureRuntime to detect that
   // the manager source has been edited since (dev staleness) and auto-restart.
   const runtimeStartedAtMs = Date.now();
@@ -200,6 +219,21 @@ export function startRuntimeServer({
           });
           return;
         }
+        if (action === 'cancel_item') {
+          const itemId = String(body.itemId ?? body.id ?? '').trim();
+          if (!itemId) {
+            sendJson(response, 400, { error: 'Missing itemId.' });
+            return;
+          }
+          validateContractInDev('controlMessage', { ...body, action, id: itemId });
+          const result = cancelQueuedControlItem(context.session, itemId, {
+            cancelItem: (item, reason) => emitControlCancelled(context, item, reason),
+            skipItem: (item, reason) => emitControlSkipped(context, item, reason),
+          });
+          void drainControlQueue(context);
+          sendJson(response, result.cancelled ? 202 : 200, { ...result, ...controlStatus(context, store) });
+          return;
+        }
         sendJson(response, 400, { error: 'Unsupported control action.' });
         return;
       }
@@ -282,6 +316,45 @@ export function startRuntimeServer({
             return;
           }
           validateContractInDev('runRequest', { ...body, input });
+          const explicitSkillName = String(body.skillName ?? '').trim().toLowerCase();
+          const invokedSkillName = /^\/([A-Za-z0-9_-]+)/.exec(input)?.[1]?.toLowerCase() ?? '';
+          if (body.skillArguments !== undefined && explicitSkillName !== invokedSkillName) {
+            sendJson(response, 400, { ok: false, terminal: true, code: 'skill_name_mismatch' });
+            return;
+          }
+          // This structured API call is itself the caller's explicit skill
+          // designation, including for reserved names. The equality check
+          // above prevents `skillName: status` from turning unrelated prose
+          // into the homonymous skill. Model-originated calls additionally
+          // pass explicitSkillReference() before reaching this endpoint.
+          if (explicitSkillName && body.skillArguments !== undefined) {
+            const result = await context.session._runSkillWithinRun(explicitSkillName, body.skillArguments, {
+              idempotencyKey: body.idempotencyKey ?? null,
+              turnId: body.turnId ?? null,
+              selectionKind: body.selectionKind ?? null,
+              // Pile de l'appelant : c'est le seul canal par lequel elle peut
+              // franchir la frontière HTTP.
+              skillStack: Array.isArray(body.skillStack) ? body.skillStack : [],
+            });
+            sendJson(response, result.accepted ? 202 : skillResultErrorStatus(result), result);
+            return;
+          }
+          const skillMatch = matchSkillInvocation(context.session, input, {
+            // Reserved names are unlocked only by a matching structured skill
+            // invocation, never by an unrelated truthy marker in the body.
+            allowReserved: Boolean(explicitSkillName && explicitSkillName === invokedSkillName),
+          });
+          if (skillMatch) {
+            try {
+              const result = await enqueueSkillInvocation(context, skillMatch);
+              sendJson(response, 202, { accepted: true, kind: 'skill_chain', ...result, ...controlStatus(context, store) });
+            } catch (err) {
+              const error = skillInvocationErrorMessage(err);
+              publishSkillInvocationFailure(context, input, error);
+              sendJson(response, skillInvocationErrorStatus(err), { error, code: err?.code ?? 'skill_compile_failed' });
+            }
+            return;
+          }
           if (context.running) {
             // A structured capability plan must never degrade into a free-text
             // control message: its exact arguments and approval policy would
@@ -339,6 +412,23 @@ export function startRuntimeServer({
         // run is active. Other interactive turns still become control
         // messages so they cannot start a competing agent decision.
         const readOnlyChat = String(body.mode ?? '').toLowerCase() === 'chat';
+        // An explicit /skill invocation has deterministic meaning. Keep the
+        // conversational /turn boundary, but do not ask the LLM to rediscover
+        // the skill from prose: it could choose a direct mutation instead and
+        // silently bypass the private workflow. Informational prose merely
+        // mentioning a skill never matches this anchored invocation parser.
+        const skillMatch = !readOnlyChat ? matchSkillInvocation(context.session, input) : null;
+        if (skillMatch) {
+          try {
+            const result = await enqueueSkillInvocation(context, skillMatch);
+            sendJson(response, 202, { accepted: true, kind: 'skill_chain', ...result, ...controlStatus(context, store) });
+          } catch (err) {
+            const error = skillInvocationErrorMessage(err);
+            publishSkillInvocationFailure(context, input, error);
+            sendJson(response, skillInvocationErrorStatus(err), { error, code: err?.code ?? 'skill_compile_failed' });
+          }
+          return;
+        }
         if (context.running && !readOnlyChat) {
           const result = await handleControlMessage(context, store, input, {
             intent: body.intent,
@@ -436,6 +526,10 @@ export function startRuntimeServer({
           sendJson(response, 200, { cancelled: false, reason: 'no active run' });
           return;
         }
+        cancelControlChain(context.session, {
+          runId: context.currentRunId,
+          cancelItem: (item, reason) => emitControlSkipped(context, item, reason),
+        });
         context.currentAbortController.abort();
         await cancel?.(context);
         sendJson(response, 202, { cancelled: true, workspace: context.workspace ?? workspace ?? null });
@@ -561,7 +655,7 @@ export function startRuntimeServer({
         host,
         port: typeof address === 'object' && address ? address.port : port,
         publish,
-        drainControl: (context) => startNextControlRequest(context),
+        drainControl: (context) => drainControlQueue(context),
         close: () => new Promise((closeResolve, closeReject) => {
           for (const client of clients) client.response.end();
           clients.clear();
@@ -572,7 +666,70 @@ export function startRuntimeServer({
   });
 
   async function resolveContext({ workspace = null } = {}) {
-    return resolvedGetContext(workspace);
+    const context = await resolvedGetContext(workspace);
+    if (context?.session) {
+      context.session._runSkillWithinRun = async (skillName, args = {}, metadata = {}) => {
+        const skill = findSkill(context.session, skillName);
+        if (!skill) return {
+          ok: false,
+          terminal: true,
+          code: 'skill_not_found',
+          availableSkills: listSkills(context.session).map((item) => item.name),
+        };
+        try {
+          const idempotencyKey = metadata.idempotencyKey
+            ? String(metadata.idempotencyKey)
+            : metadata.turnId
+              ? skillIdempotencyKey(context.workspace ?? context.session.workspace, metadata.turnId, skill.name, args)
+              : null;
+          context.skillRuns ??= new Map();
+          context.pendingSkillRuns ??= new Map();
+          const persistedChainId = idempotencyKey && typeof store.findSkillRun === 'function'
+            ? store.findSkillRun({ workspace: context.workspace ?? null, idempotencyKey })
+            : null;
+          const existingChainId = persistedChainId ?? (idempotencyKey ? context.skillRuns.get(idempotencyKey) : null);
+          if (existingChainId) return publicSkillRunProjection(context, skill.name, existingChainId, metadata.selectionKind, true);
+          if (idempotencyKey && context.pendingSkillRuns.has(idempotencyKey)) {
+            const pendingChainId = await context.pendingSkillRuns.get(idempotencyKey);
+            return publicSkillRunProjection(context, skill.name, pendingChainId, metadata.selectionKind, true);
+          }
+          const creation = runSkillChain(context, skill, {
+            args,
+            enqueueControlRequest,
+            drainControlQueue,
+            selectionKind: metadata.selectionKind,
+            // La pile du run appelant : elle sera empilée sur chaque élément mis
+            // en file, et c'est elle seule qui survit au hand-off.
+            skillStack: Array.isArray(metadata.skillStack) ? metadata.skillStack : [],
+          });
+          if (idempotencyKey) context.pendingSkillRuns.set(idempotencyKey, creation.then((item) => item.chainId));
+          const result = await creation;
+          if (idempotencyKey) {
+            context.skillRuns.set(idempotencyKey, result.chainId);
+            store.persistSkillRun?.({
+              workspace: context.workspace ?? context.session.workspace ?? null,
+              idempotencyKey,
+              chainId: result.chainId,
+            });
+          }
+          return publicSkillRunProjection(context, skill.name, result.chainId, metadata.selectionKind, false);
+        } catch (error) {
+          return {
+            ok: false,
+            terminal: true,
+            code: error?.code ?? 'skill_compile_failed',
+          };
+        } finally {
+          const key = metadata.idempotencyKey
+            ? String(metadata.idempotencyKey)
+            : metadata.turnId
+              ? skillIdempotencyKey(context.workspace ?? context.session.workspace, metadata.turnId, skill.name, args)
+              : null;
+          if (key) context.pendingSkillRuns?.delete(key);
+        }
+      };
+    }
+    return context;
   }
 
   // Shared by POST handlers that take a JSON body carrying an optional
@@ -649,22 +806,103 @@ export function startRuntimeServer({
         context.currentRunId = null;
         context.currentRunWorkspace = null;
         publishState(runWorkspace, context);
-        void startNextControlRequest(context);
+        void drainControlQueue(context);
       });
     return { accepted: true, runId, workspace: runWorkspace, ...(ready ? { ready } : {}) };
   }
 
   function startNextControlRequest(context) {
-    if (!context?.session || context.running) return false;
-    const item = controlQueueFor(context.session).find((entry) => entry.status === 'queued');
-    if (!item) return false;
-    startRuntimeRun(context, {
-      input: item.input,
-      workspace: item.workspace ?? context.workspace ?? null,
-      ...(item.capabilityPlan !== undefined ? { capabilityPlan: item.capabilityPlan } : {}),
-    }, { controlItemId: item.id });
-    return true;
+    return drainControlQueue(context);
+  }
+
+  function drainControlQueue(context) {
+    return reconcileControlQueue(context, {
+      /*
+       La provenance de chaîne suit le run.
+
+       `chainId` et `skillName` vivaient sur l'item de contrôle et s'arrêtaient
+       là : le run ne savait pas qu'il exécutait une intention compilée depuis
+       une compétence. L'agent voyait donc un objectif métier — « ingérer les
+       fichiers en attente » — qui ressemble par construction à la description
+       de la compétence dont il sort, et la resélectionnait. En headless, où
+       personne n'interrompt, cela boucle jusqu'à épuisement du budget LLM.
+      */
+      startItem: (item) => startRuntimeRun(context, {
+        input: takePrivateControlInput(context.session, item),
+        publicInput: item.input,
+        workspace: item.workspace ?? context.workspace ?? null,
+        // Interactive skill runs never approve their own mutations. Headless
+        // may still grant the pending run explicitly through --auto-approve.
+        ...(item.chainId ? { requireApproval: true } : {}),
+        ...(item.capabilityPlan !== undefined ? { capabilityPlan: item.capabilityPlan } : {}),
+        ...(item.chainId
+          ? {
+            skillChain: {
+              chainId: item.chainId,
+              skillName: item.skillName ?? null,
+              execution: item.skillExecution === 'direct' ? 'direct' : 'orchestrated',
+              // La pile des ancêtres, sans quoi le run ne peut pas savoir qu'il
+              // referme un cycle commencé deux hand-offs plus tôt.
+              skillStack: Array.isArray(item.skillStack) ? item.skillStack : [],
+            },
+          }
+          : {}),
+      }, { controlItemId: item.id }),
+      skipItem: (item, reason) => {
+        privateControlInputsFor(context.session).delete(item.id);
+        emitControlSkipped(context, item, reason);
+      },
+    });
   }
+
+  function takePrivateControlInput(session, item) {
+    const privateControlInputs = privateControlInputsFor(session);
+    const input = privateControlInputs.get(item.id) ?? item.input;
+    privateControlInputs.delete(item.id);
+    return input;
+  }
+
+  async function enqueueSkillInvocation(context, match) {
+    const result = await runSkillChain(context, match.skill, {
+      rawArgs: match.rawArgs,
+      enqueueControlRequest,
+      drainControlQueue,
+      selectionKind: 'explicit_name',
+    });
+    // Publish only after compilation succeeds. The marker prevents an
+    // invocation queued during another run from inheriting that run's id.
+    dispatchAgentEvent(context.session, createAgentEvent('user_message', {
+      origin: 'user',
+      workspace: context.workspace ?? null,
+      payload: { content: `/${match.skill.name}${match.rawArgs ? ` ${match.rawArgs}` : ''}`, independent: true },
+    }));
+    return result;
+  }
+
+  function publishSkillInvocationFailure(context, input, error) {
+    const workspace = context.workspace ?? context.session?.workspace ?? null;
+    dispatchAgentEvent(context.session, createAgentEvent('user_message', {
+      origin: 'user', workspace, payload: { content: input, independent: true },
+    }));
+    dispatchAgentEvent(context.session, createAgentEvent('assistant_message', {
+      origin: 'runtime', workspace, payload: { content: error, independent: true },
+    }));
+  }
+}
+
+function skillInvocationErrorStatus(error) {
+  return ['skill_compile_failed', 'skill_arguments_invalid'].includes(error?.code) ? 400 : 422;
+}
+
+function skillResultErrorStatus(result) {
+  if (result?.code === 'skill_not_found') return 404;
+  if (result?.code === 'skill_arguments_invalid') return 400;
+  return 422;
+}
+
+function skillInvocationErrorMessage(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return `Skill invocation could not be compiled: ${message}`;
 }
 
 function workspaceFromUrl(url) {
@@ -748,6 +986,37 @@ function controlQueueFor(session) {
   return Array.isArray(session?.controlQueue) ? session.controlQueue : [];
 }
 
+function skillIdempotencyKey(workspace, turnId, skillName, args) {
+  const canonicalArguments = JSON.stringify(Object.fromEntries(
+    Object.entries(args ?? {}).sort(([left], [right]) => left.localeCompare(right)),
+  ));
+  return createHash('sha256')
+    .update(`${workspace ?? ''}\0${turnId}\0${String(skillName).toLowerCase()}\0${canonicalArguments}`)
+    .digest('hex');
+}
+
+function publicSkillRunProjection(context, skillName, chainId, selectionKind, deduplicated) {
+  const chainItems = controlQueueFor(context?.session).filter((item) => item.chainId === chainId);
+  const resolvedSelectionKind = selectionKind ?? chainItems.find((item) => item.selectionKind)?.selectionKind ?? null;
+  const items = chainItems
+    .sort((left, right) => Number(left.chainSequence ?? 0) - Number(right.chainSequence ?? 0))
+    .map((item) => ({
+      id: item.id,
+      sequence: Number(item.chainSequence ?? 0),
+      status: item.status,
+      optional: item.optional === true,
+    }));
+  return {
+    accepted: true,
+    skill: skillName,
+    chainId,
+    objectiveCount: items.length,
+    items,
+    ...(resolvedSelectionKind ? { selectionKind: resolvedSelectionKind } : {}),
+    ...(deduplicated ? { deduplicated: true } : {}),
+  };
+}
+
 function cancelQueuedControlItems(session, workspace = null) {
   const now = new Date().toISOString();
   const counted = new Set();
@@ -760,6 +1029,7 @@ function cancelQueuedControlItems(session, workspace = null) {
       item.finishedAt = now;
       item.updatedAt = now;
       const id = item.id ?? item.runId ?? `${item.input}:${item.createdAt}`;
+      privateControlInputsFor(session).delete(item.id);
       if (!counted.has(id)) {
         counted.add(id);
         if (session) {
@@ -875,18 +1145,42 @@ async function handleControlMessage(context, store, input, { intent = null, star
     : controlMessage(context?.session, 'converse_while_idle'));
 }
 
-function enqueueControlRequest(context, input, { capabilityPlan } = {}) {
+/*
+ `skillStack` accompagne l'élément, il ne vit pas sur la session.
+
+ La pile des compétences en cours était posée sur la session pour la durée d'UN
+ run, et restaurée par son `finally`. Or une compétence imbriquée n'est pas
+ exécutée en ligne : elle est MISE EN FILE, et son run démarre après que le
+ parent a fini de se nettoyer. La pile qu'elle lisait était donc déjà vide.
+
+ Conséquence : la garde n'attrapait que le cas pour lequel elle avait été
+ écrite — une compétence qui se relance dans son propre run — et laissait
+ passer A→B→A, qui boucle jusqu'à épuisement du budget en headless.
+
+ Une file est un passage de témoin : ce qui doit survivre au parent voyage avec
+ le message, pas dans l'état de celui qui l'a posté.
+*/
+function enqueueControlRequest(context, input, { publicInput = null, capabilityPlan, chainId, chainSequence, skillName, skillExecution, skillStack, selectionKind, optional = false, continueOnFailure = false } = {}) {
   const now = new Date().toISOString();
   const item = {
     id: `control-${randomUUID()}`,
     workspace: context?.workspace ?? context?.session?.workspace ?? null,
     type: 'run_request',
-    input,
+    input: publicInput ?? input,
     status: 'queued',
     createdAt: now,
     updatedAt: now,
     ...(capabilityPlan !== undefined ? { capabilityPlan } : {}),
+    ...(chainId ? { chainId } : {}),
+    ...(Number.isInteger(chainSequence) ? { chainSequence } : {}),
+    ...(skillName ? { skillName } : {}),
+    ...(skillExecution ? { skillExecution } : {}),
+    ...(Array.isArray(skillStack) && skillStack.length ? { skillStack: [...skillStack] } : {}),
+    ...(selectionKind ? { selectionKind } : {}),
+    optional: optional === true,
+    continueOnFailure: continueOnFailure === true,
   };
+  privateControlInputsFor(context?.session).set(item.id, input);
   dispatchAgentEvent(context.session, createAgentEvent('control_enqueued', {
     origin: 'runtime',
     workspace: item.workspace,
@@ -895,6 +1189,23 @@ function enqueueControlRequest(context, input, { capabilityPlan } = {}) {
   return item;
 }
 
+function emitControlSkipped(context, item, reason) {
+  dispatchAgentEvent(context.session, createAgentEvent('control_skipped', {
+    origin: 'runtime',
+    workspace: item.workspace ?? context.workspace ?? null,
+    payload: { id: item.id, reason, finishedAt: new Date().toISOString() },
+  }));
+}
+
+function emitControlCancelled(context, item, reason) {
+  privateControlInputsFor(context?.session).delete(item.id);
+  dispatchAgentEvent(context.session, createAgentEvent('control_cancelled', {
+    origin: 'runtime',
+    workspace: item.workspace ?? context.workspace ?? null,
+    payload: { id: item.id, reason, finishedAt: new Date().toISOString() },
+  }));
+}
+
 function storeControlProposal(context, input, classification, status) {
   const now = new Date().toISOString();
   const patch = buildPlanPatchFromInput(input, status);