defineConnector(config: ConnectorConfig): ResolvedConnector — the public, write-once surface. It validates eagerly and throws ConnectorConfigError on any violation, returning a fully-defaulted ResolvedConnector that adapters and the CLI consume.

The typed per-surface identity helpers and host-capability introspection live at the consolidated @ken-jo/agent-connector/sdk subpath: defineStatusline, defineAction, defineHook, defineCommand, defineSkill, defineSubagent, defineMemory, defineConfigPatch, defineNativeHook, plus hostsSupporting / capabilitiesOf / surfaceSupport. The root @ken-jo/agent-connector export is unchanged for backward compatibility — these helpers are also re-exported from root.

ConnectorConfig#

Top-level validation rules#

• config must be an object; if supplied, id must match the kebab-case regex ^[a-z0-9][a-z0-9-]*$. Otherwise it is derived from package identity metadata.
• A connector must declare at least one of server, hooks, commands, skills, subagents, memory, statusline, actions (or a per-platform nativeHooks / configPatch declaration) — else it throws.
• If server is present: stdio transport requires a string command; any remote transport (http/sse/ws) requires a string url.
• Every present hook entry's handler must be a function.

ResolvedConnector#

What defineConnector returns: every optional ConnectorConfig field is resolved to a concrete value. hookEvents lists the events that have a function handler (what adapters install), and telemetry is fully defaulted. commands / skills / subagents / memory are normalized to [] when none.

PlatformOverride (escape hatch)#

Per-platform overrides keep the universal core thin. Use extra to reach platform-exclusive features the core doesn't model — a thin universal core with a fat per-adapter tail.

platforms: {
  warp:   { hooks: false },                 // mcp-only host: skip hooks
  cursor: { scope: "project" },             // force project scope here
  codex:  { server: { timeoutMs: 60_000 } },// shallow-merge into ServerDef
  "claude-code": {
    extra: { /* verbatim native fields the core doesn't model */ },
  },
}

Host-config key patches (configPatch)#

extra merges into the native MCP server entry — it cannot reach a sibling top-level settings key like Claude Code's env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS. platforms.<id>.configPatch declares those as ownership-tracked patches: you name a platform + key, never a file path — the adapter owns the key→file mapping (claude-code: settings.json at the install scope).statusLine is reserved for the first-class statusline surface instead of raw configPatch.

platforms: {
  "claude-code": {
    configPatch: [
      {
        // dotted LEAF path into settings.json at the install scope
        // (segments [A-Za-z0-9_-]+ — no array indices)
        key: "env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS",
        // written ONLY if the key is absent; any conflict → skip-warn
        value: "1",
        // REQUIRED — printed in the install diff and every skip-warn
        reason: "Enable Claude Code agent teams for this connector's workflow",
        docsUrl: "https://docs.anthropic.com/en/docs/claude-code/settings",
      },
    ],
  },
}