@ken-jo/agent-connector 0.1.0 → 0.2.0

package/dist/chunk-GSGDG2BV.js

@@ -0,0 +1,568 @@
+#!/usr/bin/env node
+import {
+  MANAGED_BLOCK_BEGIN_TOKEN,
+  MANAGED_BLOCK_END_TOKEN,
+  MEMORY_CONTENT_HARD_CAP_BYTES
+} from "./chunk-N6HH7K6P.js";
+import {
+  ensureDir
+} from "./chunk-TRQKHP7D.js";
+
+// src/core/config-patch-ledger.ts
+import { createHash, randomBytes } from "crypto";
+import {
+  existsSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync
+} from "fs";
+import { dirname, join } from "path";
+var CONFIG_PATCH_SEGMENT_RE = /^[A-Za-z0-9_-]+$/;
+function isValidConfigPatchKey(key) {
+  if (typeof key !== "string" || key.length === 0) return false;
+  return key.split(".").every((seg) => CONFIG_PATCH_SEGMENT_RE.test(seg));
+}
+function isJsonValue(value) {
+  if (value === null) return true;
+  switch (typeof value) {
+    case "string":
+    case "boolean":
+      return true;
+    case "number":
+      return Number.isFinite(value);
+    case "object":
+      break;
+    default:
+      return false;
+  }
+  if (Array.isArray(value)) return value.every((v) => isJsonValue(v));
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) return false;
+  return Object.values(value).every((v) => isJsonValue(v));
+}
+function configPatchNamespaceViolation(key) {
+  const head = key.split(".")[0] ?? "";
+  if (head === "hooks") {
+    return `"${key}" targets the hooks config agent-connector already models; declare it via \`hooks\` (normalized) or \`platforms.<id>.nativeHooks\` instead`;
+  }
+  if (head === "mcpServers" || head === "enableAllProjectMcpServers" || head === "enabledMcpjsonServers" || head === "disabledMcpjsonServers") {
+    return `"${key}" targets MCP server registration agent-connector already models; declare it via \`server\` / \`platforms.<id>.server\` / \`extra\` instead`;
+  }
+  return null;
+}
+function configPatchManualEdit(patch) {
+  const docs = patch.docsUrl ? ` \u2014 see ${patch.docsUrl}` : "";
+  return `manual edit if wanted: set ${patch.key} = ${describeJsonValue(patch.value)} (${patch.reason})${docs}`;
+}
+function describeJsonValue(value) {
+  if (value === void 0) return "<absent>";
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+function canonicalJson(value) {
+  if (value === void 0) return "undefined";
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map((v) => canonicalJson(v)).join(",")}]`;
+  }
+  const keys = Object.keys(value).sort();
+  const parts = keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`);
+  return `{${parts.join(",")}}`;
+}
+function hashJsonValue(value) {
+  return createHash("sha256").update(canonicalJson(value)).digest("hex");
+}
+function jsonDeepEquals(a, b) {
+  return canonicalJson(a) === canonicalJson(b);
+}
+function configPatchLedgerPath(dataRoot) {
+  return join(dataRoot, "state", "config-patches.json");
+}
+function loadConfigPatchLedger(dataRoot) {
+  const path = configPatchLedgerPath(dataRoot);
+  if (!existsSync(path)) return { version: 1, entries: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (!parsed || !Array.isArray(parsed.entries)) return { version: 1, entries: [] };
+    return { version: 1, entries: parsed.entries.filter(isPlausibleEntry) };
+  } catch {
+    return { version: 1, entries: [] };
+  }
+}
+function isPlausibleEntry(e) {
+  if (e == null || typeof e !== "object") return false;
+  const entry = e;
+  return typeof entry.platform === "string" && typeof entry.file === "string" && typeof entry.key === "string" && Array.isArray(entry.owners);
+}
+function saveConfigPatchLedger(dataRoot, ledger) {
+  const path = configPatchLedgerPath(dataRoot);
+  ensureDir(dirname(path));
+  const tmpFile = `${path}.${process.pid}-${randomBytes(4).toString("hex")}.tmp`;
+  try {
+    writeFileSync(tmpFile, `${JSON.stringify(ledger, null, 2)}
+`, "utf8");
+    renameSync(tmpFile, path);
+  } catch (err) {
+    rmSync(tmpFile, { force: true });
+    throw err;
+  }
+}
+function findLedgerEntry(ledger, platform, file, key) {
+  return ledger.entries.find(
+    (e) => e.platform === platform && e.file === file && e.key === key
+  );
+}
+function ledgerEntriesOwnedBy(ledger, platform, connectorId) {
+  return ledger.entries.filter(
+    (e) => e.platform === platform && e.owners.some((o) => o.connectorId === connectorId)
+  );
+}
+function createLedgerEntry(ledger, init) {
+  const entry = {
+    platform: init.platform,
+    file: init.file,
+    key: init.key,
+    writtenValue: init.value,
+    writtenValueHash: hashJsonValue(init.value),
+    prior: { present: false },
+    owners: [
+      {
+        connectorId: init.connectorId,
+        connectorVersion: init.connectorVersion,
+        installedAt: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    ]
+  };
+  ledger.entries.push(entry);
+  return entry;
+}
+function addLedgerOwner(entry, connectorId, connectorVersion) {
+  if (entry.owners.some((o) => o.connectorId === connectorId)) return false;
+  entry.owners.push({
+    connectorId,
+    connectorVersion,
+    installedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  return true;
+}
+function removeLedgerOwner(entry, connectorId) {
+  const before = entry.owners.length;
+  entry.owners = entry.owners.filter((o) => o.connectorId !== connectorId);
+  return { removed: entry.owners.length < before, lastOwner: entry.owners.length === 0 };
+}
+function dropLedgerEntry(ledger, entry) {
+  ledger.entries = ledger.entries.filter((e) => e !== entry);
+}
+
+// src/core/define-connector.ts
+import { isAbsolute, normalize } from "path";
+
+// src/core/mcp-standard.ts
+var MCP_SERVER_SCHEMA_URL = "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json";
+var MCPB_MANIFEST_VERSION = "0.3";
+var MCP_PROTOCOL_VERSION = "2025-11-25";
+var NPM_REGISTRY_BASE_URL = "https://registry.npmjs.org";
+function registryTransportType(transport) {
+  switch (transport) {
+    case "stdio":
+      return "stdio";
+    case "http":
+      return "streamable-http";
+    case "sse":
+      return "sse";
+    case "ws":
+      return null;
+  }
+}
+function isConcreteSemver(v) {
+  return /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(v);
+}
+function isPlaceholderVersion(v) {
+  return v === "0.0.0";
+}
+var REGISTRY_NAMESPACE_RE = /^[a-zA-Z0-9.-]+$/;
+var REGISTRY_NAME_RE = /^[a-zA-Z0-9.-]+\/[a-zA-Z0-9._-]+$/;
+
+// src/core/define-connector.ts
+var ID_RE = /^[a-z0-9][a-z0-9-]*$/;
+var SURFACE_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+var SKILL_DESCRIPTION_MAX = 1024;
+var ALL_EVENTS = [
+  "SessionStart",
+  "SessionEnd",
+  "UserPromptSubmit",
+  "PreToolUse",
+  "PostToolUse",
+  "PreCompact",
+  "Stop",
+  "Notification",
+  "PermissionRequest",
+  "PostToolUseFailure",
+  "SubagentStart",
+  "SubagentStop"
+];
+var ConnectorConfigError = class extends Error {
+  constructor(message) {
+    super(`Invalid connector config: ${message}`);
+    this.name = "ConnectorConfigError";
+  }
+};
+function declaredEvents(hooks) {
+  if (!hooks) return [];
+  return ALL_EVENTS.filter((e) => typeof hooks[e]?.handler === "function");
+}
+function defineConnector(config) {
+  if (!config || typeof config !== "object") {
+    throw new ConnectorConfigError("config must be an object");
+  }
+  if (typeof config.id !== "string" || !ID_RE.test(config.id)) {
+    throw new ConnectorConfigError(
+      `id must be kebab-case matching ${ID_RE} (got ${JSON.stringify(config.id)})`
+    );
+  }
+  const hasCommands = Array.isArray(config.commands) && config.commands.length > 0;
+  const hasSkills = Array.isArray(config.skills) && config.skills.length > 0;
+  const hasSubagents = Array.isArray(config.subagents) && config.subagents.length > 0;
+  const hasMemory = Array.isArray(config.memory) && config.memory.length > 0;
+  const hasNativeHooks = Object.values(config.platforms ?? {}).some(
+    (override) => override?.nativeHooks != null && Object.keys(override.nativeHooks).length > 0
+  );
+  const hasConfigPatch = Object.values(config.platforms ?? {}).some(
+    (override) => Array.isArray(override?.configPatch) && override.configPatch.length > 0
+  );
+  if (!config.server && !config.hooks && !hasCommands && !hasSkills && !hasSubagents && !hasMemory && !hasNativeHooks && !hasConfigPatch) {
+    throw new ConnectorConfigError(
+      "a connector must declare at least one of `server`, `hooks`, `commands`, `skills`, `subagents`, `memory`, or a per-platform `nativeHooks` / `configPatch` declaration"
+    );
+  }
+  if (config.server) {
+    const s = config.server;
+    if (s.transport === "stdio") {
+      if (!s.command || typeof s.command !== "string") {
+        throw new ConnectorConfigError(
+          "server.command is required for stdio transport"
+        );
+      }
+    } else {
+      if (!s.url || typeof s.url !== "string") {
+        throw new ConnectorConfigError(
+          `server.url is required for ${s.transport} transport`
+        );
+      }
+    }
+  }
+  if (config.hooks) {
+    for (const ev of ALL_EVENTS) {
+      const def = config.hooks[ev];
+      if (def != null && typeof def.handler !== "function") {
+        throw new ConnectorConfigError(`hooks.${ev}.handler must be a function`);
+      }
+    }
+  }
+  validateNativeHooks(config.platforms);
+  validateConfigPatches(config.platforms);
+  const commands = normalizeCommands(config.commands);
+  const skills = normalizeSkills(config.skills);
+  const subagents = normalizeSubagents(config.subagents);
+  const memory = normalizeMemory(config.memory);
+  const t = config.telemetry ?? {};
+  const resolved = {
+    id: config.id,
+    displayName: config.displayName ?? config.id,
+    version: config.version ?? "0.0.0",
+    ...config.server ? { server: normalizeServer(config.server) } : {},
+    hooks: config.hooks ?? {},
+    hookEvents: declaredEvents(config.hooks),
+    telemetry: {
+      enabled: t.enabled ?? true,
+      modelFamilyHint: t.modelFamilyHint ?? "auto",
+      measureToolDefs: t.measureToolDefs ?? true,
+      // OPT-IN: host-native turn-usage capture is OFF unless explicitly enabled
+      // in config (or forced on at install via AGENT_CONNECTOR_HOST_NATIVE=1).
+      hostNativeUsage: t.hostNativeUsage ?? false,
+      store: t.store ?? "ndjson",
+      calibration: {
+        anthropicCountTokens: t.calibration?.anthropicCountTokens ?? false
+      }
+    },
+    commands,
+    skills,
+    subagents,
+    memory,
+    platforms: config.platforms ?? {},
+    targets: config.targets ?? "auto",
+    ...config.publish ? { publish: normalizePublish(config.publish) } : {}
+  };
+  return resolved;
+}
+var NORMALIZED_EVENT_SET = new Set(ALL_EVENTS);
+function validateNativeHooks(platforms) {
+  if (platforms == null) return;
+  for (const [platformId, override] of Object.entries(platforms)) {
+    const native = override?.nativeHooks;
+    if (native == null) continue;
+    const where = `platforms.${platformId}.nativeHooks`;
+    if (typeof native !== "object" || Array.isArray(native)) {
+      throw new ConnectorConfigError(
+        `${where} must be an object keyed by host-native event name`
+      );
+    }
+    for (const [event, def] of Object.entries(native)) {
+      if (NORMALIZED_EVENT_SET.has(event)) {
+        throw new ConnectorConfigError(
+          `${where}.${event} collides with the normalized hook event "${event}"; declare it under \`hooks.${event}\` (the normalized, cross-platform hooks API) instead`
+        );
+      }
+      if (def == null || typeof def !== "object" || typeof def.handler !== "function") {
+        throw new ConnectorConfigError(`${where}.${event}.handler must be a function`);
+      }
+      if (def.matcher !== void 0 && typeof def.matcher !== "string") {
+        throw new ConnectorConfigError(`${where}.${event}.matcher must be a string`);
+      }
+    }
+  }
+}
+function validateConfigPatches(platforms) {
+  if (platforms == null) return;
+  for (const [platformId, override] of Object.entries(platforms)) {
+    const patches = override?.configPatch;
+    if (patches == null) continue;
+    const where = `platforms.${platformId}.configPatch`;
+    if (!Array.isArray(patches)) {
+      throw new ConnectorConfigError(`${where} must be an array of patch objects`);
+    }
+    const seen = /* @__PURE__ */ new Set();
+    patches.forEach((patch, i) => {
+      if (patch == null || typeof patch !== "object" || Array.isArray(patch)) {
+        throw new ConnectorConfigError(`${where}[${i}] must be an object`);
+      }
+      if (!isValidConfigPatchKey(patch.key)) {
+        throw new ConnectorConfigError(
+          `${where}[${i}].key must be a dotted LEAF path whose segments match ${CONFIG_PATCH_SEGMENT_RE} (no dots-in-key, no array indices); got ${JSON.stringify(patch.key)}`
+        );
+      }
+      const violation = configPatchNamespaceViolation(patch.key);
+      if (violation) {
+        throw new ConnectorConfigError(`${where}[${i}].key ${violation}`);
+      }
+      if (seen.has(patch.key)) {
+        throw new ConnectorConfigError(
+          `${where}[${i}] duplicate key "${patch.key}"`
+        );
+      }
+      seen.add(patch.key);
+      if (!isJsonValue(patch.value)) {
+        throw new ConnectorConfigError(
+          `${where}[${i}].value must be JSON-serializable data (string/finite number/boolean/null/array/plain object)`
+        );
+      }
+      if (typeof patch.reason !== "string" || patch.reason.trim() === "") {
+        throw new ConnectorConfigError(
+          `${where}[${i}].reason is required (a human-readable why, printed in the install diff and every skip-warn)`
+        );
+      }
+      if (patch.docsUrl !== void 0 && typeof patch.docsUrl !== "string") {
+        throw new ConnectorConfigError(`${where}[${i}].docsUrl must be a string`);
+      }
+    });
+  }
+}
+function normalizePublish(publish) {
+  if (typeof publish !== "object" || Array.isArray(publish)) {
+    throw new ConnectorConfigError("publish must be an object");
+  }
+  if (publish.registryNamespace !== void 0) {
+    const ns = publish.registryNamespace;
+    if (typeof ns !== "string" || !REGISTRY_NAMESPACE_RE.test(ns)) {
+      throw new ConnectorConfigError(
+        `publish.registryNamespace must be a reverse-DNS namespace matching ${REGISTRY_NAMESPACE_RE} (e.g. "io.github.acme" or "com.acme"); got ${JSON.stringify(ns)}`
+      );
+    }
+  }
+  if (publish.packageName !== void 0 && typeof publish.packageName !== "string") {
+    throw new ConnectorConfigError("publish.packageName must be a string");
+  }
+  if (publish.author !== void 0) {
+    const a = publish.author;
+    if (typeof a !== "object" || a == null || typeof a.name !== "string" || a.name === "") {
+      throw new ConnectorConfigError("publish.author.name must be a non-empty string");
+    }
+  }
+  return { ...publish };
+}
+function assertSurfaceName(surface, name, index) {
+  if (typeof name !== "string" || !SURFACE_NAME_RE.test(name)) {
+    throw new ConnectorConfigError(
+      `${surface}[${index}].name must be kebab-case matching ${SURFACE_NAME_RE} (got ${JSON.stringify(name)})`
+    );
+  }
+  return name;
+}
+function assertNonEmptyString(surface, index, field, value) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new ConnectorConfigError(`${surface}[${index}].${field} must be a non-empty string`);
+  }
+  return value;
+}
+function assertNoDuplicate(surface, seen, name, index) {
+  if (seen.has(name)) {
+    throw new ConnectorConfigError(`${surface}[${index}] duplicate name "${name}"`);
+  }
+  seen.add(name);
+}
+function normalizeCommands(input) {
+  if (input == null) return [];
+  if (!Array.isArray(input)) {
+    throw new ConnectorConfigError("commands must be an array");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  return input.map((cmd, i) => {
+    if (!cmd || typeof cmd !== "object") {
+      throw new ConnectorConfigError(`commands[${i}] must be an object`);
+    }
+    const name = assertSurfaceName("commands", cmd.name, i);
+    assertNoDuplicate("commands", seen, name, i);
+    assertNonEmptyString("commands", i, "prompt", cmd.prompt);
+    return { ...cmd, name };
+  });
+}
+function normalizeSkills(input) {
+  if (input == null) return [];
+  if (!Array.isArray(input)) {
+    throw new ConnectorConfigError("skills must be an array");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  return input.map((skill, i) => {
+    if (!skill || typeof skill !== "object") {
+      throw new ConnectorConfigError(`skills[${i}] must be an object`);
+    }
+    const name = assertSurfaceName("skills", skill.name, i);
+    assertNoDuplicate("skills", seen, name, i);
+    const description = assertNonEmptyString("skills", i, "description", skill.description);
+    if (description.length > SKILL_DESCRIPTION_MAX) {
+      throw new ConnectorConfigError(
+        `skills[${i}].description exceeds ${SKILL_DESCRIPTION_MAX} chars (got ${description.length})`
+      );
+    }
+    assertNonEmptyString("skills", i, "body", skill.body);
+    assertSafeResourceKeys("skills", i, skill.resources);
+    return { ...skill, name };
+  });
+}
+function assertSafeResourceKeys(surface, index, resources) {
+  if (resources == null) return;
+  if (typeof resources !== "object" || Array.isArray(resources)) {
+    throw new ConnectorConfigError(`${surface}[${index}].resources must be an object`);
+  }
+  for (const rel of Object.keys(resources)) {
+    if (rel === "" || rel === "." || rel.trim() === "") {
+      throw new ConnectorConfigError(
+        `${surface}[${index}].resources key must be a non-empty relative path (got ${JSON.stringify(rel)})`
+      );
+    }
+    if (isAbsolute(rel)) {
+      throw new ConnectorConfigError(
+        `${surface}[${index}].resources key must be a relative path inside the skill dir, not absolute (got ${JSON.stringify(rel)})`
+      );
+    }
+    const norm = normalize(rel.replace(/\\/g, "/"));
+    const segs = norm.split(/[/\\]/);
+    if (norm === ".." || norm.startsWith("../") || norm.startsWith("..\\") || segs.includes("..")) {
+      throw new ConnectorConfigError(
+        `${surface}[${index}].resources key must not escape the skill dir via ".." (got ${JSON.stringify(rel)})`
+      );
+    }
+  }
+}
+var MEMORY_DEFAULT_NAME = "memory";
+function normalizeMemory(input) {
+  if (input == null) return [];
+  if (!Array.isArray(input)) {
+    throw new ConnectorConfigError("memory must be an array");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  return input.map((entry, i) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new ConnectorConfigError(`memory[${i}] must be an object`);
+    }
+    const name = entry.name === void 0 ? MEMORY_DEFAULT_NAME : assertSurfaceName("memory", entry.name, i);
+    assertNoDuplicate("memory", seen, name, i);
+    const content = assertNonEmptyString("memory", i, "content", entry.content);
+    const bytes = Buffer.byteLength(content, "utf8");
+    if (bytes > MEMORY_CONTENT_HARD_CAP_BYTES) {
+      throw new ConnectorConfigError(
+        `memory[${i}].content exceeds the ${MEMORY_CONTENT_HARD_CAP_BYTES}-byte hard cap (got ${bytes} bytes); memory is inlined into every prompt of every targeted host \u2014 keep it terse`
+      );
+    }
+    for (const token of [MANAGED_BLOCK_BEGIN_TOKEN, MANAGED_BLOCK_END_TOKEN]) {
+      if (content.includes(token)) {
+        throw new ConnectorConfigError(
+          `memory[${i}].content must not contain the literal marker token "${token}" (it would corrupt managed-block scanning in the shared memory file); rephrase the guidance`
+        );
+      }
+    }
+    if (entry.description !== void 0 && typeof entry.description !== "string") {
+      throw new ConnectorConfigError(`memory[${i}].description must be a string`);
+    }
+    return { ...entry, name };
+  });
+}
+function normalizeSubagents(input) {
+  if (input == null) return [];
+  if (!Array.isArray(input)) {
+    throw new ConnectorConfigError("subagents must be an array");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  return input.map((agent, i) => {
+    if (!agent || typeof agent !== "object") {
+      throw new ConnectorConfigError(`subagents[${i}] must be an object`);
+    }
+    const name = assertSurfaceName("subagents", agent.name, i);
+    assertNoDuplicate("subagents", seen, name, i);
+    assertNonEmptyString("subagents", i, "description", agent.description);
+    assertNonEmptyString("subagents", i, "prompt", agent.prompt);
+    return { ...agent, name };
+  });
+}
+function normalizeServer(server) {
+  if (!server) return void 0;
+  const wrapDefault = server.transport === "stdio";
+  return {
+    ...server,
+    enabled: server.enabled ?? true,
+    tools: server.tools ?? { include: ["*"] },
+    wrapForTelemetry: server.wrapForTelemetry ?? wrapDefault
+  };
+}
+
+export {
+  MCP_SERVER_SCHEMA_URL,
+  MCPB_MANIFEST_VERSION,
+  MCP_PROTOCOL_VERSION,
+  NPM_REGISTRY_BASE_URL,
+  registryTransportType,
+  isConcreteSemver,
+  isPlaceholderVersion,
+  REGISTRY_NAME_RE,
+  isValidConfigPatchKey,
+  configPatchNamespaceViolation,
+  configPatchManualEdit,
+  describeJsonValue,
+  hashJsonValue,
+  jsonDeepEquals,
+  loadConfigPatchLedger,
+  saveConfigPatchLedger,
+  findLedgerEntry,
+  ledgerEntriesOwnedBy,
+  createLedgerEntry,
+  addLedgerOwner,
+  removeLedgerOwner,
+  dropLedgerEntry,
+  ConnectorConfigError,
+  defineConnector
+};
+//# sourceMappingURL=chunk-GSGDG2BV.js.map