@dotdrelle/wiki-manager 0.8.2 → 0.10.4

package/README.md

@@ -460,6 +460,21 @@ or the shell command `/approve item <id>`. The approval timeout defaults to 10
 minutes and can be changed with `WIKI_MANAGER_APPROVAL_TIMEOUT_MS` or
 `approvalTimeoutMs` in the `/run` body.
 
+While a run is active, `GET`/`POST /control` still answers without waiting for
+it to finish: `{"action":"status"}` returns the current run/plan/queue state,
+`{"action":"explain"}` adds a one-line plain-language summary, and
+`{"action":"enqueue","input":"..."}` accepts a new request without touching the
+active plan. A queued request starts automatically as soon as the workspace
+goes idle — either because the enqueue call itself found the workspace free,
+or because the run in progress finished and drained the next queued item.
+
+`GET /config/profiles` lists the `.wikirc` profiles for a workspace and
+`POST /config/use {"profile":"..."}` switches the active one — the same
+switch as the shell's `/config use`, rejected with 409 while a run is active.
+The manager is the source of truth for which profile is active; `llm-wiki
+serve`'s config-profile picker mirrors whatever the manager reports rather
+than tracking its own state.
+
 ### Starting external agents
 
 Start CME, documents, and mailer once for all workspaces:
@@ -512,13 +527,17 @@ The shared `docker-compose.yml` starts one workspace stack:
 
 | Service | Role | Port variable |
 | --- | --- | --- |
-| `serve` | Wiki web UI and browser chat | `WIKI_SERVE_PORT` |
-| `mcp-http` | llm-wiki MCP endpoint | `WIKI_MCP_PORT` |
-| `production-mcp` | Production job MCP endpoint | `PRODUCTION_MCP_PORT` |
+| `serve` | Wiki web UI and browser chat, container port `3000` | `WIKI_SERVE_PORT` |
+| `mcp-http` | llm-wiki MCP endpoint, container port `3333` | `WIKI_MCP_PORT` |
+| `production-mcp` | Production job MCP endpoint, container port `8080` | `PRODUCTION_MCP_PORT` |
 
 Use `wiki-workspace` whenever possible so Compose receives the right project
 name, env file, ports, and volume mounts.
 
+Runtime split: the host manager/runtime uses Node.js 22+ for `node:sqlite`; the
+interactive OpenTUI shell uses Bun 1.2+; workspace Docker services run from the
+published images and do not depend on host `node_modules`.
+
 ```bash
 wiki-workspace list
 wiki-workspace agents up
@@ -784,12 +803,23 @@ Files matching `docker-compose*.local.yml` are ignored by Git.
 ```bash
 pnpm install
 pnpm start
+pnpm run check-versions
 pnpm run check
 ```
 
-When bumping the package version, update both `package.json` and the Streamable
-HTTP MCP `clientInfo.version` in `src/core/mcp.js`. They are kept explicit so
-remote MCP server logs show the manager build that initiated the handshake.
+When bumping a coordinated release, keep `llm-wiki`, `llm-wiki-manager`, Python
+agent `_AGENT_VERSION` values, MCP `clientInfo.version` / server versions, Git
+tags, and Docker image tags aligned. Run:
+
+```bash
+pnpm run check-versions
+CHECK_GIT_TAG=1 pnpm run check-versions          # pre-release tag check
+CHECK_DOCKER_IMAGES=1 pnpm run check-versions    # after local image build
+```
+
+`build-and-push.sh` synchronizes the coordinated version, runs
+`pnpm run check-versions`, builds images tagged with that version, and can push
+the matching `latest` tags.
 
 `pnpm run check` verifies the CLI version, help output, and limited `--once` mode.
 For headless changes, also test a controlled error path, for example:

package/agents.docker-compose.yml

@@ -21,6 +21,7 @@
 #   MAILERSEND_API_KEY
 #   MAILERSEND_FROM_EMAIL
 #   MAILERSEND_FROM_NAME
+#   MAILERSEND_CA_CERT    — optional CA bundle path inside the container
 #
 # Set these variables in a .env file at the directory where you run wiki-workspace,
 # or export them in your shell before running wiki-workspace agents up.
@@ -90,7 +91,11 @@ services:
       - MAILERSEND_FROM_NAME=${MAILERSEND_FROM_NAME:-Mailer Agent}
       - MAILERSEND_USER_AGENT=${MAILERSEND_USER_AGENT:-curl/8.7.1}
       - MAILERSEND_VERIFY_SSL=${MAILERSEND_VERIFY_SSL:-true}
+      - MAILERSEND_CA_CERT=${MAILERSEND_CA_CERT:-}
       - MAILER_REQUIRE_CONFIRMATION=${MAILER_REQUIRE_CONFIRMATION:-true}
       - MAILER_DRY_RUN=${MAILER_DRY_RUN:-false}
       - MCP_AUTH_TOKEN=${MAILER_MCP_AUTH_TOKEN:-}
+    volumes:
+      # Optional: mount a CA bundle and set MAILERSEND_CA_CERT to its container path.
+      #- ${AGENTS_DATA_DIR:-./.agents-data}/certs:/certs:ro
     restart: unless-stopped

package/package.json

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

package/src/agent/graph.js

@@ -66,8 +66,26 @@ const WIKI_PLAN_SET_TOOL = {
       properties: {
         steps: {
           type: 'array',
-          items: { type: 'string' },
-          description: 'Ordered step descriptions, e.g. ["CME export", "Production ingest", "Build", "Polish", "Email report"].',
+          items: {
+            anyOf: [
+              { type: 'string' },
+              {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                  id: { type: 'string' },
+                  description: { type: 'string' },
+                  status: { type: 'string', enum: ['pending', 'queued', 'running', 'waiting', 'pending_approval', 'done', 'failed', 'cancelled', 'stalled', 'added_during_run'] },
+                  dependsOn: { type: 'array', items: { type: 'string' } },
+                  executor: { type: ['string', 'null'] },
+                  executorQuery: { type: ['object', 'null'], additionalProperties: true },
+                  outputRefs: { type: 'array', items: { type: 'string' } },
+                },
+                required: ['description'],
+              },
+            ],
+          },
+          description: 'Ordered steps. Backward-compatible strings are accepted; structured steps may include id, dependsOn, executor, executorQuery, outputRefs.',
         },
       },
       required: ['steps'],
@@ -344,11 +362,7 @@ function handleWikiTool(session, tool, args) {
   if (tool === 'plan_set') {
     const steps = Array.isArray(args.steps) ? args.steps : [];
     emitAgentEvent(session, 'plan_set', 'tool', {
-      steps: steps.map((description, i) => ({
-        step: i + 1,
-        description: String(description),
-        status: 'pending',
-      })),
+      steps: steps.map((raw, i) => normalizeDeclaredPlanStep(raw, i, session)),
     });
     return `Plan registered: ${steps.length} step${steps.length !== 1 ? 's' : ''}.`;
   }
@@ -364,6 +378,51 @@ function handleWikiTool(session, tool, args) {
   return `Unknown wiki tool: ${tool}`;
 }
 
+function normalizeDeclaredPlanStep(raw, index, session) {
+  const item = raw && typeof raw === 'object' && !Array.isArray(raw)
+    ? raw
+    : { description: String(raw) };
+  const description = String(item.description ?? item.label ?? item.name ?? item.id ?? `Step ${index + 1}`);
+  return {
+    step: Number(item.step ?? index + 1),
+    id: item.id ? String(item.id) : slugStepId(description, index),
+    description,
+    status: item.status ?? 'pending',
+    dependsOn: Array.isArray(item.dependsOn) ? item.dependsOn.map(String) : [],
+    executor: item.executor ?? selectExecutorForStep(description, session),
+    executorQuery: item.executorQuery ?? null,
+    outputRefs: Array.isArray(item.outputRefs) ? item.outputRefs.map(String) : [],
+  };
+}
+
+function slugStepId(description, index) {
+  const slug = String(description)
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48);
+  return slug || `task-${index + 1}`;
+}
+
+function selectExecutorForStep(description, session) {
+  const text = String(description ?? '').toLowerCase();
+  let fallback = null;
+  for (const [serverName, value] of Object.entries(session.mcp ?? {})) {
+    if (value.status !== 'connected') continue;
+    for (const tool of value.tools ?? []) {
+      const executor = `${serverName}.${tool.name}`;
+      fallback ??= executor;
+      const haystack = `${serverName} ${tool.name} ${tool.description ?? ''}`.toLowerCase();
+      if (text.split(/[^a-z0-9]+/).filter((token) => token.length >= 4).some((token) => haystack.includes(token))) {
+        return executor;
+      }
+    }
+  }
+  return fallback;
+}
+
 export function buildAgentSystemPrompt(state) {
   const workspace = state.session.workspace ?? 'no workspace selected';
   const wikirc = state.session.wikirc?.profile ?? 'no profile loaded';
@@ -401,8 +460,8 @@ export function buildAgentSystemPrompt(state) {
       '',
       'Task startup:',
       '  1. If the next MCP tool returns _activity.plan.steps, call that tool directly; the shell will create the visible plan from the returned activity.',
-      '  2. If the tool cannot declare its own plan, call wiki__plan_set(steps=["Step description", ...]) before executing the first step.',
-      '     Multi-tool example: wiki__plan_set(steps=["CME export", "Production pipeline", "Email report"])',
+      '  2. If the tool cannot declare its own plan, call wiki__plan_set before executing the first step. Prefer structured steps: {id, description, dependsOn, executor, executorQuery, outputRefs}; a legacy list of strings is still accepted.',
+      '     Multi-tool example: wiki__plan_set(steps=[{id:"cme-export",description:"CME export",dependsOn:[],executor:"cme.cme_export_run",outputRefs:["raw/untracked"]},{id:"production",description:"Production pipeline",dependsOn:["cme-export"],executor:"production.production_start_job",outputRefs:["deliverables"]}])',
       '  3. Immediately execute the first step using the appropriate MCP tool. Do not start step 2 in the same turn unless one async pipeline tool owns and declares the whole sequence.',
       '  For synchronous steps (result is immediate, no _activity polling), call wiki__plan_done(step=1) after confirming success.',
       '  For async MCP jobs (returns _activity with poll), the orchestrator tracks completion automatically.',

package/src/agent/graph.test.js

@@ -143,3 +143,67 @@ test('agent graph waits for tool-level approval configured on endpoint', async (
   }
 });
 
+test('agent graph accepts structured wiki plan steps and selects MCP executors', async () => {
+  let calls = 0;
+  const session = sessionBase({
+    mcp: {
+      cme: {
+        status: 'connected',
+        url: 'http://127.0.0.1:3001/mcp/',
+        tools: [{
+          name: 'cme_export_run',
+          description: 'Export CME pages',
+          inputSchema: { type: 'object', properties: {} },
+        }],
+      },
+      production: {
+        status: 'connected',
+        url: 'http://127.0.0.1:3000/mcp/',
+        tools: [{
+          name: 'production_start_job',
+          description: 'Start production job',
+          inputSchema: { type: 'object', properties: { type: { type: 'string' } } },
+        }],
+      },
+    },
+    llm: {
+      async completeWithTools() {
+        calls += 1;
+        if (calls === 1) {
+          return {
+            content: null,
+            message: { role: 'assistant', content: null },
+            tool_calls: [{
+              id: 'plan-call',
+              type: 'function',
+              function: {
+                name: 'wiki__plan_set',
+                arguments: JSON.stringify({
+                  steps: [
+                    { id: 'cme-export', description: 'Export CME pages', outputRefs: ['raw/untracked'] },
+                    { id: 'build', description: 'Run production build', dependsOn: ['cme-export'] },
+                  ],
+                }),
+              },
+            }],
+          };
+        }
+        return {
+          content: 'Plan ready.',
+          message: { role: 'assistant', content: 'Plan ready.' },
+          tool_calls: null,
+        };
+      },
+    },
+  });
+
+  const agent = createAgentGraph();
+  const result = await agent.invoke({ input: 'Plan export then build', session });
+
+  assert.equal(result.response, 'Plan ready.');
+  assert.deepEqual(session.headlessPlan.map((step) => step.id), ['cme-export', 'build']);
+  assert.equal(session.headlessPlan[0].executor, 'cme.cme_export_run');
+  assert.equal(session.headlessPlan[1].executor, 'production.production_start_job');
+  assert.deepEqual(session.headlessPlan[1].dependsOn, ['cme-export']);
+  assert.deepEqual(session.headlessPlan[0].outputRefs, ['raw/untracked']);
+});

package/src/cli/wiki-manager.js

@@ -8,6 +8,8 @@ import { createAgentGraph } from '../agent/graph.js';
 import { handleSlashCommand, printHelp, printVersion, refreshMcpRuntimeStatus } from '../commands/slash.js';
 import { runShell } from '../shell/repl.js';
 import { runChecks } from '../core/startupCheck.js';
+import { applySessionWikircProfile } from '../core/sessionConfig.js';
+import { listWikircProfiles } from '../core/wikirc.js';
 import { callMcpTool, formatMcpToolResult } from '../core/mcp.js';
 import { extractActivity, parseJsonText, sessionActivities, terminalFailures } from '../core/activity.js';
 import { syncActivitiesToPlan, formatPlanStatus } from '../core/plan.js';
@@ -161,7 +163,7 @@ async function runHeadlessAgenticLoop(agent, session, initialInput, log, { timeo
       console.log(response);
     },
     onPlanExtracted: ({ steps }) => {
-      log.push(`agentic-loop: plan extracted from text (${steps.length} steps, fallback)`);
+      log.push(`agentic-loop: plan extracted from text (${steps.length} steps, deprecated fallback)`);
     },
     onPlanAlreadySet: ({ steps }) => {
       log.push(`agentic-loop: plan set via tool (${steps.length} steps)`);
@@ -512,11 +514,14 @@ async function runRuntime(argv, agent) {
         };
       }
       emitRuntimeLog(context.session, manual ? 'runtime: manual resume completed' : 'runtime: recovery completed');
+      const controlStarted = pollingActivities.length === 0
+        ? serverHandle?.drainControl?.(context) === true
+        : false;
       return {
         workspace: context.workspace ?? workspace ?? null,
         resumed: true,
         interrupted: 0,
-        mode: pollingActivities.length > 0 ? 'activity_poll' : 'context',
+        mode: controlStarted ? 'control_queue' : pollingActivities.length > 0 ? 'activity_poll' : 'context',
       };
     } catch (err) {
       const interrupted = store.interruptRuns({ workspace });
@@ -629,6 +634,33 @@ async function runRuntime(argv, agent) {
       const context = await getWorkspaceContext(workspace);
       return context.approvalManager?.approve({ runId, itemId, approvalId }) ?? { approved: false };
     },
+    configProfiles: async (context) => {
+      const profiles = listWikircProfiles(context.session.workspacePath);
+      return {
+        profiles: profiles.map((profile) => profile.name),
+        active: context.session.wikirc?.profile ?? null,
+        items: profiles.map((profile) => ({
+          name: profile.name,
+          fileName: profile.fileName,
+          default: Boolean(profile.default),
+        })),
+      };
+    },
+    useConfigProfile: async (context, profile) => {
+      const { summary, config } = applySessionWikircProfile(context.session, profile);
+      await refreshMcpRuntimeStatus(context.session);
+      dispatchAgentEvent(context.session, createAgentEvent('runtime_log', {
+        origin: 'runtime',
+        payload: { message: `runtime: config profile switched to ${context.session.wikirc?.profile ?? profile}` },
+      }));
+      return {
+        ok: true,
+        active: context.session.wikirc?.profile ?? profile,
+        fileName: context.session.wikirc?.fileName ?? null,
+        summary,
+        config,
+      };
+    },
     token: auth.token,
   });
   const recovery = await recoverRuntime();

package/src/commands/slash.js

@@ -1,7 +1,6 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import { createLlmClientFromWikiConfig } from '../agent/llm.js';
 import { composeServices, listServices, runWikiCli, serviceLogs, serviceStates, startService, stopService } from '../core/compose.js';
 import {
   applyMcpRuntimeStatus,
@@ -26,10 +25,10 @@ import {
 } from '../core/jobQueue.js';
 import {
   listWikircProfiles,
-  loadWikircProfile,
   resolveWikircProfile,
   summarizeWikircConfig,
 } from '../core/wikirc.js';
+import { applySessionWikircProfile } from '../core/sessionConfig.js';
 import { deleteWorkspaceAndFiles, startAgents, stopAgents } from '../core/wikiSetup.js';
 import {
   cleanDocumentUploads,
@@ -546,25 +545,6 @@ function loadWorkspaceSystemPrompt(workspacePath) {
   return existsSync(promptPath) ? readFileSync(promptPath, 'utf8').trim() || null : null;
 }
 
-function loadSessionWikirc(session, profileName = 'default') {
-  if (!session.workspacePath) {
-    throw new Error('No workspace loaded. Use /use <workspace>.');
-  }
-  const loaded = loadWikircProfile(session.workspacePath, profileName);
-  session.wikirc = {
-    profile: loaded.profile.name,
-    fileName: loaded.profile.fileName,
-    path: loaded.profile.path,
-  };
-  session.wikircConfig = loaded.config;
-  session.language = loaded.config?.language ?? null;
-  session.llm = createLlmClientFromWikiConfig(loaded.config);
-  if (session.mcp?.production) {
-    session.mcp.production.activeConfigPath = loaded.profile.fileName;
-  }
-  return summarizeWikircConfig(loaded.profile, loaded.config);
-}
-
 function clearWorkspaceSession(session) {
   session.workspace = null;
   session.workspacePath = null;
@@ -635,8 +615,8 @@ ${helpPair('/workspace list', 'Workspaces', '/new <n> [path]', 'New workspace')}
 ${helpPair('/use <workspace>', 'Use workspace', '/status', 'Session status')}
 ${helpPair('/config list', 'Config profiles', '/config use <n>', 'Use config')}
 ${helpPair('/config edit <n>', 'Edit config', '/workspace delete <n>', 'Delete workspace')}
-${helpPair('/services', 'Services', '/start [service|agents]', 'Start service(s)')}
-${helpPair('/stop [service|agents]', 'Stop service(s)', '/logs <service>', 'Service logs')}
+${helpPair('/services', 'Services', '/start [all|service|agents]', 'Start service(s)')}
+${helpPair('/stop [all|service|agents]', 'Stop service(s)', '/logs <service>', 'Service logs')}
 ${helpPair('/skills', 'List skills', '/skills show <n>', 'Show skill')}
 ${helpPair('/skills run <n>', 'Run skill guide', '/skills edit <n>', 'Edit skill')}
 ${helpPair('/mcp status', 'MCP status', '/mcp endpoints', 'MCP endpoints')}
@@ -720,7 +700,7 @@ export async function handleSlashCommand(line, context) {
       context.session.systemPrompt = loadWorkspaceSystemPrompt(workspace.workspacePath);
       try {
         step(`Workspace: loading ${workspace.name} config…`);
-        const summary = loadSessionWikirc(context.session, 'default');
+        const { summary } = applySessionWikircProfile(context.session, 'default');
         step(`Workspace: discovering ${workspace.name} MCP tools…`);
         await refreshMcpRuntimeStatus(context.session);
         return {
@@ -759,7 +739,7 @@ export async function handleSlashCommand(line, context) {
           return { output: 'Usage: /config use <default|name>' };
         }
         try {
-          const summary = loadSessionWikirc(context.session, profileName);
+          const { summary } = applySessionWikircProfile(context.session, profileName);
           await refreshMcpRuntimeStatus(context.session);
           return {
             output: [
@@ -830,6 +810,10 @@ export async function handleSlashCommand(line, context) {
       }
     }
     case 'start': {
+      // 'all' already resolves correctly through serviceAliases() (DEFAULT_SERVICE_ALIASES.all
+      // = COMPOSE_SERVICES, overridable via docker-compose.yml's service-aliases.all.targets) —
+      // do not remap it to undefined, that bypasses any custom "all" target list and always
+      // falls back to the hardcoded COMPOSE_SERVICES constant instead.
       const service = args[1];
       if (service === 'agents') return runAgentCommand(startAgents, 'start');
       try {

package/src/contracts/README.md

@@ -0,0 +1,16 @@
+# Runtime Contracts
+
+Versioned JSON Schema-like contracts live in `schemas.js`.
+
+Current schema version: `1`.
+
+Validated boundaries:
+
+- `_activity` after normalization in `core/activity.js`
+- `AgentRunEvent` creation and dispatch in `core/agentEvents.js`
+- structured plan and plan patch normalization
+- runtime `/run` and `/control` request payloads
+
+Validation is enabled when `WIKI_MANAGER_VALIDATE_CONTRACTS=1`, `CI=true`, or
+`NODE_ENV` is set to a non-production value. Schemas tolerate additional fields
+so agents can extend payloads without breaking older consumers.