wendkeep 0.80.2 → 0.85.1

package/packages/mcp/src/server.mjs

@@ -0,0 +1,342 @@
+import { MCP_EFFECT_MANIFEST, resolveMcpToolEffect } from './effects.mjs';
+
+const DEFAULT_PAGE_SIZE = 50;
+const MAX_PAGE_SIZE = 100;
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+function boundedInteger(value, fallback, maximum = MAX_PAGE_SIZE) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed < 1) return fallback;
+  return Math.min(parsed, maximum);
+}
+
+function cursorFor(offset) {
+  return Buffer.from(JSON.stringify({ v: 1, offset }), 'utf8').toString('base64url');
+}
+
+function cursorOffset(value) {
+  if (!value) return 0;
+  try {
+    const parsed = JSON.parse(Buffer.from(String(value), 'base64url').toString('utf8'));
+    return parsed?.v === 1 && Number.isInteger(parsed.offset) && parsed.offset >= 0
+      ? parsed.offset
+      : 0;
+  } catch { return 0; }
+}
+
+function supportsObserverSql(nodeVersion) {
+  const [major = 0, minor = 0] = String(nodeVersion || '').split('.').map(Number);
+  return major > 22 || (major === 22 && minor >= 13);
+}
+
+function availability(tool, nodeVersion) {
+  if (tool.name !== 'wendkeep_observer_query' || supportsObserverSql(nodeVersion)) {
+    return { available: true };
+  }
+  return {
+    available: false,
+    code: 'MCP_RUNTIME_UNSUPPORTED',
+    requires: 'node>=22.13.0',
+  };
+}
+
+const TOOL_REQUIRED_ARGUMENTS = Object.freeze({
+  wendkeep_context_status: ['session_id'],
+  wendkeep_change_show: ['change'],
+  wendkeep_change_status: ['change'],
+  wendkeep_task_show: ['session_id', 'task'],
+  wendkeep_task_evaluate: ['session_id', 'task'],
+  wendkeep_handoff_current: ['session_id'],
+  wendkeep_evidence_latest: ['change'],
+  wendkeep_memory_assert: ['payload'],
+  wendkeep_context_select: ['payload'],
+  wendkeep_task_claim: ['task'],
+  wendkeep_task_complete: ['task'],
+  wendkeep_handoff_publish: ['payload'],
+});
+
+function inputSchema(tool) {
+  const required = ['project_root'];
+  required.push(...(TOOL_REQUIRED_ARGUMENTS[tool.name] || []));
+  if (tool.effect === 'write') {
+    required.push('session_id', 'active_context_id', 'actor', 'reason', 'capabilities', 'lease');
+  }
+  return {
+    type: 'object',
+    additionalProperties: false,
+    required,
+    properties: {
+      project_root: { type: 'string', minLength: 1 },
+      worktree_root: { type: 'string', minLength: 1 },
+      session_id: { type: 'string', minLength: 1 },
+      active_context_id: { type: 'string', minLength: 1 },
+      actor: { type: 'string', minLength: 1 },
+      reason: { type: 'string', minLength: 1, maxLength: 500 },
+      capabilities: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+      lease: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['id', 'expires_at'],
+        properties: {
+          id: { type: 'string', minLength: 1 },
+          expires_at: { type: 'string', format: 'date-time' },
+        },
+      },
+      change: { type: 'string' },
+      task: { type: 'string' },
+      query: { type: 'string' },
+      cursor: { type: 'string' },
+      limit: { type: 'integer', minimum: 1, maximum: MAX_PAGE_SIZE },
+      payload: { type: 'object' },
+    },
+  };
+}
+
+function toolDescriptor(tool, nodeVersion) {
+  return {
+    name: tool.name,
+    description: `${tool.capability} (${tool.effect}, effect v${tool.effect_version})`,
+    inputSchema: inputSchema(tool),
+    outputSchema: {
+      type: 'object',
+      required: ['schema_version'],
+      properties: { schema_version: { const: 1 } },
+    },
+    annotations: {
+      readOnlyHint: tool.effect === 'read',
+      destructiveHint: tool.effect === 'destructive',
+      idempotentHint: tool.effect === 'read',
+      openWorldHint: false,
+    },
+    _meta: {
+      'wendkeep/effect': {
+        catalog_version: MCP_EFFECT_MANIFEST.catalog_version,
+        effect: tool.effect,
+        effect_version: tool.effect_version,
+        capability: tool.capability,
+        input_schema: tool.input_schema,
+        output_schema: tool.output_schema,
+        manifest_integrity: MCP_EFFECT_MANIFEST.integrity,
+      },
+      availability: availability(tool, nodeVersion),
+    },
+  };
+}
+
+function sanitizeMessage(value) {
+  return String(value || 'MCP tool failed')
+    .replace(/\bgh[pousr]_[A-Za-z0-9_]{12,}\b/g, '[REDACTED_SECRET]')
+    .replace(/\b[A-Za-z]:\\[^\s)'"\r\n]+/g, '[LOCAL_PATH]')
+    .replace(/\/[Uu]sers\/[^/\s]+\/[^\s)'"\r\n]+/g, '[LOCAL_PATH]')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 500);
+}
+
+function toolError(code, message, { retryable = false } = {}) {
+  const structuredContent = {
+    schema_version: 1,
+    error: { code, message: sanitizeMessage(message), retryable },
+  };
+  return {
+    isError: true,
+    content: [{ type: 'text', text: JSON.stringify(structuredContent) }],
+    structuredContent,
+  };
+}
+
+function toolSuccess(value, {
+  cursor = '', limit = DEFAULT_PAGE_SIZE, maxResponseBytes = 1_048_576,
+} = {}) {
+  let structuredContent = value;
+  if (Array.isArray(value)) {
+    const offset = cursorOffset(cursor);
+    const pageSize = boundedInteger(limit, DEFAULT_PAGE_SIZE);
+    const items = value.slice(offset, offset + pageSize);
+    do {
+      structuredContent = {
+        schema_version: 1,
+        items,
+        ...(offset + items.length < value.length ? { next_cursor: cursorFor(offset + items.length) } : {}),
+      };
+      if (Buffer.byteLength(JSON.stringify(structuredContent), 'utf8') <= maxResponseBytes) break;
+      items.pop();
+    } while (items.length);
+    if (!items.length && offset < value.length) {
+      return toolError('MCP_RESPONSE_TOO_LARGE', 'one result item exceeds the configured byte budget');
+    }
+  } else {
+    structuredContent = value && typeof value === 'object'
+      ? { ...value, schema_version: 1 }
+      : { schema_version: 1, value };
+    if (Buffer.byteLength(JSON.stringify(structuredContent), 'utf8') > maxResponseBytes) {
+      return toolError('MCP_RESPONSE_TOO_LARGE', 'tool result exceeds the configured byte budget');
+    }
+  }
+  return {
+    isError: false,
+    content: [{ type: 'text', text: JSON.stringify(structuredContent) }],
+    structuredContent,
+  };
+}
+
+function validateArguments(tool, args, now = Date.now()) {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) return 'MCP_ARGUMENTS_INVALID';
+  if (!String(args.project_root || '').trim()) return 'MCP_PROJECT_REQUIRED';
+  for (const field of TOOL_REQUIRED_ARGUMENTS[tool.name] || []) {
+    if (!String(args[field] || '').trim()) return 'MCP_ARGUMENT_REQUIRED';
+  }
+  if (tool.effect !== 'write') return '';
+  if (!Array.isArray(args.capabilities) || !args.capabilities.includes(tool.capability)) {
+    return 'MCP_CAPABILITY_REQUIRED';
+  }
+  if (!String(args.session_id || '').trim()
+    || !String(args.active_context_id || '').trim()
+    || !String(args.actor || '').trim()
+    || !String(args.reason || '').trim()
+    || !String(args.lease?.id || '').trim()
+    || !String(args.lease?.expires_at || '').trim()) return 'MCP_WRITE_CONTEXT_REQUIRED';
+  const expiresAt = Date.parse(args.lease.expires_at);
+  if (!Number.isFinite(expiresAt)) return 'MCP_LEASE_INVALID';
+  if (expiresAt <= now) return 'MCP_LEASE_EXPIRED';
+  return '';
+}
+
+function withControl(operation, timeoutMs, controller) {
+  let timer;
+  let onAbort;
+  const { signal } = controller;
+  timer = setTimeout(() => controller.abort(Object.assign(new Error('tool call timed out'), {
+    code: 'MCP_TOOL_TIMEOUT',
+  })), timeoutMs);
+  return Promise.race([
+    operation,
+    new Promise((_, reject) => {
+      onAbort = () => {
+        const reason = signal.reason;
+        reject(typeof reason?.code === 'string' && reason.code.startsWith('MCP_')
+          ? reason
+          : Object.assign(new Error('tool call cancelled'), {
+          code: 'MCP_TOOL_CANCELLED',
+          }));
+      };
+      signal.addEventListener('abort', onAbort, { once: true });
+    }),
+  ]).finally(() => {
+    clearTimeout(timer);
+    signal.removeEventListener('abort', onAbort);
+  });
+}
+
+export function createNativeMcpServer({
+  executeTool = async () => ({}),
+  nodeVersion = process.versions.node,
+  defaultPageSize = DEFAULT_PAGE_SIZE,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  serverVersion = '1',
+  manifest = MCP_EFFECT_MANIFEST,
+  maxRequestBytes = 1_048_576,
+  maxResponseBytes = 1_048_576,
+  now = () => Date.now(),
+  auditToolCall = async () => {},
+} = {}) {
+  const pending = new Map();
+
+  async function callTool(params = {}, requestId = null) {
+    const startedAt = performance.now();
+    const effect = resolveMcpToolEffect(params.name, { manifest });
+    const finish = async (result, tool = null) => {
+      const errorCode = result?.structuredContent?.error?.code || '';
+      try {
+        await auditToolCall({
+          tool: tool?.name || String(params.name || '').slice(0, 120),
+          effect: tool?.effect || effect.effect,
+          capability: tool?.capability || effect.capability,
+          outcome: result?.isError ? 'error' : 'success',
+          error_code: errorCode,
+          duration_ms: Math.max(0, Math.round(performance.now() - startedAt)),
+        }, { projectRoot: String(params.arguments?.project_root || '') });
+      } catch { /* audit failures must not corrupt protocol responses */ }
+      return result;
+    };
+    if (!effect.known) {
+      return finish(toolError('MCP_TOOL_UNKNOWN', 'tool is absent from the verified effect catalog'));
+    }
+    const tool = manifest.tools.find((candidate) => candidate.name === effect.name);
+    const available = availability(tool, nodeVersion);
+    if (!available.available) {
+      return finish(toolError(available.code, `${tool.name} requires ${available.requires}`), tool);
+    }
+    const args = params.arguments || {};
+    if (Buffer.byteLength(JSON.stringify({ name: params.name, arguments: args }), 'utf8') > maxRequestBytes) {
+      return finish(toolError('MCP_REQUEST_TOO_LARGE', 'tool request exceeds the configured byte budget'), tool);
+    }
+    const validationCode = validateArguments(tool, args, now());
+    if (validationCode) return finish(toolError(validationCode, `invalid arguments for ${tool.name}`), tool);
+    const controller = new AbortController();
+    if (requestId !== null && requestId !== undefined) pending.set(requestId, controller);
+    try {
+      const value = await withControl(
+        Promise.resolve(executeTool(tool, args, { signal: controller.signal })),
+        boundedInteger(timeoutMs, DEFAULT_TIMEOUT_MS, 120_000),
+        controller,
+      );
+      return finish(toolSuccess(value, {
+        cursor: args.cursor,
+        limit: boundedInteger(args.limit, defaultPageSize),
+        maxResponseBytes,
+      }), tool);
+    } catch (error) {
+      return finish(toolError(error?.code || 'MCP_TOOL_FAILED', error?.message || error, {
+        retryable: error?.code === 'MCP_TOOL_TIMEOUT',
+      }), tool);
+    } finally {
+      if (requestId !== null && requestId !== undefined) pending.delete(requestId);
+    }
+  }
+
+  return {
+    async handle(message = {}) {
+      const id = message.id;
+      if (message.jsonrpc !== '2.0') {
+        return { jsonrpc: '2.0', id: id ?? null, error: { code: -32600, message: 'Invalid Request' } };
+      }
+      if (message.method === 'initialize') {
+        return {
+          jsonrpc: '2.0', id,
+          result: {
+            protocolVersion: message.params?.protocolVersion || '2025-06-18',
+            capabilities: { tools: { listChanged: false } },
+            serverInfo: { name: 'wendkeep-native', version: serverVersion },
+          },
+        };
+      }
+      if (message.method === 'notifications/initialized') {
+        return null;
+      }
+      if (message.method === 'notifications/cancelled') {
+        pending.get(message.params?.requestId)?.abort();
+        return null;
+      }
+      if (message.method === 'tools/list') {
+        const offset = cursorOffset(message.params?.cursor);
+        const pageSize = boundedInteger(message.params?.limit, defaultPageSize);
+        const descriptors = manifest.tools.map((tool) => toolDescriptor(tool, nodeVersion));
+        const tools = descriptors.slice(offset, offset + pageSize);
+        return {
+          jsonrpc: '2.0', id,
+          result: {
+            tools,
+            ...(offset + tools.length < descriptors.length ? { nextCursor: cursorFor(offset + tools.length) } : {}),
+          },
+        };
+      }
+      if (message.method === 'tools/call') {
+        return { jsonrpc: '2.0', id, result: await callTool(message.params, id) };
+      }
+      return { jsonrpc: '2.0', id: id ?? null, error: { code: -32601, message: 'Method not found' } };
+    },
+  };
+}
+
+export { supportsObserverSql };

package/packages/mcp/src/stdio.mjs

@@ -0,0 +1,38 @@
+import { createInterface } from 'node:readline';
+
+export async function runNativeMcpStdio({
+  input = process.stdin,
+  output = process.stdout,
+  server,
+} = {}) {
+  if (!server || typeof server.handle !== 'function') {
+    throw new TypeError('runNativeMcpStdio requires a server');
+  }
+  const pending = new Set();
+  const lines = createInterface({ input, crlfDelay: Infinity, terminal: false });
+  for await (const line of lines) {
+    if (!line.trim()) continue;
+    let message;
+    try { message = JSON.parse(line); }
+    catch {
+      output.write(`${JSON.stringify({
+        jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' },
+      })}\n`);
+      continue;
+    }
+    const operation = Promise.resolve(server.handle(message))
+      .then((response) => {
+        if (response) output.write(`${JSON.stringify(response)}\n`);
+      })
+      .catch(() => {
+        if (message.id !== undefined) {
+          output.write(`${JSON.stringify({
+            jsonrpc: '2.0', id: message.id, error: { code: -32603, message: 'Internal error' },
+          })}\n`);
+        }
+      })
+      .finally(() => pending.delete(operation));
+    pending.add(operation);
+  }
+  await Promise.all(pending);
+}

package/packages/mcp/src/sync.mjs

@@ -0,0 +1,56 @@
+export const SYNC_MCP_TOOL_DEFINITIONS = [
+  {
+    name: 'wendkeep_sync_status',
+    description: 'Read local-first sync health, pending count, and explicit conflict count.',
+    effect: 'read',
+  },
+  {
+    name: 'wendkeep_sync_conflicts',
+    description: 'List explicit sync conflict candidates without returning authored payloads.',
+    effect: 'read',
+  },
+];
+
+function publicCandidate(candidate) {
+  return {
+    event_id: String(candidate?.event_id || ''),
+    revision: Number(candidate?.revision || 0),
+    content_hash: String(candidate?.content_hash || ''),
+    actor_id: String(candidate?.actor_id || ''),
+    device_id: String(candidate?.device_id || ''),
+    observed_at: String(candidate?.observed_at || ''),
+    operation: String(candidate?.operation || ''),
+    privacy: String(candidate?.privacy || ''),
+  };
+}
+
+export function inspectSyncForMcp({ outbox, state = null } = {}) {
+  const safeOutbox = outbox && typeof outbox === 'object'
+    ? {
+        status: String(outbox.status || 'corrupt'),
+        events: Number(outbox.events || 0),
+        pending: Number(outbox.pending || 0),
+        acknowledged: Number(outbox.acknowledged || 0),
+        ...(outbox.code ? { code: String(outbox.code) } : {}),
+      }
+    : { status: 'corrupt', events: 0, pending: 0, acknowledged: 0, code: 'WENDKEEP_SYNC_STATE_UNAVAILABLE' };
+  if (safeOutbox.status === 'disabled') return { enabled: false, outbox: safeOutbox, conflicts: 0 };
+  if (!state || typeof state !== 'object') return {
+    enabled: true,
+    outbox: { ...safeOutbox, status: 'corrupt', code: 'WENDKEEP_SYNC_STATE_UNAVAILABLE' },
+    conflicts: 0,
+  };
+  const conflicts = Object.values(state.conflicts || {}).filter((item) => item?.status === 'open').length;
+  return { enabled: true, outbox: safeOutbox, conflicts };
+}
+
+export function listSyncConflictsForMcp({ state } = {}) {
+  return Object.entries(state?.conflicts || {})
+    .filter(([, item]) => item?.status === 'open')
+    .map(([recordKey, item]) => ({
+      record_key: recordKey,
+      status: 'open',
+      candidates: (item.candidates || []).map(publicCandidate),
+    }))
+    .sort((left, right) => left.record_key.localeCompare(right.record_key));
+}

package/packages/pi/package.json

@@ -1,5 +1,6 @@
 {
   "name": "@wendkeep/pi",
   "private": true,
-  "type": "module"
+  "type": "module",
+  "exports": "./src/index.mjs"
 }

package/packages/pi/src/index.mjs

@@ -0,0 +1,29 @@
+const EVENT_CAPABILITIES = {
+  session_start: 'session.start',
+  session_resume: 'session.resume',
+  session_stop: 'session.stop',
+  prompt_submit: 'prompt.submit',
+  tool_pre: 'tool.pre',
+};
+
+export function piAdapterDescriptor() {
+  return {
+    schema_version: 1,
+    host_id: 'pi',
+    adapter_version: 1,
+    transport: 'extension',
+    envelope_version: 1,
+  };
+}
+
+export function normalizePiLifecycleEvent(input = {}) {
+  const capability = EVENT_CAPABILITIES[String(input.type || '')];
+  if (!capability) return { ok: false, code: 'PI_ENVELOPE_UNKNOWN' };
+  return {
+    schema_version: 1,
+    host_id: 'pi',
+    capability,
+    session_id: String(input.sessionId || input.session_id || ''),
+    authority: 'adapted',
+  };
+}

package/schema/handoff-contract-v1.schema.json

@@ -22,9 +22,13 @@
     "decisions": { "$ref": "#/$defs/stringArray" },
     "next_actions": { "$ref": "#/$defs/stringArray" },
     "blockers": { "$ref": "#/$defs/stringArray" },
+    "tdd_attestation_ids": { "$ref": "#/$defs/stringArray" },
     "head_sha": { "type": "string", "minLength": 1 },
     "tasks_sha256": { "type": "string", "minLength": 1 },
     "spec_sha256": { "type": "string", "minLength": 1 },
+    "host_coverage": { "$ref": "host-coverage-v1.schema.json" },
+    "coverage_findings": { "type": "array", "items": { "type": "object" } },
+    "coverage_waivers": { "type": "array", "items": { "type": "object" } },
     "authority": { "enum": ["verified", "reported"] }
   },
   "$defs": {

package/schema/host-capability-manifest-v1.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wendkeep.dev/schema/host-capability-manifest-v1.schema.json",
+  "title": "WendKeep host capability manifest v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "manifest_version", "host_id", "label", "supported_major_versions", "envelope_versions", "capabilities"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "manifest_version": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
+    "host_id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "label": { "type": "string", "minLength": 1, "maxLength": 80 },
+    "supported_major_versions": { "type": "array", "minItems": 1, "items": { "type": ["integer", "string"] } },
+    "envelope_versions": { "type": "array", "minItems": 1, "items": { "type": "integer", "minimum": 1 } },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["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"],
+      "properties": {
+        "session.start": { "$ref": "#/$defs/state" },
+        "session.resume": { "$ref": "#/$defs/state" },
+        "session.stop": { "$ref": "#/$defs/state" },
+        "prompt.submit": { "$ref": "#/$defs/state" },
+        "tool.pre": { "$ref": "#/$defs/state" },
+        "tool.post": { "$ref": "#/$defs/state" },
+        "tool.effect.read": { "$ref": "#/$defs/state" },
+        "tool.effect.write": { "$ref": "#/$defs/state" },
+        "tool.effect.destructive": { "$ref": "#/$defs/state" },
+        "edit.attribution": { "$ref": "#/$defs/state" },
+        "plan.approved": { "$ref": "#/$defs/state" },
+        "decision.capture": { "$ref": "#/$defs/state" },
+        "task.completed": { "$ref": "#/$defs/state" },
+        "subagent.start": { "$ref": "#/$defs/state" },
+        "subagent.stop": { "$ref": "#/$defs/state" },
+        "transcript.read": { "$ref": "#/$defs/state" },
+        "usage.read": { "$ref": "#/$defs/state" }
+      }
+    }
+  },
+  "$defs": {
+    "state": { "enum": ["native", "adapted", "polled", "manual", "unavailable"] },
+    "capabilityName": {
+      "enum": ["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"]
+    }
+  }
+}

package/schema/host-coverage-v1.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wendkeep.dev/schema/host-coverage-v1.schema.json",
+  "title": "WendKeep host coverage v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "manifest_version", "host_id", "requested_host_id", "host_version", "version_supported", "observed_at", "degraded", "capabilities", "degradations", "tool_effects"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "manifest_version": { "type": "string" },
+    "host_id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "requested_host_id": { "type": "string", "minLength": 1, "maxLength": 80 },
+    "host_version": { "type": "string", "maxLength": 80 },
+    "version_supported": { "type": "boolean" },
+    "observed_at": { "type": "string", "format": "date-time" },
+    "degraded": { "type": "boolean" },
+    "capabilities": { "type": "array", "minItems": 17, "maxItems": 17, "items": { "$ref": "#/$defs/capability" } },
+    "degradations": { "type": "array", "items": { "$ref": "#/$defs/degradation" } },
+    "tool_effects": { "$ref": "#/$defs/toolEffects" }
+  },
+  "$defs": {
+    "state": { "enum": ["native", "adapted", "polled", "manual", "unavailable"] },
+    "capability": {
+      "type": "object", "additionalProperties": false,
+      "required": ["capability", "state", "authority"],
+      "properties": {
+        "capability": { "type": "string" },
+        "state": { "$ref": "#/$defs/state" },
+        "authority": { "enum": ["verified", "reported", "unavailable"] }
+      }
+    },
+    "degradation": {
+      "type": "object", "additionalProperties": false,
+      "required": ["capability", "state", "code", "blocking"],
+      "properties": {
+        "capability": { "type": "string" },
+        "state": { "$ref": "#/$defs/state" },
+        "code": { "type": "string", "pattern": "^HOST_[A-Z0-9_]+$" },
+        "blocking": { "type": "boolean" }
+      }
+    },
+    "toolEffects": {
+      "type": "object", "additionalProperties": false,
+      "required": ["manifest_valid", "catalog_version", "read", "write", "destructive", "unknown"],
+      "properties": {
+        "manifest_valid": { "type": "boolean" },
+        "catalog_version": { "type": "string" },
+        "read": { "type": "boolean" },
+        "write": { "type": "boolean" },
+        "destructive": { "type": "boolean" },
+        "unknown": { "const": "fail-closed" }
+      }
+    }
+  }
+}

package/schema/mcp-effect-manifest-v1.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "wendkeep://schema/mcp-effect-manifest-v1",
+  "title": "WendKeep MCP effect manifest v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "catalog_version", "server_aliases", "tools", "integrity"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "catalog_version": { "type": "string", "format": "date" },
+    "server_aliases": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }
+    },
+    "tools": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "effect", "capability", "effect_version", "input_schema", "output_schema"],
+        "properties": {
+          "name": { "type": "string", "pattern": "^wendkeep_[a-z0-9_]+$" },
+          "effect": { "enum": ["read", "write", "destructive"] },
+          "capability": { "type": "string", "pattern": "^[a-z]+:[a-z]+$" },
+          "effect_version": { "const": 1 },
+          "input_schema": { "const": "wendkeep://schema/mcp-tool-input-v1" },
+          "output_schema": { "const": "wendkeep://schema/mcp-tool-result-v1" }
+        }
+      }
+    },
+    "integrity": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
+  }
+}

package/schema/mcp-tool-input-v1.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "wendkeep://schema/mcp-tool-input-v1",
+  "title": "WendKeep MCP tool input v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["project_root"],
+  "properties": {
+    "project_root": { "type": "string", "minLength": 1 },
+    "worktree_root": { "type": "string", "minLength": 1 },
+    "session_id": { "type": "string", "minLength": 1 },
+    "active_context_id": { "type": "string", "minLength": 1 },
+    "actor": { "type": "string", "minLength": 1 },
+    "reason": { "type": "string", "minLength": 1, "maxLength": 500 },
+    "capabilities": { "type": "array", "uniqueItems": true, "items": { "type": "string" } },
+    "lease": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "expires_at"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "expires_at": { "type": "string", "format": "date-time" }
+      }
+    },
+    "change": { "type": "string" },
+    "task": { "type": "string" },
+    "query": { "type": "string" },
+    "cursor": { "type": "string" },
+    "limit": { "type": "integer", "minimum": 1, "maximum": 100 },
+    "payload": { "type": "object" }
+  }
+}