@dotdrelle/wiki-manager 0.15.66 → 0.15.71

package/src/cli/wiki-manager.js

@@ -30,6 +30,7 @@ import { createAgentEvent, dispatchAgentEvent, reduceAgentEvents } from '../core
 import { runAgentTurn, runAgenticLoop } from '../core/agentLoop.js';
 import { resolveCapabilityConcurrency } from '../orchestrator/scheduler.js';
 import { capabilityRegistryForSession } from '../orchestrator/capabilityRegistry.js';
+import { CapabilityUnavailableError, resolve as resolveCapability } from '../orchestrator/capabilityResolver.js';
 import { listWorkspaces } from '../core/workspaces.js';
 import { findSkill } from '../core/skills.js';
 import { rememberArtifact } from '../core/currentArtifact.js';
@@ -69,6 +70,20 @@ function unavailableRuntime(err) {
   return { url: null, error: reason };
 }
 
+// The user-facing reason a capability cannot start — one sentence, the likely
+// cause, and the fix. The raw registry goes to the logs, never to the chat.
+function capabilityUnavailableMessage(capabilityId, seen = []) {
+  const agentic = String(capabilityId).startsWith('agent.');
+  const servicesDown = seen.some((entry) => /\[none\]$/.test(entry));
+  if (agentic) {
+    return `No agent provides capability ${capabilityId} — the agentic runtime is not enabled or not reachable. Enable it (GATEWAY_ENABLED=true + wiki-workspace agents up) and check /status.`;
+  }
+  if (servicesDown) {
+    return `No agent provides capability ${capabilityId} — the workspace services are not running. Start them (wiki-workspace up <workspace>), then retry.`;
+  }
+  return `No agent provides capability ${capabilityId} — no connected agent declares it. Check /status.`;
+}
+
 export function buildExecutorOnlyFragment({ objective, workspace, selection }) {
   const provider = selection.provider;
   const capability = provider.capability ?? {};
@@ -155,7 +170,7 @@ export async function resolveExecutorArguments({
     'Only fill a field when the objective explicitly states or clearly implies its value.',
     'Omit every field that is not stated. Never invent identifiers, queries, filters or counts.',
     // The objective almost always names the workspace ("export the pages of
-    // workspace acpi"), and the orchestrator already binds it out of band. With
+    // workspace acme"), and the orchestrator already binds it out of band. With
     // one free-text field in the schema and no field for the workspace, a model
     // reliably misbinds the two — that is how a workspace name ended up as a
     // source name and failed the task.
@@ -923,6 +938,7 @@ async function runRuntime(argv, agent) {
   const { startRuntimeServer } = await import('../runtime/server.js');
   const { recoverActiveRuns } = await import('../runtime/recoveryManager.js');
   const { emitRuntimeLog, startActivitySupervisor, cancelActiveActivityJobs, discoverAgentsOnce } = await import('../runtime/supervisor.js');
+  const { discoverRuntimeProvidersOnce } = await import('../orchestrator/providers/runtimeProviders.js');
   const { resolveRuntimeAuthToken } = await import('../runtime/auth.js');
   const { createSqliteQueueStore } = await import('../runtime/queueStore.js');
   const { createApprovalManager } = await import('../runtime/approvals.js');
@@ -950,6 +966,7 @@ async function runRuntime(argv, agent) {
     await Promise.all(resolved.map(async (context) => {
       await refreshMcpRuntimeStatus(context.session);
       await discoverAgentsOnce(context.session);
+      await discoverRuntimeProvidersOnce(context.session);
     }));
   }
 
@@ -1137,6 +1154,14 @@ async function runRuntime(argv, agent) {
     try {
       const context = await getWorkspaceContext(workspace);
       await refreshMcpRuntimeStatus(context.session);
+      // The supervisor kicks off agent + runtime-provider discovery fire-and-
+      // forget, so at boot `session.runtimeProviderAgents` is usually still
+      // undefined here. recoverActiveRuns resolves an external-runtime task by
+      // finding its synthetic agent in that list; without it the task falls to
+      // the MCP path, calls a non-existent server named after the capability,
+      // throws, and the run is interrupted instead of recovered. Await the same
+      // discovery the /run path already awaits (wiki-manager.js's turn setup).
+      await discoverRuntimeProvidersOnce(context.session);
       const gaps = recoveryMcpGaps(context);
       if (gaps.length > 0) {
         const interrupted = store.interruptRuns({ workspace: context.workspace });
@@ -1243,6 +1268,7 @@ async function runRuntime(argv, agent) {
     // live endpoints and await one discovery pass before resolving.
     await refreshMcpRuntimeStatus(session);
     await discoverAgentsOnce(session, { registry: session.agentRegistry });
+    await discoverRuntimeProvidersOnce(session);
     let selection;
     try {
       selection = await resolveObjective(objective, session);
@@ -1457,11 +1483,37 @@ async function runRuntime(argv, agent) {
       if (body.capabilityPlan?.capability) {
         const { validateFragment } = await import('../orchestrator/planValidator.js');
         const { integrate } = await import('../orchestrator/planIntegrator.js');
+        // Same boot-race guard as prepareDelegation below: discovery is
+        // asynchronous at startup, so a structured capability run submitted
+        // right after boot must not observe the transient empty registry and
+        // fail while the provider is already healthy (first E2E run of the
+        // day did exactly that: "No agent provides capability agent.review"
+        // while the gateway answered /health).
+        await refreshMcpRuntimeStatus(session);
+        await discoverAgentsOnce(session, { registry: session.agentRegistry });
+        await discoverRuntimeProvidersOnce(session);
         const registry = capabilityRegistryForSession(session);
-        const agents = session.agentRegistry?.snapshot?.() ?? session.agentRegistrySnapshot ?? [];
-        const provider = agents.find((item) => (item.description?.capabilities ?? [])
-          .some((capability) => capability.id === body.capabilityPlan.capability));
-        if (!provider?.serverName) {
+        const capabilityId = String(body.capabilityPlan.capability);
+        const candidates = registry.providersFor(capabilityId) ?? [];
+        // Route through the same resolver every other task assignment uses
+        // (assignmentManager.js, resultAggregator.js), instead of a bespoke
+        // "prefer external-runtime, else any with serverName" chain that
+        // ignored the workspace's own capabilityRouting config (preferred/
+        // allowed/fallback agents) and never checked health/availability at
+        // all — this could hand a direct /run capability request to a
+        // disallowed or unhealthy agent while every other entry point honors
+        // the routing config.
+        const workspaceConfig = session?.wikircConfig ?? session?.wikirc?.config ?? {};
+        let provider = null;
+        let resolutionReason = null;
+        try {
+          const resolved = resolveCapability(capabilityId, { workspaceConfig, registry });
+          provider = candidates.find((item) => item.agentInstanceId === resolved.agentInstanceId) ?? null;
+        } catch (error) {
+          if (!(error instanceof CapabilityUnavailableError)) throw error;
+          resolutionReason = error.reason;
+        }
+        if (!provider) {
           /*
            Say what WAS seen, not only what was missing.
 
@@ -1471,38 +1523,60 @@ async function runRuntime(argv, agent) {
            PRODUCTION_ALLOWED_STEPS drops its whole capability from
            agent_describe, silently), or a name mismatch. Listing the registry
            turns the next occurrence into its own diagnosis instead of a guess.
-          */
-          const seen = agents.map((item) => {
-            const ids = (item.description?.capabilities ?? []).map((capability) => capability.id);
-            return `${item.serverName ?? '?'}[${ids.join(', ') || 'none'}]`;
-          });
-          throw new Error(
-            `No agent provides capability ${body.capabilityPlan.capability}. `
-            + (seen.length
-              ? `Registered agents: ${seen.join('; ')}.`
-              : 'No agent is registered: none answered agent_describe.'),
-          );
+           */
+          const seen = [
+            ...(session.agentRegistry?.snapshot?.() ?? session.agentRegistrySnapshot ?? []),
+            ...(session.runtimeProviderAgents ?? []),
+          ].map((item) => {
+              const ids = (item.description?.capabilities ?? []).map((capability) => capability.id);
+              return `${item.serverName ?? item.runtimeId ?? '?'}[${ids.join(', ') || 'none'}]`;
+            });
+          // The raw registry stays for diagnosis, in the LOGS — never in the
+          // user-facing message, which explains the likely cause instead.
+          emitRuntimeLog(session, `capability-plan: ${capabilityId} unresolvable (${resolutionReason ?? 'no_candidate'}) — registry: ${seen.join('; ') || 'no agent answered agent_describe'}`);
+          const error = new Error(capabilityUnavailableMessage(capabilityId, seen));
+          error.code = 'capability_unavailable';
+          throw error;
         }
-        const fragment = parseJsonText(formatMcpToolResult(await callMcpTool(session.mcp, provider.serverName, 'agent_plan', {
-          capability: body.capabilityPlan.capability,
-          operation: body.capabilityPlan.operation ?? undefined,
-          workspace: { revision: String(Date.now()) },
-          constraints: {
-            // The agent declares its capacity. Request/env values are only
-            // constraints: they may lower that capacity, never raise it.
-            maxConcurrency: resolveCapabilityConcurrency(
-              provider,
-              body.capabilityPlan.maxConcurrency,
-              process.env.WIKI_MANAGER_CAPABILITY_CONCURRENCY,
-            ),
-            requireApprovalForMutations: body.capabilityPlan.requireApproval !== false,
-          },
-          ...(body.capabilityPlan.arguments && typeof body.capabilityPlan.arguments === 'object'
-            ? { arguments: body.capabilityPlan.arguments }
-            : Array.isArray(body.capabilityPlan.inputs) && body.capabilityPlan.inputs.length > 0
-              ? { arguments: { inputs: body.capabilityPlan.inputs } }
-              : {}),
-        })));
+        const operation = body.capabilityPlan.operation
+          ?? provider.capability?.supportedOperations?.[0]
+          ?? 'run';
+        const canPlan = provider.description?.orchestration?.canPlan !== false;
+        const fragment = canPlan
+          ? parseJsonText(formatMcpToolResult(await callMcpTool(session.mcp, provider.serverName, 'agent_plan', {
+              capability: capabilityId,
+              operation,
+              workspace: { revision: String(Date.now()) },
+              constraints: {
+                // The agent declares its capacity. Request/env values are only
+                // constraints: they may lower that capacity, never raise it.
+                maxConcurrency: resolveCapabilityConcurrency(
+                  provider,
+                  body.capabilityPlan.maxConcurrency,
+                  process.env.WIKI_MANAGER_CAPABILITY_CONCURRENCY,
+                ),
+                requireApprovalForMutations: body.capabilityPlan.requireApproval !== false,
+              },
+              ...(body.capabilityPlan.arguments && typeof body.capabilityPlan.arguments === 'object'
+                ? { arguments: body.capabilityPlan.arguments }
+                : Array.isArray(body.capabilityPlan.inputs) && body.capabilityPlan.inputs.length > 0
+                  ? { arguments: { inputs: body.capabilityPlan.inputs } }
+                  : {}),
+            })))
+          : buildExecutorOnlyFragment({
+              objective: `Capability run ${capabilityId}`,
+              workspace: session.workspace ?? 'workspace',
+              selection: {
+                capability: capabilityId,
+                operation,
+                provider,
+                arguments: body.capabilityPlan.arguments && typeof body.capabilityPlan.arguments === 'object'
+                  ? body.capabilityPlan.arguments
+                  : Array.isArray(body.capabilityPlan.inputs) && body.capabilityPlan.inputs.length > 0
+                    ? { inputs: body.capabilityPlan.inputs }
+                    : {},
+              },
+            });
         if (!Array.isArray(fragment?.tasks) || fragment.tasks.length === 0) {
           dispatchAgentEvent(session, createAgentEvent('assistant_message', {
             origin: 'runtime',
@@ -1534,7 +1608,18 @@ async function runRuntime(argv, agent) {
         if (!integrated.ok) {
           throw new Error(`Capability plan integration failed: ${(integrated.errors ?? []).map((error) => error.message ?? error.code ?? String(error)).join('; ')}`);
         }
-        emitRuntimeLog(session, `capability-plan: ${fragment.tasks.length} task(s) integrated from ${provider.serverName}.agent_plan (${body.capabilityPlan.capability}); approvals: ${(session.agentProjection?.approvals ?? []).filter((approval) => approval.status === 'pending_approval').length} pending`);
+        // The structured path integrates the plan directly, so it must honor
+        // the same explicit opt-in as the delegation path (delegation.js
+        // `resolvePreparedDelegationApproval`): autoApprove grants one
+        // run-scoped approval right after integration. Without it, a
+        // headless/CI caller with autoApprove:true deadlocks on the
+        // scheduler's approval gate until the timeout — first E2E research
+        // run did exactly that.
+        if (body.autoApprove === true) {
+          const { resolvePreparedDelegationApproval } = await import('../runtime/delegation.js');
+          resolvePreparedDelegationApproval({ autoApprove: true, approvalManager: context.approvalManager, runId });
+        }
+        emitRuntimeLog(session, `capability-plan: ${fragment.tasks.length} task(s) integrated${provider.serverName ? ` from ${provider.serverName}.agent_plan` : ''} (${body.capabilityPlan.capability}); approvals: ${(session.agentProjection?.approvals ?? []).filter((approval) => approval.status === 'pending_approval').length} pending`);
       }
       await runRuntimeAgenticWorkflow(agent, session, input, {
         signal,
@@ -1568,6 +1653,9 @@ async function runRuntime(argv, agent) {
         payload: {
           runId,
           message: err instanceof Error ? err.message : String(err),
+          // UIs map this to amber ("service not available") instead of red
+          // ("the run failed"): the run could not START, it did not crash.
+          ...(err?.code === 'capability_unavailable' ? { kind: 'capability_unavailable' } : {}),
         },
       }));
     } finally {

package/src/cli/wiki-manager.test.js

@@ -66,7 +66,7 @@ test('interactive runtime refreshes configured MCP endpoints that started late',
 test('executor-only capabilities receive one manager-authored executable task', () => {
   const fragment = buildExecutorOnlyFragment({
     objective: 'donne-moi mes derniers mails',
-    workspace: 'juno',
+    workspace: 'demo',
     selection: {
       capability: 'external-source.collect',
       operation: 'collect',
@@ -91,7 +91,7 @@ test('executor-only capabilities receive one manager-authored executable task',
   assert.equal(fragment.tasks[0].requiredCapability, 'external-source.collect');
   assert.equal(fragment.tasks[0].operation, 'collect');
   assert.deepEqual(fragment.tasks[0].arguments, { maxMessages: 10 });
-  assert.deepEqual(fragment.tasks[0].locks, ['external-source.collect:juno']);
+  assert.deepEqual(fragment.tasks[0].locks, ['external-source.collect:demo']);
   assert.equal(fragment.tasks[0].requiresApproval, true);
   assert.equal(fragment.tasks[0].approvalClass, 'external-source');
   assert.match(fragment.tasks[0].idempotencyKey, /^[0-9a-f-]{36}$/);
@@ -263,14 +263,14 @@ const EXPORT_CAPABILITY = {
 };
 
 test('argument extraction drops a value that only echoes the active workspace', async () => {
-  // Regression: "exporter les pages Confluence du workspace acpi" against a
+  // Regression: "export the Confluence pages of the acme workspace" against a
   // schema whose single free-text field is source_name. The model binds the
-  // workspace name to it, and the executor fails with "source 'acpi' not
+  // workspace name to it, and the executor fails with "source 'acme' not
   // found". The workspace is already bound out of band, so the echo is noise.
   const llm = {
     completeWithTools: async () => ({
       tool_calls: [{
-        function: { name: 'set_task_arguments', arguments: JSON.stringify({ source_name: 'acpi' }) },
+        function: { name: 'set_task_arguments', arguments: JSON.stringify({ source_name: 'acme' }) },
       }],
     }),
   };
@@ -278,9 +278,9 @@ test('argument extraction drops a value that only echoes the active workspace',
   assert.deepEqual(
     await resolveExecutorArguments({
       llm,
-      objective: 'exporter les pages Confluence du workspace acpi',
+      objective: 'export the Confluence pages of the acme workspace',
       capability: EXPORT_CAPABILITY,
-      workspace: 'acpi',
+      workspace: 'acme',
     }),
     {},
   );
@@ -303,7 +303,7 @@ test('argument extraction keeps a real value that is not the workspace name', as
       llm,
       objective: 'exporter la source EAS_Avant_projet_ACPI',
       capability: EXPORT_CAPABILITY,
-      workspace: 'acpi',
+      workspace: 'acme',
     }),
     { source_name: 'EAS_Avant_projet_ACPI' },
   );
@@ -320,17 +320,17 @@ test('argument extraction tells the model the workspace is already bound', async
 
   await resolveExecutorArguments({
     llm,
-    objective: 'exporter les pages du workspace acpi',
+    objective: 'export the pages of the acme workspace',
     capability: EXPORT_CAPABILITY,
-    workspace: 'acpi',
+    workspace: 'acme',
   });
 
-  assert.match(seenSystem, /already runs against workspace "acpi"/);
+  assert.match(seenSystem, /already runs against workspace "acme"/);
 });
 
 test('argument extraction rejects a value outside the closed vocabulary', async () => {
-  // Regression: "exporter les pages Confluence du workspace juno" — the
-  // workspace guard removes "juno", so the model reaches for the next noun and
+  // Regression: "export the Confluence pages of the demo workspace" — the
+  // workspace guard removes "demo", so the model reaches for the next noun and
   // emits "Confluence". Only the agent knows the valid names; once it publishes
   // them as an enum, the orchestrator can check without guessing at meaning.
   const capability = {
@@ -354,9 +354,9 @@ test('argument extraction rejects a value outside the closed vocabulary', async
   assert.deepEqual(
     await resolveExecutorArguments({
       llm,
-      objective: 'exporter les pages Confluence du workspace juno',
+      objective: 'export the Confluence pages of the demo workspace',
       capability,
-      workspace: 'juno',
+      workspace: 'demo',
     }),
     {},
   );
@@ -389,7 +389,7 @@ test('argument extraction keeps a value the vocabulary allows', async () => {
       llm,
       objective: 'exporter la source EAS_Avant_projet_ACPI',
       capability,
-      workspace: 'acpi',
+      workspace: 'acme',
     }),
     { source_name: 'EAS_Avant_projet_ACPI' },
   );

package/src/commands/slash.js

@@ -30,6 +30,7 @@ import { findSkill, inspectSkills, listSkills } from '../core/skills.js';
 import { extractActivity, formatActivityError, formatActivityLine, formatActivitySummary, parseJsonText } from '../core/activity.js';
 import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
 import { emitRuntimeLog } from '../runtime/supervisor.js';
+import { discoverRuntimeProvidersOnce } from '../orchestrator/providers/runtimeProviders.js';
 import {
   cancelQueueItem,
   clearFinishedQueueItems,
@@ -660,8 +661,34 @@ function reportNewlyDegradedMcp(session, previousMcp) {
   }
 }
 
+function runtimeProvidersSection(session) {
+  const agents = session.runtimeProviderAgents ?? [];
+  if (agents.length === 0) return null;
+  const byRuntime = new Map();
+  for (const agent of agents) {
+    const runtimeId = agent.runtimeId ?? 'external';
+    if (!byRuntime.has(runtimeId)) byRuntime.set(runtimeId, []);
+    byRuntime.get(runtimeId).push(agent);
+  }
+  const lines = [];
+  for (const [runtimeId, list] of byRuntime) {
+    const health = list[0]?.health ?? 'unknown';
+    const capabilities = list
+      .map((agent) => agent.description?.capabilities?.[0]?.id ?? agent.agentInstanceId);
+    lines.push(`${runtimeId}: ${health}`);
+    // One capability per line: the status pane is a fixed-width box that
+    // TRUNCATES long lines, and a joined list ended mid-word
+    // ("capabilities: agent.review, agent.research, agent"). A per-line list
+    // never truncates and stays scannable.
+    lines.push('capabilities:');
+    for (const capability of capabilities) lines.push(`    ${capability}`);
+  }
+  return sectionBlock('Agentic runtime', lines);
+}
+
 async function statusText(session) {
   const states = await refreshMcpRuntimeStatus(session);
+  await discoverRuntimeProvidersOnce(session);
   const workspaceStats = collectWorkspaceStats(session);
   const workspaceColumn = sectionBlock(`Workspace · ${session.workspace ?? '-'}`, [
     `path: ${compactPath(session.workspacePath ?? '-')}`,
@@ -678,11 +705,20 @@ async function statusText(session) {
     `baseUrl: ${compactBaseUrl(session.wikircConfig?.llm?.baseUrl)}`,
     ...(skillDiagnosticCount ? [`skill diagnostics: ${skillDiagnostics.rejected.length} rejected, ${skillDiagnostics.warnings.length} warning(s) (/skills)`] : []),
   ]);
-  const runtimeColumn = sectionBlock('Runtime', (states ? serviceStatesText(states) : 'Docker runtime not available or no workspace loaded.').split('\n'));
+  // The workspace stack (serve / mcp-http / production-mcp) only means
+  // something once a workspace is loaded AND services are actually declared;
+  // an empty list is noise either way. Named "Services" (not "Runtime") to
+  // avoid colliding with the "Agentic runtime" section that lists the
+  // external engines.
+  const hasServices = Boolean(states && Object.keys(states).length > 0);
+  const runtimeColumn = hasServices
+    ? sectionBlock('Services', serviceStatesText(states).split('\n'))
+    : null;
   const mcpColumn = sectionBlock('MCP', compactMcpStatus(session.mcp).split('\n'));
+  const runtimesColumn = runtimeProvidersSection(session);
   const stats = workspaceStatsColumns(workspaceStats, session);
 
-  const leftColumn = [workspaceColumn, stats.left, runtimeColumn, mcpColumn].filter(Boolean).join('\n\n');
+  const leftColumn = [workspaceColumn, stats.left, runtimeColumn, mcpColumn, runtimesColumn].filter(Boolean).join('\n\n');
   const rightColumn = [configColumn, stats.right].filter(Boolean).join('\n\n');
 
   // Leading/trailing blank row so the boxed pair doesn't butt directly against
@@ -850,12 +886,13 @@ function componentInstallAction(missingImages) {
   return missingImages.length > 0 ? 'downloaded-and-installed-missing-components' : null;
 }
 
-export function localizedOperationResult({ operation, target, status = 'succeeded', componentAction = null, images = [] }) {
+export function localizedOperationResult({ operation, target, status = 'succeeded', componentAction = null, images = [], detail = null }) {
   const facts = JSON.stringify({
     operation,
     target,
     status,
     ...(componentAction ? { componentAction, images } : {}),
+    ...(detail ? { detail } : {}),
   });
   return {
     output: facts,
@@ -937,7 +974,10 @@ export async function handleSlashCommand(line, context) {
   const runAgentCommand = async (fn, verb) => {
     try {
       step(`Agents: ${verb}ing external agents…`);
-      const missingImages = await collectMissingImages(step, fn);
+      let outcome = null;
+      const missingImages = await collectMissingImages(step, async (options) => {
+        outcome = await fn(options);
+      });
       if (verb === 'start') {
         // `wiki-workspace agents up` generates the agent tokens into the
         // manager .env and adds the profiled entries to mcp.endpoints.json.
@@ -951,6 +991,17 @@ export async function handleSlashCommand(line, context) {
         loadManagerEnv({ override: true });
         await refreshMcpRuntimeStatus(context.session);
       }
+      if (outcome?.degraded) {
+        step('Agents: stack started degraded — one optional agent failed; the base agents are up.');
+        return localizedOperationResult({
+          operation: verb,
+          target: 'agents',
+          status: 'degraded',
+          componentAction: componentInstallAction(missingImages),
+          images: missingImages,
+          detail: rawFailureText(outcome.degradedError),
+        });
+      }
       return localizedOperationResult({
         operation: verb,
         target: 'agents',
@@ -1396,7 +1447,10 @@ export async function handleSlashCommand(line, context) {
           },
         });
         if (result?.runId) {
-          return { output: `▶ Capability run accepted (${String(result.runId).slice(0, 8)}) — the agent's plan will be integrated and dispatched in parallel; approval requested before mutations (/approve).` };
+          // Honest and generic: the runtime decides, per task, whether a
+          // mutation needs approval. Claiming "awaiting approval" here would
+          // be false for read-only capabilities like agent.review.
+          return { output: `▶ Capability run accepted (${String(result.runId).slice(0, 8)}) — the plan will be integrated and dispatched in parallel; any mutating step will wait for /approve.` };
         }
         return { output: `Run not started: ${result?.explanation ?? result?.error ?? JSON.stringify(result)}` };
       }

package/src/contracts/schemas.js

@@ -330,6 +330,71 @@ const patchTaskSchema = {
   },
 };
 
+const runtimeCapabilitySchema = {
+  type: 'object',
+  required: ['name'],
+  additionalProperties: true,
+  properties: {
+    name: { type: 'string', minLength: 1 },
+    description: { type: 'string' },
+    operations: stringArraySchema,
+    aliases: stringArraySchema,
+    aliasOperations: { type: 'object', additionalProperties: true },
+    mutationClass: { type: 'string' },
+    defaultRequiresApproval: { type: 'boolean' },
+  },
+};
+
+const runtimeDescriptionSchema = {
+  $id: 'https://dotdrelle.dev/wiki-manager/contracts/runtime-description/v1',
+  title: 'RuntimeDescription',
+  schemaVersion: '1',
+  type: 'object',
+  required: ['runtime', 'version', 'protocolVersion'],
+  additionalProperties: true,
+  properties: {
+    runtime: { type: 'string', minLength: 1 },
+    version: { type: 'string', minLength: 1 },
+    protocolVersion: { type: 'string', minLength: 1 },
+    health: { type: 'string' },
+    capabilities: { type: 'array', items: runtimeCapabilitySchema },
+  },
+};
+
+const runtimeEventSchema = {
+  $id: 'https://dotdrelle.dev/wiki-manager/contracts/runtime-event/v1',
+  title: 'RuntimeEvent',
+  schemaVersion: '1',
+  type: 'object',
+  required: ['type'],
+  additionalProperties: true,
+  properties: {
+    type: {
+      type: 'string',
+      enum: [
+        'run_created',
+        'run_started',
+        'agent_thinking',
+        'tool_started',
+        'tool_finished',
+        'subagent_started',
+        'subagent_finished',
+        'message',
+        'approval_required',
+        'run_completed',
+        'run_failed',
+        'run_cancelled',
+      ],
+    },
+    runId: { type: 'string' },
+    tool: { type: 'string' },
+    durationMs: { type: 'number' },
+    resultSummary: { type: 'string' },
+    error: nullableString,
+    args: nullableObject,
+  },
+};
+
 export const contractSchemas = {
   activity: {
     $id: 'https://dotdrelle.dev/wiki-manager/contracts/activity/v1',
@@ -462,6 +527,8 @@ export const contractSchemas = {
   plannedTask: plannedTaskSchema,
   taskGraphFragment: taskGraphFragmentSchema,
   planExpansionRequest: planExpansionRequestSchema,
+  runtimeDescription: runtimeDescriptionSchema,
+  runtimeEvent: runtimeEventSchema,
 };
 
 export function validateContract(name, value) {

package/src/core/activity.js

@@ -214,6 +214,11 @@ export function mergePolledActivity(tracked, polled) {
     // Identity: keep the tracked source/id so activityKey() stays stable.
     id: tracked.id ?? polled.id,
     source: tracked.source ?? polled.source,
+    // A later poll often reports only {status, progress} with no phase/type,
+    // and activityFromStatusPayload then falls back to the generic 'job' —
+    // spreading that over the tracked value degraded a real kind (e.g.
+    // 'knowledge.update') to 'job' on the very next poll tick.
+    kind: tracked.kind ?? polled.kind,
     // Keep polling with the descriptor that worked when the agent's answer
     // does not carry one of its own.
     poll: polled.poll ?? tracked.poll,