@kaddo/mcp 3.81.0 → 3.83.0

package/dist/index.js

@@ -262,8 +262,8 @@ function sectionParagraph(md, title) {
   return "";
 }
 function listCapsules(root) {
-  const registry = readYaml(root, ".kaddo/external.yml");
-  const entries = Array.isArray(registry?.external) ? registry.external : [];
+  const registry2 = readYaml(root, ".kaddo/external.yml");
+  const entries = Array.isArray(registry2?.external) ? registry2.external : [];
   return entries.map((e) => {
     const md = e.path ? readText(root, e.path) : null;
     let system;
@@ -480,8 +480,8 @@ function loadConfig(dir) {
   const parsed = configSchema.safeParse(raw ?? {});
   if (!parsed.success) {
     const issues = parsed.error.issues.map((i) => {
-      const path5 = i.path.join(".");
-      return path5 ? `  - ${path5}: ${i.message}` : `  - ${i.message}`;
+      const path6 = i.path.join(".");
+      return path6 ? `  - ${path6}: ${i.message}` : `  - ${i.message}`;
     }).join("\n");
     throw new ConfigError(`Invalid .kaddo/config.yml:
 ${issues}`);
@@ -922,11 +922,11 @@ function moduleArtifactCoverage(dir, id) {
   };
 }
 function loadMappedModules(dir) {
-  const path5 = join(dir, DESCRIPTOR_PATH);
-  if (!exists(path5)) return [];
+  const path6 = join(dir, DESCRIPTOR_PATH);
+  if (!exists(path6)) return [];
   let parsed;
   try {
-    parsed = parseYaml4(readFile(path5));
+    parsed = parseYaml4(readFile(path6));
   } catch {
     return [];
   }
@@ -2433,7 +2433,7 @@ function sectionParagraph2(md, title) {
   }
   return "";
 }
-function parseCapsule(id, path5, md) {
+function parseCapsule(id, path6, md) {
   const { data } = matter4(md);
   const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
   let ageDays = null;
@@ -2443,7 +2443,7 @@ function parseCapsule(id, path5, md) {
   }
   return {
     id,
-    path: path5,
+    path: path6,
     system: data.system ? String(data.system) : id,
     owner: data.owner ? String(data.owner) : void 0,
     updatedAt,
@@ -2505,9 +2505,9 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
   ];
   const presentLayers = [];
   for (const layer2 of layerDocs) {
-    const path5 = layer2.files.map((f3) => `${KNOWLEDGE3}/${f3}`).find((rel) => exists(join(dir, rel)));
-    if (path5) {
-      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path5 });
+    const path6 = layer2.files.map((f3) => `${KNOWLEDGE3}/${f3}`).find((rel) => exists(join(dir, rel)));
+    if (path6) {
+      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path6 });
       presentLayers.push(layer2.id);
     }
   }
@@ -4088,10 +4088,10 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   const q3 = (rel) => analyzeKnowledgeArtifact(dir, rel);
   const resolveAgent = (agent) => {
     const file = agent.endsWith(".md") ? agent : `${agent}.md`;
-    const path5 = agentInstallPath(file);
-    const installed = isFile(join(dir, path5));
+    const path6 = agentInstallPath(file);
+    const installed = isFile(join(dir, path6));
     const group = agentGroupOf(file);
-    return { agentPath: path5, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
+    return { agentPath: path6, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
   };
   const moduleRepo = isModule(config);
   const coreRepo = isCore(config);
@@ -7643,6 +7643,7 @@ function parseWorkItemSource(frontmatter) {
       title: optStr(obj.title) ?? optStr(frontmatter.source_title),
       context: optStr(obj.context) ?? optStr(frontmatter.source_context),
       provider: optStr(obj.provider) ?? optStr(frontmatter.source_provider),
+      integration: optStr(obj.integration) ?? optStr(frontmatter.source_integration),
       url: optStr(obj.url) ?? optStr(frontmatter.source_url),
       imported_at: optStr(obj.imported_at) ?? optStr(frontmatter.source_imported_at),
       synced_at: optStr(obj.synced_at) ?? optStr(frontmatter.source_synced_at),
@@ -9131,7 +9132,7 @@ function buildGuardHistory(dir) {
     const d3 = hotspotDir(t.code_path);
     hotspotMap.set(d3, (hotspotMap.get(d3) ?? 0) + 1);
   }
-  const hotspots = [...hotspotMap.entries()].map(([path5, warnings]) => ({ path: path5, warnings })).sort((a2, b2) => b2.warnings - a2.warnings);
+  const hotspots = [...hotspotMap.entries()].map(([path6, warnings]) => ({ path: path6, warnings })).sort((a2, b2) => b2.warnings - a2.warnings);
   return {
     available: true,
     total_runs: sorted.length,
@@ -11515,16 +11516,16 @@ function findSystemPaths(dir, source, target, opts = {}) {
     out.get(r2.source).push(r2.target);
   }
   const paths = [];
-  const walk = (node, path5) => {
+  const walk = (node, path6) => {
     if (paths.length >= 20) return;
-    if (node === target && path5.length > 1) {
-      paths.push([...path5]);
+    if (node === target && path6.length > 1) {
+      paths.push([...path6]);
       return;
     }
-    if (path5.length > maxDepth) return;
+    if (path6.length > maxDepth) return;
     for (const nxt of out.get(node) ?? []) {
-      if (path5.includes(nxt)) continue;
-      walk(nxt, [...path5, nxt]);
+      if (path6.includes(nxt)) continue;
+      walk(nxt, [...path6, nxt]);
     }
   };
   walk(source, [source]);
@@ -11549,14 +11550,14 @@ function getImpactCandidates(dir, seedIds, opts = {}) {
         existing.reason.push(reason);
         continue;
       }
-      const path5 = findSystemPaths(dir, seed, n.id, { maxDepth: opts.maxDepth ?? DEFAULT_MAX_DEPTH })[0];
+      const path6 = findSystemPaths(dir, seed, n.id, { maxDepth: opts.maxDepth ?? DEFAULT_MAX_DEPTH })[0];
       candidates.set(n.id, {
         nodeId: n.id,
         label: n.label,
         kind: n.type,
         ...n.moduleId ? { moduleId: n.moduleId } : {},
         reason: [reason],
-        ...path5 ? { graphPath: path5.map((id) => byId.get(id)?.label ?? id) } : {},
+        ...path6 ? { graphPath: path6.map((id) => byId.get(id)?.label ?? id) } : {},
         ...n.implementationRefs?.length ? { implementationRefs: n.implementationRefs } : {},
         ...n.knowledgeRefs?.length ? { knowledgeRefs: n.knowledgeRefs } : {},
         status: "candidate",
@@ -11654,8 +11655,596 @@ function systemImpactCandidatesTool(root, args) {
   });
 }
 
-// ../cli/src/core/context-pack.ts
+// ../cli/src/services/integrations.ts
+import matter13 from "gray-matter";
+import { parse as parseYaml12, stringify as stringifyYaml6 } from "yaml";
+
+// ../cli/src/core/work-item-write.ts
+import fs5 from "fs";
+import path5 from "path";
+import crypto2 from "crypto";
 import matter12 from "gray-matter";
+var SECTION_ORDER = [
+  "Actor",
+  "Outcome",
+  "Current behavior",
+  "Target behavior",
+  "Entry points",
+  "End-to-end flow",
+  "Scope unknowns",
+  "Acceptance criteria"
+];
+var KNOWN_HEADINGS = new Set(SECTION_ORDER.map((s) => s.toLowerCase()));
+
+// ../integrations/src/errors.ts
+var RETRYABLE = /* @__PURE__ */ new Set([
+  "INTEGRATION_RATE_LIMITED",
+  "INTEGRATION_UNAVAILABLE",
+  "INTEGRATION_TIMEOUT"
+]);
+var IntegrationError = class extends Error {
+  code;
+  /** True for transient conditions (rate limit / unavailable / timeout). */
+  retryable;
+  /** A safe, provider-agnostic reason. Never the raw SDK message. */
+  safeMessage;
+  constructor(code, message) {
+    super(message);
+    this.name = "IntegrationError";
+    this.code = code;
+    this.retryable = RETRYABLE.has(code);
+    this.safeMessage = message;
+  }
+};
+function defaultMessageFor(code) {
+  switch (code) {
+    case "INTEGRATION_CONFIG_INVALID":
+      return "The integration configuration is invalid.";
+    case "INTEGRATION_UNAUTHORIZED":
+      return "Authentication failed. Check the configured credentials.";
+    case "INTEGRATION_FORBIDDEN":
+      return "The configured credentials lack permission for this operation.";
+    case "INTEGRATION_NOT_FOUND":
+      return "The requested external resource was not found.";
+    case "INTEGRATION_RATE_LIMITED":
+      return "The external provider is rate limiting requests. Try again later.";
+    case "INTEGRATION_UNAVAILABLE":
+      return "The external provider is temporarily unavailable.";
+    case "INTEGRATION_TIMEOUT":
+      return "The external provider did not respond in time.";
+    case "INTEGRATION_PROVIDER_ERROR":
+      return "The external provider returned an error.";
+    case "UNSUPPORTED_CAPABILITY":
+      return "This adapter does not support the requested capability.";
+  }
+}
+function integrationError(code, message) {
+  return new IntegrationError(code, message ?? defaultMessageFor(code));
+}
+
+// ../integrations/src/config.ts
+var ENV_SUFFIX = "_env";
+var SECRET_KEY = /(token|secret|password|key|pat|apikey|api_key)/i;
+function parseCredentials(raw, id, findings) {
+  const creds = {};
+  if (raw == null) return creds;
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    findings.push({ level: "blocking", id, message: `Integration "${id}": credentials must be a mapping of secret references.` });
+    return creds;
+  }
+  for (const [key, value] of Object.entries(raw)) {
+    if (key.endsWith(ENV_SUFFIX)) {
+      const name = key.slice(0, -ENV_SUFFIX.length);
+      if (typeof value === "string" && value.trim()) creds[name] = { env: value.trim() };
+      else findings.push({ level: "blocking", id, message: `Integration "${id}": credential "${key}" must name an environment variable.` });
+      continue;
+    }
+    if (SECRET_KEY.test(key) && typeof value === "string") {
+      findings.push({ level: "blocking", id, message: `Integration "${id}": secret "${key}" must not be stored in config. Use "${key}${ENV_SUFFIX}: <ENV_VAR_NAME>".` });
+      continue;
+    }
+    if (value && typeof value === "object" && typeof value.env === "string") {
+      creds[key] = { env: String(value.env) };
+      continue;
+    }
+    findings.push({ level: "warning", id, message: `Integration "${id}": ignoring unrecognized credential entry "${key}".` });
+  }
+  return creds;
+}
+function parseSecrets(raw, id, findings) {
+  const secrets = {};
+  if (raw == null) return secrets;
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    findings.push({ level: "blocking", id, message: `Integration "${id}": secrets must be a mapping of logical references.` });
+    return secrets;
+  }
+  for (const [key, value] of Object.entries(raw)) {
+    if (typeof value === "string" && value.trim()) {
+      if (value.length > 100 || /^(ghp_|sk-|xox[bpsa]-|glpat-|ey[A-Za-z0-9])/i.test(value)) {
+        findings.push({ level: "blocking", id, message: `Integration "${id}": secret "${key}" appears to contain an actual credential, not a reference name.` });
+        continue;
+      }
+      secrets[key] = value.trim();
+    } else {
+      findings.push({ level: "warning", id, message: `Integration "${id}": ignoring non-string secret entry "${key}".` });
+    }
+  }
+  return secrets;
+}
+function parseIntegrationsConfig(raw, opts) {
+  const findings = [];
+  const integrations = [];
+  const list2 = raw && typeof raw === "object" && Array.isArray(raw.integrations) ? raw.integrations : Array.isArray(raw) ? raw : [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of list2) {
+    if (!entry || typeof entry !== "object") {
+      findings.push({ level: "blocking", message: "Each integration must be a mapping." });
+      continue;
+    }
+    const o2 = entry;
+    const id = typeof o2.id === "string" ? o2.id.trim() : "";
+    const adapter = typeof o2.adapter === "string" ? o2.adapter.trim() : "";
+    if (!id) {
+      findings.push({ level: "blocking", message: 'An integration is missing a required "id".' });
+      continue;
+    }
+    if (seen.has(id)) {
+      findings.push({ level: "blocking", id, message: `Duplicate integration id "${id}".` });
+      continue;
+    }
+    seen.add(id);
+    if (!adapter) {
+      findings.push({ level: "blocking", id, message: `Integration "${id}" is missing a required "adapter".` });
+      continue;
+    }
+    if (!opts.adapterIds.has(adapter)) {
+      findings.push({ level: "blocking", id, message: `Integration "${id}" references unknown adapter "${adapter}".` });
+    }
+    const enabled = o2.enabled === void 0 ? true : o2.enabled === true || o2.enabled === "true";
+    const config = o2.config && typeof o2.config === "object" && !Array.isArray(o2.config) ? o2.config : {};
+    const credentials = parseCredentials(o2.credentials, id, findings);
+    const secrets = parseSecrets(o2.secrets, id, findings);
+    const timeoutMs = typeof o2.timeout_ms === "number" ? o2.timeout_ms : typeof o2.timeoutMs === "number" ? o2.timeoutMs : void 0;
+    integrations.push({ id, adapter, enabled, config, credentials, secrets, timeoutMs });
+  }
+  return { integrations, findings };
+}
+async function resolveAllCredentials(integration, resolver, env) {
+  const credentials = {};
+  const missing = [];
+  for (const [name, ref] of Object.entries(integration.credentials)) {
+    const value = env[ref.env];
+    if (value && value.length > 0) credentials[name] = value;
+    else missing.push(ref.env);
+  }
+  for (const [name, ref] of Object.entries(integration.secrets)) {
+    if (credentials[name]) continue;
+    const value = await resolver.resolve(ref);
+    if (value !== void 0) credentials[name] = value;
+    else missing.push(ref);
+  }
+  return { credentials, missing };
+}
+
+// ../integrations/src/secrets.ts
+import { readFileSync as readFileSync2, writeFileSync, mkdirSync, existsSync as existsSync2, unlinkSync } from "fs";
+import { dirname as dirname2 } from "path";
+var SECRETS_FILENAME = ".secrets.json";
+function secretsPath(projectDir) {
+  return `${projectDir}/.kaddo/${SECRETS_FILENAME}`;
+}
+function loadStore(filePath) {
+  if (!existsSync2(filePath)) return {};
+  try {
+    const raw = readFileSync2(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+    return {};
+  } catch {
+    return {};
+  }
+}
+function saveStore(filePath, store) {
+  mkdirSync(dirname2(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(store, null, 2) + "\n", "utf-8");
+}
+function createLocalSecretProvider(projectDir) {
+  const fp = secretsPath(projectDir);
+  return {
+    async get(key) {
+      const store = loadStore(fp);
+      const val = store[key];
+      return val !== void 0 && val !== "" ? val : void 0;
+    },
+    async set(key, value) {
+      const store = loadStore(fp);
+      store[key] = value;
+      saveStore(fp, store);
+    },
+    async delete(key) {
+      const store = loadStore(fp);
+      delete store[key];
+      saveStore(fp, store);
+    },
+    async exists(key) {
+      const store = loadStore(fp);
+      return key in store && store[key] !== void 0 && store[key] !== "";
+    }
+  };
+}
+function createEnvSecretProvider(env = process.env) {
+  return {
+    async get(key) {
+      const val = env[key];
+      return val !== void 0 && val !== "" ? val : void 0;
+    },
+    async set() {
+      throw new Error("Environment secret provider is read-only.");
+    },
+    async delete() {
+      throw new Error("Environment secret provider is read-only.");
+    },
+    async exists(key) {
+      const val = env[key];
+      return val !== void 0 && val !== "";
+    }
+  };
+}
+function createCompositeResolver(...providers) {
+  return {
+    async resolve(reference) {
+      for (const provider of providers) {
+        const val = await provider.get(reference);
+        if (val !== void 0) return val;
+      }
+      return void 0;
+    }
+  };
+}
+
+// ../integrations/src/registry.ts
+var DuplicateAdapterError = class extends Error {
+  constructor(id) {
+    super(`An integration adapter with id "${id}" is already registered.`);
+    this.name = "DuplicateAdapterError";
+  }
+};
+var IntegrationRegistry = class {
+  adapters = /* @__PURE__ */ new Map();
+  register(adapter) {
+    if (this.adapters.has(adapter.id)) throw new DuplicateAdapterError(adapter.id);
+    this.adapters.set(adapter.id, adapter);
+  }
+  get(id) {
+    return this.adapters.get(id);
+  }
+  has(id) {
+    return this.adapters.has(id);
+  }
+  list() {
+    return [...this.adapters.values()].sort((a2, b2) => a2.id.localeCompare(b2.id));
+  }
+  ids() {
+    return new Set(this.adapters.keys());
+  }
+};
+
+// ../integrations/src/mock-adapter.ts
+var MOCK_ADAPTER_ID = "mock";
+var DEFAULT_ITEMS = [
+  {
+    externalId: "EXT-001",
+    provider: MOCK_ADAPTER_ID,
+    title: "Open public registration to everyone",
+    description: "Open self-service registration to the public once the private beta ends.",
+    type: "Feature",
+    status: "Open",
+    url: "https://example.test/mock/EXT-001",
+    labels: ["registration", "beta"],
+    createdAt: "2026-01-05T10:00:00.000Z",
+    updatedAt: "2026-02-01T09:30:00.000Z",
+    rawMetadata: { board: "delivery" }
+  },
+  {
+    externalId: "EXT-002",
+    provider: MOCK_ADAPTER_ID,
+    title: "Personalize onboarding steps",
+    description: "The onboarding checklist should adapt to what the user has already completed.",
+    type: "Task",
+    status: "To Do",
+    url: "https://example.test/mock/EXT-002",
+    labels: ["onboarding"],
+    createdAt: "2026-01-08T12:00:00.000Z",
+    updatedAt: "2026-01-20T15:00:00.000Z"
+  }
+];
+function simulationOf(context, fallback) {
+  const fromConfig = context.config?.simulate;
+  return typeof fromConfig === "string" ? fromConfig : fallback;
+}
+function readFailure(sim) {
+  switch (sim) {
+    case "unauthorized":
+      throw integrationError("INTEGRATION_UNAUTHORIZED");
+    case "rate-limited":
+      throw integrationError("INTEGRATION_RATE_LIMITED");
+    case "unavailable":
+      throw integrationError("INTEGRATION_UNAVAILABLE");
+    case "timeout":
+      throw integrationError("INTEGRATION_TIMEOUT");
+    case "available":
+      break;
+  }
+}
+function createMockAdapter(opts = {}) {
+  const items = opts.items ?? DEFAULT_ITEMS;
+  const defaultSim = opts.simulate ?? "available";
+  const defaultPageSize = opts.pageSize ?? 50;
+  return {
+    id: MOCK_ADAPTER_ID,
+    metadata: {
+      id: MOCK_ADAPTER_ID,
+      displayName: "Mock Work Source",
+      version: "1.0.0",
+      description: "Deterministic offline reference adapter for validating the integration foundation.",
+      configSchema: {
+        simulate: {
+          type: "select",
+          required: false,
+          label: "Simulation mode",
+          description: "Controls what the mock adapter simulates during verify/read operations.",
+          options: [
+            { value: "available", label: "Available" },
+            { value: "unauthorized", label: "Unauthorized" },
+            { value: "rate-limited", label: "Rate Limited" },
+            { value: "unavailable", label: "Unavailable" },
+            { value: "timeout", label: "Timeout" }
+          ],
+          defaultValue: "available"
+        }
+      },
+      secretSchema: {
+        token: {
+          type: "string",
+          required: false,
+          label: "API Token",
+          description: "Optional token for testing secret handling (not used by the mock adapter)."
+        }
+      }
+    },
+    capabilities: {
+      workItems: { list: true, read: true, import: true, write: false, statusSync: false, comments: false, webhooks: false }
+    },
+    async verifyConnection(context) {
+      const sim = simulationOf(context, defaultSim);
+      const checkedAt = (/* @__PURE__ */ new Date()).toISOString();
+      switch (sim) {
+        case "available":
+          return { status: "available", checkedAt };
+        case "unauthorized":
+          return { status: "unauthorized", message: "Check the configured credentials.", checkedAt };
+        case "rate-limited":
+        case "unavailable":
+        case "timeout":
+          return { status: "unavailable", message: "The mock provider is temporarily unavailable.", checkedAt };
+      }
+    },
+    async listWorkItems(request) {
+      readFailure(simulationOf(request.context, defaultSim));
+      let pool = items;
+      const f3 = request.filters;
+      if (f3?.status) pool = pool.filter((i) => (i.status ?? "").toLowerCase() === f3.status.toLowerCase());
+      if (f3?.query) pool = pool.filter((i) => `${i.title} ${i.description ?? ""}`.toLowerCase().includes(f3.query.toLowerCase()));
+      if (f3?.updatedSince) pool = pool.filter((i) => (i.updatedAt ?? "") >= f3.updatedSince);
+      const size = Math.max(1, request.pageSize ?? defaultPageSize);
+      const start = request.cursor ? Math.max(0, Number.parseInt(request.cursor, 10) || 0) : 0;
+      const slice = pool.slice(start, start + size);
+      const end = start + slice.length;
+      const hasMore = end < pool.length;
+      return { items: slice, hasMore, ...hasMore ? { nextCursor: String(end) } : {} };
+    },
+    async getWorkItem(request) {
+      readFailure(simulationOf(request.context, defaultSim));
+      return items.find((i) => i.externalId === request.externalId) ?? null;
+    }
+  };
+}
+
+// ../integrations/src/index.ts
+function createDefaultRegistry() {
+  const registry2 = new IntegrationRegistry();
+  registry2.register(createMockAdapter());
+  return registry2;
+}
+
+// ../cli/src/services/integrations.ts
+var INTEGRATIONS_FILE = ".kaddo/integrations.yml";
+var DEFAULT_TIMEOUT_MS = 1e4;
+var registry = createDefaultRegistry();
+var IntegrationServiceError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "IntegrationServiceError";
+    this.code = code;
+  }
+};
+function loadRaw(dir) {
+  const abs = join(dir, INTEGRATIONS_FILE);
+  if (!exists(abs)) return { integrations: [] };
+  try {
+    return parseYaml12(readFile(abs)) ?? { integrations: [] };
+  } catch {
+    return { integrations: [] };
+  }
+}
+function loadIntegrations(dir) {
+  return parseIntegrationsConfig(loadRaw(dir), { adapterIds: registry.ids() });
+}
+function configStatus(integration, findings) {
+  if (!integration.enabled) return "disabled";
+  const blocking = findings.some((f3) => f3.id === integration.id && f3.level === "blocking");
+  if (blocking || !registry.has(integration.adapter)) return "invalid-config";
+  return "configured";
+}
+function secretResolver(dir, env) {
+  return createCompositeResolver(createLocalSecretProvider(dir), createEnvSecretProvider(env));
+}
+function listIntegrations(dir) {
+  const { integrations, findings } = loadIntegrations(dir);
+  return integrations.map((integration) => {
+    const adapter = registry.get(integration.adapter);
+    return {
+      id: integration.id,
+      adapter: integration.adapter,
+      enabled: integration.enabled,
+      status: configStatus(integration, findings),
+      displayName: adapter?.metadata.displayName ?? integration.adapter,
+      capabilities: adapter?.capabilities ?? null,
+      metadata: adapter?.metadata ?? null,
+      credentialRefs: Object.values(integration.credentials).map((c) => c.env),
+      secretRefs: Object.values(integration.secrets),
+      secretStatus: {},
+      findings: findings.filter((f3) => f3.id === integration.id)
+    };
+  });
+}
+function requireIntegration(dir, id) {
+  const { integrations, findings } = loadIntegrations(dir);
+  const integration = integrations.find((i) => i.id === id);
+  if (!integration) throw new IntegrationServiceError("INTEGRATION_NOT_CONFIGURED", `No integration "${id}" is configured in this project.`);
+  return { integration, findings, all: integrations };
+}
+function resolveAdapter(integration) {
+  const adapter = registry.get(integration.adapter);
+  if (!adapter) throw new IntegrationServiceError("ADAPTER_NOT_FOUND", `Unknown integration adapter "${integration.adapter}".`);
+  return adapter;
+}
+async function buildContextWithSecrets(dir, integration, env) {
+  const resolver = secretResolver(dir, env);
+  const { credentials, missing } = await resolveAllCredentials(integration, resolver, env);
+  return {
+    context: { integrationId: integration.id, config: integration.config, credentials, timeoutMs: integration.timeoutMs ?? DEFAULT_TIMEOUT_MS },
+    missing
+  };
+}
+async function withTimeout(op, ms) {
+  let timer;
+  const timeout = new Promise((_3, reject) => {
+    timer = setTimeout(() => reject(integrationError("INTEGRATION_TIMEOUT")), ms);
+  });
+  try {
+    return await Promise.race([op, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+async function verifyIntegration(dir, id, env = process.env) {
+  const { integration, findings } = requireIntegration(dir, id);
+  const cfgStatus = configStatus(integration, findings);
+  if (cfgStatus === "disabled") return { id, status: "disabled", connection: null, missingCredentials: [] };
+  if (cfgStatus === "invalid-config") return { id, status: "invalid-config", connection: null, missingCredentials: [] };
+  const adapter = resolveAdapter(integration);
+  const { context, missing } = await buildContextWithSecrets(dir, integration, env);
+  try {
+    const connection = await withTimeout(adapter.verifyConnection(context), context.timeoutMs);
+    return { id, status: statusOf(connection), connection, missingCredentials: missing, message: connection.message };
+  } catch (err) {
+    const e = err instanceof IntegrationError ? err : integrationError("INTEGRATION_PROVIDER_ERROR");
+    return { id, status: e.code === "INTEGRATION_UNAUTHORIZED" ? "unauthorized" : "unavailable", connection: null, missingCredentials: missing, message: e.safeMessage };
+  }
+}
+function statusOf(connection) {
+  switch (connection.status) {
+    case "available":
+      return "available";
+    case "unauthorized":
+      return "unauthorized";
+    case "unavailable":
+      return "unavailable";
+    case "invalid-config":
+      return "invalid-config";
+  }
+}
+async function listExternalWorkItems(dir, id, opts = {}, env = process.env) {
+  const { integration } = requireIntegration(dir, id);
+  const adapter = resolveAdapter(integration);
+  if (!adapter.capabilities.workItems.list) throw integrationError("UNSUPPORTED_CAPABILITY", `Adapter "${adapter.id}" cannot list work items.`);
+  const { context } = await buildContextWithSecrets(dir, integration, env);
+  return withTimeout(adapter.listWorkItems({ context, cursor: opts.cursor, pageSize: opts.pageSize, filters: opts.filters }), context.timeoutMs);
+}
+async function getExternalWorkItem(dir, id, externalId, env = process.env) {
+  const { integration } = requireIntegration(dir, id);
+  const adapter = resolveAdapter(integration);
+  if (!adapter.capabilities.workItems.read) throw integrationError("UNSUPPORTED_CAPABILITY", `Adapter "${adapter.id}" cannot read work items.`);
+  const { context } = await buildContextWithSecrets(dir, integration, env);
+  return withTimeout(adapter.getWorkItem({ context, externalId }), context.timeoutMs);
+}
+
+// src/integrations.ts
+var ok4 = (data) => ({ ok: true, data });
+var fail3 = (message) => ({ ok: false, message });
+function safeError(err) {
+  if (err instanceof IntegrationError) return fail3(`[${err.code}] ${err.safeMessage}`);
+  return fail3("The integration operation failed.");
+}
+function integrationsListTool(root) {
+  return ok4({
+    integrations: listIntegrations(root).map((i) => ({
+      id: i.id,
+      adapter: i.adapter,
+      enabled: i.enabled,
+      status: i.status,
+      displayName: i.displayName,
+      capabilities: i.capabilities,
+      // Only credential *reference* names — never values.
+      credentialRefs: i.credentialRefs
+    })),
+    note: "Read-only. Reading external items never creates a Kaddo Work Item; import requires human confirmation."
+  });
+}
+async function integrationsStatusTool(root, args) {
+  try {
+    const summaries = listIntegrations(root).filter((s) => !args.id || s.id === args.id);
+    const results = await Promise.all(summaries.map(async (s) => {
+      if (s.status === "disabled" || s.status === "invalid-config") return { id: s.id, status: s.status };
+      const v = await verifyIntegration(root, s.id);
+      return { id: v.id, status: v.status, message: v.message, missingCredentials: v.missingCredentials };
+    }));
+    return ok4({ statuses: results });
+  } catch (err) {
+    return safeError(err);
+  }
+}
+async function integrationsWorkItemsTool(root, args) {
+  try {
+    const page = await listExternalWorkItems(root, args.id, {
+      cursor: args.cursor,
+      pageSize: args.pageSize,
+      filters: { status: args.status, query: args.query }
+    });
+    return ok4({
+      items: page.items,
+      hasMore: page.hasMore,
+      nextCursor: page.nextCursor ?? null,
+      note: "Read-only external items. Import them explicitly (with human confirmation) to create a Kaddo Draft."
+    });
+  } catch (err) {
+    return safeError(err);
+  }
+}
+async function integrationsWorkItemTool(root, args) {
+  try {
+    const item = await getExternalWorkItem(root, args.id, args.externalId);
+    if (!item) return ok4({ found: false });
+    return ok4({ found: true, item });
+  } catch (err) {
+    return safeError(err);
+  }
+}
+
+// ../cli/src/core/context-pack.ts
+import matter14 from "gray-matter";
 var CONTEXT_PACK_VERSION = "1";
 var ARCH_DIR3 = "knowledge";
 function readScanJson(dir) {
@@ -11668,7 +12257,7 @@ function readScanJson(dir) {
   }
 }
 function firstParagraph4(markdown) {
-  const body = matter12(markdown).content.trim();
+  const body = matter14(markdown).content.trim();
   const para = body.split("\n\n").map((p) => p.trim()).find((p) => p && !p.startsWith("#"));
   return para ?? "";
 }
@@ -12803,6 +13392,15 @@ function guarded(root, fn) {
     throw err;
   }
 }
+async function guardedAsync(root, fn) {
+  try {
+    assertKaddoProject(root);
+    return await fn();
+  } catch (err) {
+    if (err instanceof KaddoMcpError) return { ok: false, message: err.message };
+    throw err;
+  }
+}
 function generated(root, label, fn) {
   try {
     assertKaddoProject(root);
@@ -13044,6 +13642,45 @@ function createServer(root) {
     },
     async (args) => toolText(guarded(root, () => systemImpactCandidatesTool(root, args)))
   );
+  const INTEGRATION_READ_NOTE = "Read-only. Reading external items never creates a Kaddo Work Item; import is a separate, human-confirmed action.";
+  server.registerTool(
+    "kaddo_integrations_list",
+    { title: "List integrations", description: `List configured external-work-system integrations and their capabilities. ${INTEGRATION_READ_NOTE}`, inputSchema: {} },
+    async () => toolText(guarded(root, () => integrationsListTool(root)))
+  );
+  server.registerTool(
+    "kaddo_integrations_status",
+    {
+      title: "Integration status",
+      description: `Verify integrations and report connection status (available/unauthorized/unavailable/\u2026). Never returns secrets. ${INTEGRATION_READ_NOTE}`,
+      inputSchema: { id: z3.string().optional() }
+    },
+    async (args) => toolText(await guardedAsync(root, () => integrationsStatusTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_integrations_work_items",
+    {
+      title: "List external work items",
+      description: `List external work items from an integration (paginated). ${INTEGRATION_READ_NOTE}`,
+      inputSchema: {
+        id: z3.string(),
+        cursor: z3.string().optional(),
+        pageSize: z3.number().int().positive().optional(),
+        status: z3.string().optional(),
+        query: z3.string().optional()
+      }
+    },
+    async (args) => toolText(await guardedAsync(root, () => integrationsWorkItemsTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_integrations_work_item",
+    {
+      title: "Read an external work item",
+      description: `Read a single external work item by id. ${INTEGRATION_READ_NOTE}`,
+      inputSchema: { id: z3.string(), externalId: z3.string() }
+    },
+    async (args) => toolText(await guardedAsync(root, () => integrationsWorkItemTool(root, args)))
+  );
   let installedSkills = [];
   try {
     assertKaddoProject(root);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaddo/mcp",
-  "version": "3.81.0",
+  "version": "3.83.0",
   "description": "MCP server for Kaddo project knowledge: read-only resources/tools/prompts plus safe derived generation under .kaddo/.",
   "license": "MIT",
   "repository": {