wendkeep 0.80.2 → 0.85.1

package/packages/integrations/src/capabilities.mjs

@@ -0,0 +1,220 @@
+export const HOST_CAPABILITIES = [
+  'session.start', 'session.resume', 'session.stop', 'prompt.submit',
+  'tool.pre', 'tool.post', 'tool.effect.read', 'tool.effect.write',
+  'tool.effect.destructive', 'edit.attribution', 'plan.approved', 'decision.capture',
+  'task.completed', 'subagent.start', 'subagent.stop', 'transcript.read', 'usage.read',
+];
+
+export const HOST_CAPABILITY_STATES = ['native', 'adapted', 'polled', 'manual', 'unavailable'];
+
+function matrix(defaultState, overrides = {}) {
+  return Object.fromEntries(HOST_CAPABILITIES.map((capability) => [
+    capability, overrides[capability] || defaultState,
+  ]));
+}
+
+const effectOverrides = {
+  'tool.effect.read': 'adapted',
+  'tool.effect.write': 'adapted',
+  'tool.effect.destructive': 'adapted',
+};
+
+export const HOST_CAPABILITY_MANIFESTS = {
+  claude: {
+    schema_version: 1,
+    manifest_version: '2026-08-25',
+    host_id: 'claude',
+    label: 'Claude Code',
+    supported_major_versions: [1, 2],
+    envelope_versions: [1],
+    capabilities: matrix('native', {
+      ...effectOverrides,
+      'transcript.read': 'polled',
+      'usage.read': 'polled',
+    }),
+  },
+  codex: {
+    schema_version: 1,
+    manifest_version: '2026-08-25',
+    host_id: 'codex',
+    label: 'Codex',
+    supported_major_versions: [0, 1],
+    envelope_versions: [1],
+    capabilities: matrix('unavailable', {
+      ...effectOverrides,
+      'session.start': 'native',
+      'session.resume': 'adapted',
+      'session.stop': 'native',
+      'prompt.submit': 'native',
+      'tool.pre': 'native',
+      'edit.attribution': 'adapted',
+      'decision.capture': 'manual',
+      'subagent.start': 'native',
+      'subagent.stop': 'native',
+      'transcript.read': 'polled',
+      'usage.read': 'polled',
+    }),
+  },
+  pi: {
+    schema_version: 1,
+    manifest_version: '2026-08-25',
+    host_id: 'pi',
+    label: 'Pi',
+    supported_major_versions: [0, 1],
+    envelope_versions: [1],
+    capabilities: matrix('unavailable', {
+      ...effectOverrides,
+      'session.start': 'adapted',
+      'session.resume': 'adapted',
+      'session.stop': 'adapted',
+      'prompt.submit': 'adapted',
+      'tool.pre': 'adapted',
+      'decision.capture': 'manual',
+      'task.completed': 'manual',
+      'transcript.read': 'polled',
+      'usage.read': 'polled',
+    }),
+  },
+  'generic-mcp': {
+    schema_version: 1,
+    manifest_version: '2026-08-25',
+    host_id: 'generic-mcp',
+    label: 'Generic MCP/CLI',
+    supported_major_versions: ['*'],
+    envelope_versions: [1],
+    capabilities: matrix('unavailable', {
+      ...effectOverrides,
+      'session.start': 'manual',
+      'session.resume': 'manual',
+      'session.stop': 'manual',
+      'prompt.submit': 'manual',
+      'decision.capture': 'manual',
+      'task.completed': 'manual',
+    }),
+  },
+};
+
+const EVENT_CAPABILITIES = {
+  SessionStart: 'session.start',
+  SessionResume: 'session.resume',
+  Stop: 'session.stop',
+  UserPromptSubmit: 'prompt.submit',
+  PreToolUse: 'tool.pre',
+  PostToolUse: 'tool.post',
+  PlanApproved: 'plan.approved',
+  TaskCompleted: 'task.completed',
+  SubagentStart: 'subagent.start',
+  SubagentStop: 'subagent.stop',
+};
+
+function authorityFor(state) {
+  if (['native', 'adapted', 'polled'].includes(state)) return 'verified';
+  if (state === 'manual') return 'reported';
+  return 'unavailable';
+}
+
+export function verifyHostCapabilityManifest(manifest) {
+  const errors = [];
+  if (manifest?.schema_version !== 1) errors.push('schema_version');
+  if (!/^[a-z][a-z0-9-]*$/.test(String(manifest?.host_id || ''))) errors.push('host_id');
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(String(manifest?.manifest_version || ''))) errors.push('manifest_version');
+  const keys = Object.keys(manifest?.capabilities || {}).sort();
+  if (JSON.stringify(keys) !== JSON.stringify([...HOST_CAPABILITIES].sort())) errors.push('capabilities');
+  for (const state of Object.values(manifest?.capabilities || {})) {
+    if (!HOST_CAPABILITY_STATES.includes(state)) errors.push('capability_state');
+  }
+  if (!Array.isArray(manifest?.supported_major_versions) || !manifest.supported_major_versions.length) errors.push('supported_versions');
+  if (!Array.isArray(manifest?.envelope_versions) || !manifest.envelope_versions.length) errors.push('envelope_versions');
+  return { valid: errors.length === 0, errors: [...new Set(errors)] };
+}
+
+function versionSupported(manifest, version) {
+  if (manifest.supported_major_versions.includes('*') || !version) return true;
+  const match = String(version).match(/^(\d+)(?:\.|$)/);
+  return Boolean(match && manifest.supported_major_versions.includes(Number(match[1])));
+}
+
+export function buildCoverageFromManifest({
+  hostId,
+  hostVersion = '',
+  observedAt = new Date().toISOString(),
+  toolEffects = null,
+} = {}) {
+  const requested = String(hostId || '').trim().toLowerCase();
+  const known = Object.hasOwn(HOST_CAPABILITY_MANIFESTS, requested);
+  const manifest = HOST_CAPABILITY_MANIFESTS[known ? requested : 'generic-mcp'];
+  const supported = versionSupported(manifest, hostVersion);
+  const capabilities = HOST_CAPABILITIES.map((capability) => {
+    let state = manifest.capabilities[capability];
+    if (capability.startsWith('tool.effect.')) {
+      const effect = capability.slice('tool.effect.'.length);
+      if (toolEffects?.manifest_valid !== true || toolEffects?.[effect] !== true) state = 'unavailable';
+    }
+    return { capability, state, authority: authorityFor(state) };
+  });
+  const degradations = capabilities
+    .filter((item) => ['manual', 'unavailable'].includes(item.state))
+    .map((item) => ({
+      capability: item.capability,
+      state: item.state,
+      code: item.state === 'manual' ? 'HOST_CAPABILITY_MANUAL' : 'HOST_CAPABILITY_UNAVAILABLE',
+      blocking: item.state === 'unavailable',
+    }));
+  if (!known) degradations.unshift({ capability: '', state: 'manual', code: 'HOST_UNKNOWN', blocking: false });
+  if (!supported) degradations.unshift({ capability: '', state: 'unavailable', code: 'HOST_VERSION_UNPROVEN', blocking: true });
+  return {
+    schema_version: 1,
+    manifest_version: manifest.manifest_version,
+    host_id: manifest.host_id,
+    requested_host_id: requested || manifest.host_id,
+    host_version: String(hostVersion || ''),
+    version_supported: supported,
+    observed_at: new Date(observedAt).toISOString(),
+    degraded: degradations.length > 0,
+    capabilities,
+    degradations,
+    tool_effects: toolEffects || {
+      manifest_valid: false, catalog_version: '', read: false, write: false,
+      destructive: false, unknown: 'fail-closed',
+    },
+  };
+}
+
+function validWaiver(value, capability) {
+  return value?.capability === capability
+    && value?.authority === 'human'
+    && String(value?.approved_by || '').trim()
+    && String(value?.reason || '').trim();
+}
+
+export function evaluateHostCoverage(coverage, required = [], { waivers = [] } = {}) {
+  const rows = new Map((coverage?.capabilities || []).map((item) => [item.capability, item]));
+  const findings = [];
+  const waived = [];
+  for (const capability of [...new Set(required)]) {
+    const row = rows.get(capability);
+    if (row && row.authority === 'verified') continue;
+    const waiver = waivers.find((item) => validWaiver(item, capability));
+    if (waiver) {
+      waived.push({ capability, approved_by: String(waiver.approved_by), reason: String(waiver.reason) });
+      continue;
+    }
+    findings.push({
+      capability,
+      state: row?.state || 'unavailable',
+      code: row?.state === 'manual' ? 'HOST_CAPABILITY_MANUAL' : 'HOST_CAPABILITY_UNAVAILABLE',
+    });
+  }
+  return { ok: findings.length === 0, findings, waived };
+}
+
+export function normalizeHostEnvelope({ hostId, event, envelopeVersion } = {}) {
+  const manifest = HOST_CAPABILITY_MANIFESTS[String(hostId || '').toLowerCase()];
+  if (!manifest || !manifest.envelope_versions.includes(Number(envelopeVersion))) {
+    return { ok: false, code: 'HOST_ENVELOPE_UNKNOWN' };
+  }
+  const capability = EVENT_CAPABILITIES[String(event || '')];
+  if (!capability) return { ok: false, code: 'HOST_ENVELOPE_UNKNOWN' };
+  const state = manifest.capabilities[capability];
+  return { ok: true, capability, state, authority: authorityFor(state) };
+}

package/packages/integrations/src/index.mjs

@@ -1,4 +1,5 @@
 export * from './host-hooks.mjs';
+export * from './capabilities.mjs';
 export * from './hook-envelope.mjs';
 export * from './prompt-content.mjs';
 export * from './transcript-usage.mjs';

package/packages/mcp/src/audit.mjs

@@ -0,0 +1,49 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  assertVaultPathSafe,
+  mkdirVaultPath,
+  VAULT_LOCK_BUSY,
+  withVaultPathLock,
+  writeVaultFileAtomic,
+} from '../../vault/src/vault-path-safety.mjs';
+
+const OUTCOMES = new Set(['success', 'error']);
+const EFFECTS = new Set(['read', 'write', 'destructive', 'unknown']);
+
+function safeText(value, maximum = 160) {
+  return String(value || '').replace(/[\r\n\t]/g, ' ').slice(0, maximum);
+}
+
+export function createMcpAuditor(vaultBase, { now = () => new Date() } = {}) {
+  const runtime = join(vaultBase, '.brain', 'runtime');
+  const path = join(runtime, 'MCP_AUDIT.jsonl');
+  return async function auditToolCall(event = {}) {
+    mkdirVaultPath(vaultBase, runtime, { label: 'runtime da auditoria MCP' });
+    const record = {
+      schema_version: 1,
+      observed_at: now().toISOString(),
+      tool: safeText(event.tool, 120),
+      effect: EFFECTS.has(event.effect) ? event.effect : 'unknown',
+      capability: safeText(event.capability, 120),
+      outcome: OUTCOMES.has(event.outcome) ? event.outcome : 'error',
+      error_code: safeText(event.error_code, 120),
+      duration_ms: Math.max(0, Math.min(Number(event.duration_ms) || 0, 86_400_000)),
+    };
+    const outcome = withVaultPathLock(vaultBase, path, () => {
+      const checked = assertVaultPathSafe(vaultBase, path, {
+        expectedType: 'file', label: 'ledger de auditoria MCP',
+      });
+      const previous = checked.exists ? readFileSync(checked.target, 'utf8') : '';
+      writeVaultFileAtomic(vaultBase, path, `${previous}${JSON.stringify(record)}\n`, 'utf8', {
+        label: 'ledger de auditoria MCP',
+      });
+      return record;
+    }, { code: 'MCP_AUDIT_LOCK_BUSY' });
+    if (outcome === VAULT_LOCK_BUSY) {
+      throw Object.assign(new Error('MCP audit ledger is busy'), { code: 'MCP_AUDIT_LOCK_BUSY' });
+    }
+    return outcome;
+  };
+}

package/packages/mcp/src/cli.mjs

@@ -0,0 +1,78 @@
+import { isAbsolute, resolve } from 'node:path';
+
+import { resolveProjectVault } from '../../vault/src/project-vault.mjs';
+import { createMcpAuditor } from './audit.mjs';
+import { renderMcpClientConfig } from './config.mjs';
+import { createNativeMcpServer } from './server.mjs';
+import { executeNativeMcpTool } from './executor.mjs';
+import { runNativeMcpStdio } from './stdio.mjs';
+
+function optionValue(argv, name) {
+  const index = argv.indexOf(name);
+  if (index >= 0) return argv[index + 1] || '';
+  return argv.find((item) => item.startsWith(`${name}=`))?.slice(name.length + 1) || '';
+}
+
+export const MCP_HELP = `wendkeep mcp <serve|config> [options]
+
+Run the native WendKeep semantic MCP server over stdio.
+
+Options:
+  --vault <path>       Select the bound Vault for compatibility with project MCP config.
+  --timeout-ms <n>     Per-tool execution timeout (default: 10000; maximum: 120000).
+  --client <name>      Config output: generic, claude, codex, or cursor.
+  --help, -h           Show this help.
+`;
+
+export async function runMcp(argv = []) {
+  const [subcommand] = argv;
+  if (argv.includes('--help') || argv.includes('-h')) {
+    process.stdout.write(MCP_HELP);
+    return 0;
+  }
+  if (subcommand === 'config') {
+    const vault = optionValue(argv, '--vault');
+    if (!vault) {
+      process.stderr.write('wendkeep mcp config: --vault is required\n');
+      return 2;
+    }
+    try {
+      process.stdout.write(renderMcpClientConfig(optionValue(argv, '--client') || 'generic', vault));
+      return 0;
+    } catch (error) {
+      process.stderr.write(`wendkeep mcp config: ${error.message}\n`);
+      return 2;
+    }
+  }
+  if (subcommand !== 'serve') {
+    process.stderr.write(`wendkeep mcp: expected "serve"\n${MCP_HELP}`);
+    return 2;
+  }
+  const timeoutValue = optionValue(argv, '--timeout-ms');
+  const timeoutMs = timeoutValue ? Number.parseInt(timeoutValue, 10) : undefined;
+  if (timeoutValue && (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120_000)) {
+    process.stderr.write('wendkeep mcp: --timeout-ms must be an integer from 1 to 120000\n');
+    return 2;
+  }
+  const explicitVault = optionValue(argv, '--vault');
+  const vaultBase = explicitVault
+    ? (isAbsolute(explicitVault) ? resolve(explicitVault) : resolve(process.cwd(), explicitVault))
+    : '';
+  const auditors = new Map();
+  const auditToolCall = async (event, { projectRoot = '' } = {}) => {
+    let selectedVault = vaultBase;
+    if (!selectedVault && projectRoot) {
+      selectedVault = resolveProjectVault({ startDir: projectRoot }).base;
+    }
+    if (!selectedVault) return;
+    if (!auditors.has(selectedVault)) auditors.set(selectedVault, createMcpAuditor(selectedVault));
+    await auditors.get(selectedVault)(event);
+  };
+  const server = createNativeMcpServer({
+    executeTool: executeNativeMcpTool,
+    auditToolCall,
+    ...(timeoutMs ? { timeoutMs } : {}),
+  });
+  await runNativeMcpStdio({ server });
+  return 0;
+}

package/packages/mcp/src/config.mjs

@@ -4,10 +4,31 @@ export function mcpServerEntry(vaultPath) {
   return {
     type: 'stdio',
     command: 'npx',
-    args: ['-y', '@bitbonsai/mcpvault@latest', vaultPath],
+    args: ['--no-install', 'wendkeep', 'mcp', 'serve', '--vault', vaultPath],
   };
 }
 
+function tomlString(value) {
+  return JSON.stringify(String(value));
+}
+
+export function renderMcpClientConfig(client, vaultPath) {
+  const selected = String(client || 'generic').toLowerCase();
+  const entry = mcpServerEntry(vaultPath);
+  if (selected === 'codex') {
+    return [
+      `[mcp_servers.${MCP_SERVER_KEY}]`,
+      `command = ${tomlString(entry.command)}`,
+      `args = [${entry.args.map(tomlString).join(', ')}]`,
+      '',
+    ].join('\n');
+  }
+  if (!['generic', 'claude', 'cursor'].includes(selected)) {
+    throw Object.assign(new Error(`unsupported MCP client: ${client}`), { code: 'MCP_CLIENT_INVALID' });
+  }
+  return `${JSON.stringify({ mcpServers: { [MCP_SERVER_KEY]: entry } }, null, 2)}\n`;
+}
+
 export function selectMcpServers(descriptors, skipIds = []) {
   const skipSet = new Set(skipIds);
   const servers = {};

package/packages/mcp/src/effects.mjs

@@ -0,0 +1,115 @@
+import { createHash } from 'node:crypto';
+
+const EFFECTS = new Set(['read', 'write', 'destructive']);
+
+const TOOLS = [
+  ['wendkeep_project_status', 'read', 'project:status'],
+  ['wendkeep_context_status', 'read', 'context:status'],
+  ['wendkeep_memory_recall', 'read', 'memory:recall'],
+  ['wendkeep_memory_conflicts', 'read', 'memory:conflicts'],
+  ['wendkeep_change_list', 'read', 'change:list'],
+  ['wendkeep_change_show', 'read', 'change:show'],
+  ['wendkeep_change_status', 'read', 'change:status'],
+  ['wendkeep_spec_effective', 'read', 'spec:effective'],
+  ['wendkeep_task_show', 'read', 'task:show'],
+  ['wendkeep_task_evaluate', 'read', 'task:evaluate'],
+  ['wendkeep_handoff_current', 'read', 'handoff:current'],
+  ['wendkeep_evidence_latest', 'read', 'evidence:latest'],
+  ['wendkeep_observer_query', 'read', 'observer:query'],
+  ['wendkeep_memory_assert', 'write', 'memory:assert'],
+  ['wendkeep_checkpoint_create', 'write', 'checkpoint:create'],
+  ['wendkeep_context_select', 'write', 'context:select'],
+  ['wendkeep_task_claim', 'write', 'task:claim'],
+  ['wendkeep_task_complete', 'write', 'task:complete'],
+  ['wendkeep_handoff_publish', 'write', 'handoff:publish'],
+].map(([name, effect, capability]) => ({
+  name,
+  effect,
+  capability,
+  effect_version: 1,
+  input_schema: 'wendkeep://schema/mcp-tool-input-v1',
+  output_schema: 'wendkeep://schema/mcp-tool-result-v1',
+}));
+
+function manifestPayload(manifest) {
+  return {
+    schema_version: manifest?.schema_version,
+    catalog_version: manifest?.catalog_version,
+    server_aliases: manifest?.server_aliases,
+    tools: manifest?.tools,
+  };
+}
+
+function manifestIntegrity(manifest) {
+  return `sha256:${createHash('sha256')
+    .update(JSON.stringify(manifestPayload(manifest)), 'utf8')
+    .digest('hex')}`;
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const child of Object.values(value)) deepFreeze(child);
+  return value;
+}
+
+export const MCP_EFFECT_MANIFEST = deepFreeze({
+  schema_version: 1,
+  catalog_version: '2026-08-24',
+  server_aliases: ['wendkeep', 'wendkeep-native'],
+  tools: TOOLS,
+  integrity: 'sha256:de96c2f3f5ae3d814440b541db778f87be4550ebd2ce9dd5ae2377f354770046',
+});
+
+export function verifyMcpEffectManifest(manifest) {
+  const names = new Set();
+  const aliases = new Set();
+  const errors = [];
+  if (manifest?.schema_version !== 1) errors.push('schema_version');
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(String(manifest?.catalog_version || ''))) errors.push('catalog_version');
+  if (!Array.isArray(manifest?.server_aliases) || !manifest.server_aliases.length) errors.push('server_aliases');
+  for (const alias of manifest?.server_aliases || []) {
+    if (!/^[a-z][a-z0-9-]*$/.test(alias) || aliases.has(alias)) errors.push('server_alias');
+    aliases.add(alias);
+  }
+  if (!Array.isArray(manifest?.tools) || !manifest.tools.length) errors.push('tools');
+  for (const tool of manifest?.tools || []) {
+    if (!/^wendkeep_[a-z0-9_]+$/.test(String(tool?.name || '')) || names.has(tool.name)) errors.push('tool_name');
+    names.add(tool?.name);
+    if (!EFFECTS.has(tool?.effect)) errors.push('tool_effect');
+    if (!/^[a-z]+:[a-z]+$/.test(String(tool?.capability || ''))) errors.push('tool_capability');
+    if (tool?.effect_version !== 1) errors.push('effect_version');
+    if (tool?.input_schema !== 'wendkeep://schema/mcp-tool-input-v1') errors.push('input_schema');
+    if (tool?.output_schema !== 'wendkeep://schema/mcp-tool-result-v1') errors.push('output_schema');
+  }
+  const expected = manifestIntegrity(manifest);
+  if (manifest?.integrity !== expected) errors.push('integrity');
+  return { valid: errors.length === 0, errors: [...new Set(errors)], expected_integrity: expected };
+}
+
+function semanticToolName(toolName, manifest) {
+  const name = String(toolName || '');
+  if (name.startsWith('wendkeep_')) return name;
+  for (const alias of manifest.server_aliases || []) {
+    const prefix = `mcp__${alias}__`;
+    if (name.startsWith(prefix)) return name.slice(prefix.length);
+  }
+  return '';
+}
+
+export function resolveMcpToolEffect(toolName, { manifest = MCP_EFFECT_MANIFEST } = {}) {
+  if (!verifyMcpEffectManifest(manifest).valid) {
+    return { known: false, name: '', effect: 'unknown', capability: '', effect_version: 0 };
+  }
+  const name = semanticToolName(toolName, manifest);
+  const tool = manifest.tools.find((candidate) => candidate.name === name);
+  return tool
+    ? {
+      known: true,
+      name: tool.name,
+      effect: tool.effect,
+      capability: tool.capability,
+      effect_version: tool.effect_version,
+    }
+    : { known: false, name, effect: 'unknown', capability: '', effect_version: 0 };
+}