@dotdrelle/wiki-manager 0.11.10 → 0.12.1

package/src/orchestrator/resultAggregator.test.js

@@ -0,0 +1,211 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
+import { accept } from './resultAggregator.js';
+
+test('resultAggregator expands a plan after a task result and rewires insertion after the task', async () => {
+  const session = sessionWithPlan();
+  session.approvals = [{ id: 'approval-run', scope: 'run', status: 'approved', runId: 'run-expansion' }];
+  const calls = [];
+
+  const result = await accept(taskResultWithExpansion(), {
+    session,
+    runId: 'run-expansion',
+    task: session.headlessPlan[0],
+    assignment: { agentInstanceId: 'production-main', serverName: 'production' },
+    registry: expansionRegistry(),
+    callTool: async (_mcp, serverName, toolName, args) => {
+      calls.push({ serverName, toolName, args });
+      assert.equal(serverName, 'production');
+      assert.equal(toolName, 'agent_plan');
+      return expansionFragment();
+    },
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(result.expansion.ok, true);
+  assert.deepEqual(calls.map((call) => call.args.capability), ['document.build']);
+  const plan = Object.fromEntries(session.headlessPlan.map((task) => [task.id, task]));
+  assert.deepEqual(plan['run-expansion:build-x'].dependsOn, ['run-expansion:a']);
+  assert.deepEqual(plan['run-expansion:build-y'].dependsOn, ['run-expansion:build-x']);
+  assert.deepEqual(plan['run-expansion:b'].dependsOn, ['run-expansion:build-y']);
+  assert.equal(plan['run-expansion:build-x'].status, 'pending');
+  assert.equal(session.planRevision, 1);
+});
+
+test('resultAggregator marks expanded tasks waiting_approval when approval is not covered', async () => {
+  const session = sessionWithPlan();
+
+  const result = await accept(taskResultWithExpansion(), {
+    session,
+    runId: 'run-expansion',
+    task: session.headlessPlan[0],
+    assignment: { agentInstanceId: 'production-main', serverName: 'production' },
+    registry: expansionRegistry(),
+    callTool: async () => expansionFragment(),
+  });
+
+  assert.equal(result.expansion.ok, true);
+  const created = session.headlessPlan.filter((task) => ['run-expansion:build-x', 'run-expansion:build-y'].includes(task.id));
+  assert.deepEqual(created.map((task) => task.status), ['waiting_approval', 'waiting_approval']);
+});
+
+test('resultAggregator rejects an expansion with an unknown capability and preserves task success', async () => {
+  const session = sessionWithPlan();
+
+  const result = await accept({
+    ok: true,
+    taskId: 'run-expansion:a',
+    status: 'succeeded',
+    outputRefs: [],
+    planExpansionRequest: {
+      capability: 'unknown.capability',
+      operation: 'expand',
+      arguments: {},
+      insertAfterTasks: ['run-expansion:a'],
+    },
+  }, {
+    session,
+    runId: 'run-expansion',
+    task: session.headlessPlan[0],
+    assignment: { agentInstanceId: 'production-main', serverName: 'production' },
+    registry: expansionRegistry(),
+    callTool: async () => assert.fail('agent_plan must not be called for an unknown capability'),
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(result.expansion.ok, false);
+  assert.equal(result.expansion.errors[0].code, 'capability_unavailable');
+  assert.deepEqual(session.headlessPlan.map((task) => task.id), ['run-expansion:a', 'run-expansion:b']);
+  assert.equal(session.headlessPlan[0].status, 'done');
+  assert.ok(session.agentEvents.some((event) => event.type === 'plan.rejected'));
+});
+
+function sessionWithPlan() {
+  const session = {
+    mcp: {
+      production: {
+        tools: [{ name: 'agent_plan' }],
+      },
+    },
+    agentEvents: [],
+    activities: {},
+    workspace: 'docs',
+    headlessPlan: [
+      {
+        id: 'run-expansion:a',
+        step: 1,
+        label: 'Task A',
+        description: 'Task A',
+        status: 'running',
+        dependsOn: [],
+        outputRefs: [],
+      },
+      {
+        id: 'run-expansion:b',
+        step: 2,
+        label: 'Task B',
+        description: 'Task B',
+        status: 'pending',
+        dependsOn: ['run-expansion:a'],
+        outputRefs: [],
+      },
+    ],
+  };
+  dispatchAgentEvent(session, createAgentEvent('plan_set', {
+    origin: 'test',
+    runId: 'run-expansion',
+    payload: { steps: session.headlessPlan, planRevision: 0 },
+  }));
+  session.agentEvents = [];
+  return session;
+}
+
+function taskResultWithExpansion() {
+  return {
+    ok: true,
+    taskId: 'run-expansion:a',
+    status: 'succeeded',
+    outputRefs: [{ type: 'file', ref: 'out/a.json' }],
+    planExpansionRequest: {
+      capability: 'document.build',
+      operation: 'build',
+      objective: 'Build downstream generated documents.',
+      arguments: { templates: ['templates/x.md'] },
+      insertAfterTasks: ['run-expansion:a'],
+    },
+  };
+}
+
+function expansionFragment() {
+  return {
+    contractVersion: '1',
+    agentInstanceId: 'production-main',
+    capability: 'document.build',
+    summary: {
+      label: 'Build generated documents',
+      initialSynthesis: ['Build two generated documents.'],
+      estimatedTasks: 2,
+    },
+    groups: [{ id: 'build', label: 'Build', recommendedConcurrency: 1 }],
+    tasks: [
+      plannedBuildTask('build-x', []),
+      plannedBuildTask('build-y', ['build-x']),
+    ],
+    expectedOutputs: [{ type: 'file', ref: 'deliverables/y.md' }],
+  };
+}
+
+function plannedBuildTask(id, dependsOn) {
+  return {
+    id,
+    label: `Build ${id}`,
+    requiredCapability: 'document.build',
+    operation: 'build',
+    arguments: { templates: [`templates/${id}.md`] },
+    groupId: 'build',
+    dependsOn,
+    parallelizable: true,
+    inputRefs: [{ type: 'file', ref: `templates/${id}.md` }],
+    expectedOutputRefs: [{ type: 'file', ref: `deliverables/${id}.md` }],
+    locks: [`deliverable:${id}.md`],
+    requiresApproval: true,
+    idempotencyKey: `idem-${id}`,
+    progressWeight: 1,
+  };
+}
+
+function expansionRegistry() {
+  return {
+    providersFor(capability) {
+      if (capability !== 'document.build') return [];
+      return [{
+        agentInstanceId: 'production-main',
+        serverName: 'production',
+        health: 'available',
+        capability: {
+          id: 'document.build',
+          version: '1',
+          description: 'Build documents',
+          inputSchema: {
+            type: 'object',
+            required: ['templates'],
+            additionalProperties: true,
+            properties: {
+              templates: { type: 'array', items: { type: 'string' } },
+            },
+          },
+          outputSchema: {},
+          supportedOperations: ['build'],
+          mutationClass: 'workspace',
+          defaultRequiresApproval: true,
+        },
+        description: { contractVersion: '1' },
+      }];
+    },
+    isCompatible(contractVersion) {
+      return String(contractVersion) === '1';
+    },
+  };
+}

package/src/orchestrator/scheduler.js

@@ -0,0 +1,103 @@
+import { readyTasks } from './dependencyResolver.js';
+
+export const DEFAULT_SCHEDULER_CONCURRENCY = 3;
+
+export function resolveSchedulerConcurrency(value = process.env.WIKI_MANAGER_SCHEDULER_CONCURRENCY) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0
+    ? Math.max(1, Math.floor(parsed))
+    : DEFAULT_SCHEDULER_CONCURRENCY;
+}
+
+export function effectiveConcurrency(group = null, agent = null, donna = null, provider = null) {
+  const limits = [
+    ...concurrencyValues(donna),
+    ...concurrencyValues(group),
+    ...concurrencyValues(provider),
+    ...concurrencyValues(agent),
+  ].filter((value) => value != null && value > 0);
+  return Math.max(1, Math.min(...(limits.length ? limits : [DEFAULT_SCHEDULER_CONCURRENCY])));
+}
+
+export async function drainActive(active, attemptManager = null) {
+  if (active.size === 0) return;
+  const entries = [...active.values()];
+  await Promise.all(entries.map((entry) => entry.promise));
+  for (const entry of entries) entry.cleanup?.();
+  active.clear();
+  attemptManager?.clear?.();
+}
+
+export function startReadyTasks({
+  plan,
+  active,
+  attemptManager,
+  startTask,
+  limit,
+  session = null,
+  registry = null,
+  lockManager = null,
+  budgetManager = null,
+  approvals = [],
+  onDuplicateTask = null,
+  onTaskReady = null,
+  onAttemptCreated = null,
+  onTaskStarting = null,
+} = {}) {
+  let started = 0;
+  const seenTaskIds = new Set(active.keys());
+  const ready = readyTasks(plan, {
+    registry,
+    lockManager,
+    budgetManager,
+    approvals,
+    activeTaskIds: active.keys(),
+  });
+  for (const task of ready) {
+    if (active.size >= limit) break;
+    const taskId = planTaskId(task);
+    if (active.has(taskId)) continue;
+    if (seenTaskIds.has(taskId)) {
+      onDuplicateTask?.(taskId, task);
+      continue;
+    }
+    seenTaskIds.add(taskId);
+    onTaskReady?.(task);
+    const attempt = attemptManager.reserve(task);
+    if (!attempt) continue;
+    onAttemptCreated?.(task, attempt);
+    budgetManager?.recordTaskStart?.(task);
+    onTaskStarting?.(task, attempt);
+    const entry = startTask(task, attempt);
+    active.set(taskId, { taskId, ...entry });
+    started += 1;
+  }
+  return started;
+}
+
+function concurrencyValues(source) {
+  if (source == null) return [];
+  if (typeof source === 'number') return [positiveInteger(source)].filter(Boolean);
+  const candidates = [
+    source,
+    source.limits,
+    source.description?.limits,
+    source.capability?.limits,
+  ].filter(Boolean);
+  return candidates.flatMap((limits) => [
+    limits.effectiveConcurrency,
+    limits.maxConcurrency,
+    limits.recommendedConcurrency,
+    limits.concurrency,
+    limits.schedulerConcurrency,
+  ]).map(positiveInteger).filter(Boolean);
+}
+
+function positiveInteger(value) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? Math.floor(number) : null;
+}
+
+function planTaskId(task) {
+  return String(task?.id ?? task?.step);
+}

package/src/orchestrator/scheduler.test.js

@@ -0,0 +1,138 @@
+import assert from 'node:assert/strict';
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import test from 'node:test';
+
+import { createBudgetManager } from './budgetManager.js';
+import { readyTasks } from './dependencyResolver.js';
+import { createLockManager } from './lockManager.js';
+import { effectiveConcurrency, startReadyTasks } from './scheduler.js';
+
+test('dependencyResolver holds a barrier task until its dependsOnGroup is done', () => {
+  const plan = [
+    task('ingest-a', { groupId: 'ingest', status: 'done' }),
+    task('ingest-b', { groupId: 'ingest', status: 'pending' }),
+    task('consolidate', { dependsOnGroup: 'ingest', priority: 1 }),
+  ];
+
+  assert.deepEqual(readyTasks(plan).map((item) => item.id), ['ingest-b']);
+  plan[1].status = 'done';
+  assert.deepEqual(readyTasks(plan).map((item) => item.id), ['consolidate']);
+});
+
+test('dependencyResolver orders ready tasks by priority before step', () => {
+  const plan = [
+    task('low', { step: 1, priority: 20 }),
+    task('high', { step: 2, priority: 5 }),
+    task('none', { step: 0 }),
+  ];
+
+  assert.deepEqual(readyTasks(plan).map((item) => item.id), ['high', 'low', 'none']);
+});
+
+test('dependencyResolver skips tasks whose locks are not free and keeps other ready work moving', () => {
+  const lockManager = createLockManager();
+  const held = lockManager.acquire(['deliverable:a.md']);
+  const plan = [
+    task('blocked', { locks: ['deliverable:a.md'], priority: 1 }),
+    task('free', { locks: ['deliverable:b.md'], priority: 2 }),
+  ];
+
+  assert.deepEqual(readyTasks(plan, { lockManager }).map((item) => item.id), ['free']);
+  held.release();
+  assert.deepEqual(readyTasks(plan, { lockManager }).map((item) => item.id), ['blocked', 'free']);
+});
+
+test('budgetManager blocks ready tasks once the run budget is exceeded', () => {
+  const budgetManager = createBudgetManager({ budgets: { maxTasks: 0 }, runId: 'run-budget' });
+
+  assert.deepEqual(readyTasks([task('a')], { budgetManager }), []);
+  assert.equal(budgetManager.exceeded().reason, 'max_tasks_exceeded');
+});
+
+test('budgetManager tracks attempts depth duration and tokens per run', () => {
+  const budgetManager = createBudgetManager({
+    budgets: { maxAttempts: 1, maxDepth: 2, maxDurationMs: 5, maxTokens: 10 },
+    runId: 'run-budget-counters',
+  });
+
+  budgetManager.recordTaskStart(task('a', { depth: 2 }));
+  assert.equal(budgetManager.canStartTask(task('b')), false);
+  assert.equal(budgetManager.exceeded().reason, 'max_attempts_exceeded');
+  assert.throws(
+    () => budgetManager.recordTaskResult({ metrics: { durationMs: 6, totalTokens: 9 } }),
+    /max_duration_exceeded/,
+  );
+  assert.equal(budgetManager.snapshot().durationMs, 6);
+  assert.equal(budgetManager.snapshot().tokens, 9);
+});
+
+test('scheduler.effectiveConcurrency returns the minimum effective concurrency', () => {
+  const group = { recommendedConcurrency: 4 };
+  const agent = { description: { limits: { recommendedConcurrency: 3, maxConcurrency: 8 } } };
+  const donna = { schedulerConcurrency: 6 };
+  const provider = { capability: { limits: { maxConcurrency: 2 } }, maxConcurrency: 5 };
+
+  assert.equal(effectiveConcurrency(group, agent, donna, provider), 2);
+});
+
+test('startReadyTasks starts only ready tasks and respects lock starvation', () => {
+  const active = new Map();
+  const lockManager = createLockManager();
+  const attemptManager = {
+    reserve(item) {
+      const reservation = lockManager.acquire(item);
+      if (!reservation) return null;
+      return { attemptId: `${item.id}:attempt-1`, release: reservation.release };
+    },
+  };
+  const started = [];
+  const count = startReadyTasks({
+    plan: [
+      task('blocked', { locks: ['workspace:write'], priority: 1 }),
+      task('free', { locks: ['deliverable:a.md'], priority: 2 }),
+    ],
+    active,
+    attemptManager,
+    lockManager,
+    limit: 2,
+    startTask(item) {
+      started.push(item.id);
+      return { promise: Promise.resolve({ ok: true, taskId: item.id }) };
+    },
+  });
+
+  assert.equal(count, 2);
+  assert.deepEqual(started, ['blocked', 'free']);
+  assert.deepEqual(lockManager.snapshot(), ['deliverable:a.md', 'workspace:write']);
+});
+
+test('orchestrator modules do not import business-specific packages', () => {
+  const banned = /\b(?:production|cme|commercial|documents|wiki)\b/;
+  const orchestratorDir = new URL('.', import.meta.url).pathname;
+  const offenders = readdirSync(orchestratorDir)
+    .filter((file) => file.endsWith('.js') && !file.endsWith('.test.js'))
+    .flatMap((file) => {
+      const content = readFileSync(join(orchestratorDir, file), 'utf8');
+      return content
+        .split('\n')
+        .filter((line) => /^\s*import\s/.test(line) && banned.test(line))
+        .map((line) => `${file}: ${line.trim()}`);
+    });
+
+  assert.deepEqual(offenders, []);
+});
+
+function task(id, overrides = {}) {
+  return {
+    id,
+    step: overrides.step ?? 1,
+    status: overrides.status ?? 'pending',
+    dependsOn: overrides.dependsOn ?? [],
+    requiredCapability: 'workspace.diagnose',
+    operation: 'doctor',
+    locks: [],
+    requiresApproval: false,
+    ...overrides,
+  };
+}

package/src/runtime/approvals.js

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
+import { normalizeApprovalGrant } from '../orchestrator/approvalPolicy.js';
 
 const DEFAULT_APPROVAL_TIMEOUT_MS = 10 * 60 * 1000;
 
@@ -12,6 +13,9 @@ export function createApprovalManager(session, {
     const scope = request.scope === 'tool' ? 'tool' : 'run';
     const approvalId = request.approvalId ?? randomUUID();
     const runId = request.runId ?? session._currentRunIdentity?.runId ?? null;
+    const workspaceId = request.workspaceId ?? request.workspace ?? session._currentRunIdentity?.workspace ?? session.workspace ?? null;
+    const planRevision = request.planRevision ?? session.planRevision ?? null;
+    const approvalClasses = normalizeClasses(request.approvalClasses ?? request.approvalClass);
     const timeoutMs = Number.isFinite(Number(request.timeoutMs))
       ? Math.max(1, Number(request.timeoutMs))
       : defaultTimeoutMs;
@@ -31,6 +35,25 @@ export function createApprovalManager(session, {
         timeoutMs,
       },
     }));
+    dispatchAgentEvent(session, createAgentEvent('approval.requested', {
+      origin: 'runtime',
+      runId,
+      taskId: request.taskId ?? request.itemId ?? null,
+      workspace: workspaceId,
+      payload: {
+        id: approvalId,
+        approvalId,
+        scope: normalizeGrantScope(request.scope),
+        runId,
+        workspaceId,
+        planRevision,
+        taskId: request.taskId ?? request.itemId ?? null,
+        itemId: request.itemId ?? request.taskId ?? null,
+        groupId: request.groupId ?? null,
+        approvalClasses,
+        reason: request.reason ?? null,
+      },
+    }));
 
     await new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -53,8 +76,15 @@ export function createApprovalManager(session, {
       pending.set(approvalId, {
         approvalId,
         scope,
+        grantScope: normalizeGrantScope(request.scope),
         runId,
+        workspaceId,
+        planRevision,
         itemId: request.itemId ?? null,
+        taskId: request.taskId ?? request.itemId ?? null,
+        groupId: request.groupId ?? null,
+        approvalClasses,
+        reason: request.reason ?? null,
         resolve: () => {
           pending.delete(approvalId);
           cleanup();
@@ -77,10 +107,59 @@ export function createApprovalManager(session, {
         itemId: request.itemId ?? null,
       },
     }));
+    const grant = normalizeApprovalGrant({
+      id: approvalId,
+      approvalId,
+      scope: normalizeGrantScope(request.scope),
+      runId,
+      workspaceId,
+      planRevision,
+      taskId: request.taskId ?? request.itemId ?? null,
+      itemId: request.itemId ?? request.taskId ?? null,
+      groupId: request.groupId ?? null,
+      approvalClasses,
+      status: 'approved',
+      reason: request.reason ?? null,
+    });
+    dispatchAgentEvent(session, createAgentEvent('approval.granted', {
+      origin: 'runtime',
+      runId,
+      taskId: grant.taskId,
+      workspace: workspaceId,
+      payload: grant,
+    }));
     return { approved: true, approvalId, runId, itemId: request.itemId ?? null };
   }
 
-  function approve({ approvalId = null, runId = null, itemId = null } = {}) {
+  function approve(request = {}) {
+    const { approvalId = null, runId = null, itemId = null } = request;
+    if (request.scope || request.planRevision != null || request.approvalClasses || request.approvalClass || request.taskId || request.groupId) {
+      const grant = normalizeApprovalGrant({
+        ...request,
+        id: request.id ?? request.approvalId ?? randomUUID(),
+        workspaceId: request.workspaceId ?? request.workspace ?? session.workspace ?? null,
+        scope: normalizeGrantScope(request.scope),
+        itemId: request.itemId ?? request.taskId ?? null,
+        status: 'approved',
+      });
+      dispatchAgentEvent(session, createAgentEvent('approval.granted', {
+        origin: 'runtime',
+        runId: grant.runId,
+        taskId: grant.taskId,
+        workspace: grant.workspaceId,
+        payload: grant,
+      }));
+      resolveMatchingPending(grant);
+      return {
+        approved: true,
+        approvalId: grant.approvalId ?? grant.id,
+        runId: grant.runId,
+        itemId: grant.itemId,
+        scope: grant.scope,
+        planRevision: grant.planRevision,
+        approvalClasses: grant.approvalClasses,
+      };
+    }
     const entry = approvalId
       ? pending.get(approvalId)
       : [...pending.values()].find((item) =>
@@ -96,6 +175,31 @@ export function createApprovalManager(session, {
     };
   }
 
+  function reject(request = {}) {
+    const grant = normalizeApprovalGrant({
+      ...request,
+      id: request.id ?? request.approvalId ?? randomUUID(),
+      workspaceId: request.workspaceId ?? request.workspace ?? session.workspace ?? null,
+      scope: normalizeGrantScope(request.scope),
+      status: 'rejected',
+    });
+    dispatchAgentEvent(session, createAgentEvent('approval.rejected', {
+      origin: 'runtime',
+      runId: grant.runId,
+      taskId: grant.taskId,
+      workspace: grant.workspaceId,
+      payload: grant,
+    }));
+    return {
+      approved: false,
+      rejected: true,
+      approvalId: grant.approvalId ?? grant.id,
+      runId: grant.runId,
+      itemId: grant.itemId,
+      scope: grant.scope,
+    };
+  }
+
   function list() {
     return [...pending.entries()].map(([approvalId, item]) => ({
       approvalId,
@@ -108,6 +212,31 @@ export function createApprovalManager(session, {
   return {
     requestApproval,
     approve,
+    reject,
     list,
   };
+
+  function resolveMatchingPending(grant) {
+    for (const entry of pending.values()) {
+      if (grant.approvalId && entry.approvalId === grant.approvalId) entry.resolve();
+      else if (grant.taskId && entry.taskId === grant.taskId) entry.resolve();
+      else if (grant.itemId && entry.itemId === grant.itemId) entry.resolve();
+      else if (grant.scope === 'run' && grant.runId && entry.runId === grant.runId) entry.resolve();
+      else continue;
+      break;
+    }
+  }
+}
+
+function normalizeGrantScope(scope) {
+  const normalized = String(scope ?? 'run').toLowerCase();
+  if (normalized === 'all') return 'run';
+  if (['run', 'task', 'group', 'tool'].includes(normalized)) return normalized;
+  return normalized === 'tool' ? 'tool' : 'run';
+}
+
+function normalizeClasses(value) {
+  if (value == null) return [];
+  const values = Array.isArray(value) ? value : [value];
+  return [...new Set(values.map((item) => String(item).trim()).filter(Boolean))];
 }

package/src/runtime/controlMessages.js

@@ -0,0 +1,43 @@
+// Deterministic, localized messages for the runtime control lane.
+//
+// Control-lane acknowledgements (run queued, ambiguous input, conversation
+// fallback…) are intentionally NOT generated by Donna: spending an LLM turn
+// to say "your request is queued" would reintroduce exactly the per-message
+// cost the orchestration refactor removed. But they are user-facing, so they
+// must follow the session's configured reply language. This catalog is the
+// single source for those strings — never hardcode a control-lane message in
+// the shell or the server directly.
+
+const CONTROL_MESSAGES = {
+  queued_for_future_run: {
+    en: 'Request added to the queue — it will start automatically after the current run.',
+    fr: 'Demande ajoutée à la file — elle démarrera automatiquement à la fin du run en cours.',
+  },
+  plan_patch_proposed: {
+    en: 'Plan patch proposed. Approve it explicitly to apply it to the active plan.',
+    fr: 'Modification de plan proposée. Approuvez-la explicitement pour l’appliquer au plan actif.',
+  },
+  ambiguous_control: {
+    en: 'The runtime cannot safely classify this message.',
+    fr: 'Le runtime ne peut pas classer ce message de façon sûre.',
+  },
+  converse_while_running: {
+    en: 'Runtime run is still active. This message was treated as conversation and did not create a queued run.',
+    fr: 'Un run est toujours actif. Ce message a été traité comme conversation et n’a pas créé de run en file.',
+  },
+  converse_while_idle: {
+    en: 'Runtime is idle. This message was treated as conversation and did not create a run.',
+    fr: 'Le runtime est inactif. Ce message a été traité comme conversation et n’a pas créé de run.',
+  },
+};
+
+export function controlLanguage(session) {
+  const raw = String(session?.language ?? 'en').toLowerCase();
+  return raw.startsWith('fr') ? 'fr' : 'en';
+}
+
+export function controlMessage(session, key) {
+  const entry = CONTROL_MESSAGES[key];
+  if (!entry) throw new Error(`Unknown control message key: ${key}`);
+  return entry[controlLanguage(session)] ?? entry.en;
+}

package/src/runtime/controlMessages.test.js

@@ -0,0 +1,21 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { controlLanguage, controlMessage } from './controlMessages.js';
+
+test('controlLanguage maps fr locales to fr and everything else to en', () => {
+  assert.equal(controlLanguage({ language: 'fr-FR' }), 'fr');
+  assert.equal(controlLanguage({ language: 'fr' }), 'fr');
+  assert.equal(controlLanguage({ language: 'en-US' }), 'en');
+  assert.equal(controlLanguage({ language: null }), 'en');
+  assert.equal(controlLanguage(null), 'en');
+});
+
+test('controlMessage returns the localized queued acknowledgement', () => {
+  assert.match(controlMessage({ language: 'fr-FR' }, 'queued_for_future_run'), /ajoutée à la file/);
+  assert.match(controlMessage({ language: 'en-US' }, 'queued_for_future_run'), /added to the queue/);
+});
+
+test('controlMessage falls back to en for unknown locales and throws on unknown keys', () => {
+  assert.match(controlMessage({ language: 'de-DE' }, 'queued_for_future_run'), /added to the queue/);
+  assert.throws(() => controlMessage({ language: 'fr-FR' }, 'nope'), /Unknown control message key/);
+});