@keemakr/operator-sdk 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keemakr/operator-sdk",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "The keemakr connector contract: defineProvider + ConnectionProvider/ConnectionOperation types + OperationContext (governed fetch) + the connector manifest schema, shared by keemakr-core's built-in adapters and external connector repos. One shape, two consumers.",
   "type": "module",
   "license": "MIT",

package/src/conformance/index.ts

@@ -68,6 +68,15 @@ export async function runConformance(
     !manifest.auth_kind || provider.authKind === manifest.auth_kind,
     `code '${provider.authKind}' vs manifest '${manifest.auth_kind ?? '—'}'`,
   );
+  // The credential alias is a reviewed dependency: when either side declares
+  // it, both must, and they must agree (a code-only alias would ride a
+  // connection reviewers never saw).
+  add(
+    'credential-alias',
+    'credential alias matches the manifest (when either declares it)',
+    (provider.credentialProvider ?? null) === (manifest.credential_provider ?? null),
+    `code '${provider.credentialProvider ?? '—'}' vs manifest '${manifest.credential_provider ?? '—'}'`,
+  );
 
   // 6 — code may not claim MORE network than the reviewed manifest.
   const undeclared = (provider.allowedDomains ?? []).filter(

package/src/index.ts

@@ -22,6 +22,23 @@ export type AuthKind = 'oauth2' | 'api_key' | 'app_password';
 // to 'ready'), so legacy adapters stay connectable until told otherwise.
 export type Maturity = 'ready' | 'coming_soon';
 
+// Who a connector is FOR — the audience axis the end-user client uses to decide
+// whether to surface it, and how. Classify EVERY connector (defineProvider will
+// enforce this) so the client catalog never conflates the three kinds:
+//   'user-account' → the tenant's OWN account; connect/disconnect is the point.
+//                    Shown in the end-user connections hub (Gmail, Slack, Stripe,
+//                    HubSpot, social channels).
+//   'agent-tool'   → infrastructure an AGENT uses to do a task, not a personal
+//                    account. The platform may hold a shared key; a tenant may
+//                    override with their own. NEVER a standalone hub card — it
+//                    surfaces only via the install card of an agent that declares
+//                    it (Apollo, Hunter, Clearbit — enrichment/analytics/scraping).
+//   'internal'     → platform plumbing, or a dormant connector with no operations
+//                    and no consumer. Never shown to end users (e.g. agent-sessions;
+//                    op-less stubs — also keep those at maturity:'coming_soon').
+// See docs/architecture/05 + 15 and the AGENTS.md "Connectors" convention.
+export type ConnectorSurface = 'user-account' | 'agent-tool' | 'internal';
+
 export interface TokenSet {
   accessToken: string;
   refreshToken?: string | null;
@@ -95,6 +112,12 @@ export interface ConnectionProvider {
   // Connect-path maturity. Omitted ⇒ 'ready'. See Maturity above.
   maturity?: Maturity;
 
+  // Audience classification — see ConnectorSurface. Drives whether the end-user
+  // client surfaces this connector and how. Optional in the type for now so
+  // existing/external adapters compile through the SDK bump; defineProvider warns
+  // when omitted and this tightens to required once every built-in declares it.
+  surface?: ConnectorSurface;
+
   // Egress allowlist: the ONLY hosts this connector's operations/test may reach
   // through ctx.fetch. Bare hostname for an exact match ('api.acme.com') or a
   // wildcard for subdomains ('*.acme.com' — does NOT match the apex; list it
@@ -107,6 +130,17 @@ export interface ConnectionProvider {
   // omit it (first-party).
   publisher?: string;
 
+  // Credential alias — the agent-tool chain's "one key opens many doors" seam.
+  // A connector that fronts one facet of a wider platform (an Apify actor, a
+  // Composio toolkit) declares the provider whose TENANT CONNECTION it rides:
+  // when a tenant has no row for THIS provider, getConnection falls back to the
+  // alias provider's row (tenant connects 'apify' once; every actor connector
+  // works). A tenant-pasted key for this provider still wins — the alias is the
+  // fallback, not the override. Refresh semantics follow the ALIAS provider's
+  // adapter. One hop only; the alias must name a concrete provider, never
+  // another aliased one.
+  credentialProvider?: string;
+
   // Inline connect-form spec for api_key / app_password shapes. Omitted by pure
   // oauth2 adapters (they render a Connect button instead). For a dual-mode
   // provider (WordPress), this describes the NON-oauth fallback form; the UI
@@ -267,6 +301,16 @@ export function defineProvider(p: ConnectionProvider): ConnectionProvider {
   if (typeof p.test !== 'function') {
     throw new Error(`connections: provider '${p.provider}' must implement test()`);
   }
+  if (!p.surface) {
+    // Nudge, not throw (yet): the built-ins all declare `surface`, but external/marketplace
+    // connectors (separate repos) haven't adopted it. Tightening to a hard throw + a required
+    // field is gated on adding `surface` to the connector manifest schema.
+    console.warn(
+      `connections: provider '${p.provider}' does not declare surface ` +
+        `('user-account' | 'agent-tool' | 'internal') — classify it so the client catalog knows ` +
+        `whether and how to show it. See the AGENTS.md "Connectors" convention.`,
+    );
+  }
   if (p.operations && Object.keys(p.operations).length > 0 && !p.allowedDomains?.length) {
     // Warn, don't throw: built-ins are grandfathered on ambient fetch. The
     // marketplace publish gate REQUIRES allowed_domains in the manifest, so

package/src/manifest.ts

@@ -59,9 +59,24 @@ export const connectorManifestSchema = z
     // tenant's credential — which is why remote connectors require explicit
     // per-connection consent before any call.
     runtime_url: z.string().url().max(500).optional(),
+    // Lane 'mcp': the author points at a remote Model Context Protocol server
+    // instead of writing operation bodies. Each declared operation forwards to
+    // that server's `tools/call` over Streamable HTTP, driven through the same
+    // governed fetch as Lane B. `url` is https-only and author-declared (never
+    // tenant-supplied); `auth` is 'injected' only in v1 — core vaults the
+    // tenant's credential and rides it on a transport header, never in the tool
+    // args. ('server_managed', where the MCP server holds its own upstream
+    // OAuth, is reserved for a later, higher-tier release.)
+    mcp: z
+      .object({
+        url: z.string().url().max(500),
+        auth: z.enum(['injected']),
+      })
+      .optional(),
     // Remote connectors have no adapter code in core, so their connect form is
     // declared HERE (vendored connectors keep connectFields in code — the
-    // adapter stays the single source of truth for Lane A).
+    // adapter stays the single source of truth for Lane A). MCP connectors are
+    // the same: no adapter code, so the form lives here too.
     connect_fields: z
       .array(
         z.object({
@@ -77,6 +92,14 @@ export const connectorManifestSchema = z
     allowed_domains: z
       .array(z.string().regex(domainPattern, 'each entry is a bare host or *.host, optional :port'))
       .min(1, 'declare at least one allowed domain'),
+    // Credential alias (see ConnectionProvider.credentialProvider): the provider
+    // whose tenant connection this connector rides when the tenant has not
+    // connected THIS provider directly. Declared here so reviewers see the
+    // dependency; the adapter's copy is authoritative at runtime.
+    credential_provider: z
+      .string()
+      .regex(kebab, 'credential_provider must be a lowercase-kebab provider key')
+      .optional(),
     // Connector-level config keys the platform must supply (resolved from the
     // encrypted config store — values are set by staff at publish, never bundled).
     env: z
@@ -91,10 +114,19 @@ export const connectorManifestSchema = z
     changelog: z.string().max(5000).optional(),
   })
   .superRefine((m, ctx) => {
-    if (!m.entrypoint && !m.runtime_url) {
+    const lanes = [m.entrypoint, m.runtime_url, m.mcp].filter((v) => v != null).length;
+    if (lanes === 0) {
       ctx.addIssue({
         code: 'custom',
-        message: 'declare an entrypoint (vendored, Lane A) or a runtime_url (remote, Lane B)',
+        message:
+          'declare exactly one lane: an entrypoint (vendored, Lane A), a runtime_url (remote, Lane B), or an mcp endpoint (remote MCP)',
+      });
+    }
+    if (lanes > 1) {
+      ctx.addIssue({
+        code: 'custom',
+        message:
+          'declare exactly one lane — entrypoint, runtime_url, and mcp are mutually exclusive',
       });
     }
     if (m.runtime_url && !m.runtime_url.startsWith('https://')) {
@@ -116,6 +148,25 @@ export const connectorManifestSchema = z
           'remote connectors must declare connect_fields (there is no adapter code to own the form)',
       });
     }
+    if (m.mcp && !m.mcp.url.startsWith('https://')) {
+      ctx.addIssue({ code: 'custom', path: ['mcp', 'url'], message: 'mcp.url must be https' });
+    }
+    if (m.mcp && m.auth_kind === 'oauth2') {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['auth_kind'],
+        message:
+          'mcp connectors are api_key/app_password only — core injects the vaulted credential on a transport header, it does not broker an author-owned OAuth dance',
+      });
+    }
+    if (m.mcp && (!m.connect_fields || m.connect_fields.length === 0)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['connect_fields'],
+        message:
+          'mcp connectors must declare connect_fields (there is no adapter code to own the form)',
+      });
+    }
   });
 
 export type ConnectorOperationDeclaration = z.infer<typeof connectorOperationDeclaration>;