@keemakr/operator-sdk 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keemakr/operator-sdk",
-  "version": "0.4.0",
+  "version": "0.6.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/index.ts

@@ -52,6 +52,60 @@ export interface TestResult {
   detail?: string;
 }
 
+// ─── Who a call acts for ─────────────────────────────────────────────────────
+//
+// The VERIFIED answer to "which person is behind this call", handed to an operation on
+// `ctx.actor`. Before this existed a connector could see only `connector:<keyId>` — the
+// install, not the human — so a connector that had to record who resolved an identity or
+// recorded an opt-out took the actor as a TOOL ARGUMENT, a value the model fills. Kee CRM
+// stored exactly that and had to mark it unverified (COS-207).
+//
+// Core fills this from something it authenticated — claims it SIGNED at mint time
+// (`on_behalf_of`, `actor_role`), a verified member session, or the recorded approver of a held
+// write — never from the operation's args. It is a PRINCIPAL, not an authorization: it says
+// who, never what they may do — the grant's scopes and the operation's access class decide
+// that, before your code runs.
+export interface OperationActor {
+  /** The keemakr org this call is scoped to. */
+  tenantId: string;
+  /**
+   * The human this call acts for, or null when nobody does.
+   *
+   * NULL IS MEANINGFUL, not missing: an unattended machine grant has no honest answer, and a
+   * connector that must attribute an action should refuse rather than invent one.
+   *
+   * NON-NULL DOES NOT MEAN PRESENT. A scheduled run carries the schedule's OWNER here (`via:
+   * 'schedule'`) — a real, named, accountable person who is not at the keyboard. Check `attended`
+   * for "is a person behind this call right now", never this field's truthiness.
+   *
+   * On `via: 'approval'` this is the person who RELEASED the write, never merely the one who
+   * asked for it. Where core cannot establish who approved, it is null.
+   */
+  userId: string | null;
+  /**
+   * That person's org role, read when the call was authenticated, or null when none was proven — a machine grant, a
+   * principal who is no longer a member, or a grant minted before the claim existed. Fail
+   * closed on null; never default it to a role.
+   */
+  role: 'owner' | 'admin' | 'member' | 'viewer' | null;
+  /**
+   * What the platform authenticated. `grant` is a marketplace install's capability grant,
+   * `schedule` a capability grant minted for a scheduled run (acting as the schedule's owner),
+   * `operator` a tenant member driving the Operator in the app, `mcp` a tenant member calling
+   * through the platform's MCP server (an AI client acting for them), `approval` a write a human
+   * released from an approval card.
+   *
+   * Treat this union as OPEN: switch on the values you accept and refuse the rest, so a lane
+   * added later fails closed in your connector instead of matching a default branch.
+   */
+  via: 'grant' | 'schedule' | 'operator' | 'mcp' | 'approval';
+  /**
+   * True exactly when a person is behind this call AS IT RUNS: `userId` is non-null and the lane
+   * is not `schedule`. A scheduled run names its owner but is still unattended.
+   */
+  attended: boolean;
+}
+
 // ─── Execution context ───────────────────────────────────────────────────────
 //
 // Handed to an operation (and test()) by the platform at call time. Marketplace
@@ -71,6 +125,15 @@ export interface OperationContext {
   config?: Record<string, string>;
   // Trace-correlated logger. Never log credentials or response payloads.
   log?: (msg: string) => void;
+  // WHO this call acts for, as the platform verified it — see OperationActor.
+  //
+  // Optional because not every lane has one: a connect-time probe and a built-in adapter run
+  // without a ctx at all, and a `remote` or `mcp` runtime connector is never handed the ctx core
+  // builds (it gets the same actor on its signed call grant instead, read with
+  // `verifyConnectorRequest` / `verifyMcpToolCall` from `@keemakr/agent-sdk`). An operation that
+  // needs attribution must treat an absent actor the same as an unattended one and refuse, rather
+  // than falling back to an args value. Frozen: read it, never write it.
+  actor?: Readonly<OperationActor>;
 }
 
 // Slim context for the OAuth lifecycle hooks (buildAuthUrl/exchangeCode/refresh):
@@ -100,6 +163,24 @@ export interface ConnectField {
   help?: string;
 }
 
+// Outcome of a connect-time (or on-demand) health probe. `status` is the user-
+// facing vocabulary the Hub renders: 'connected' (probe passed), 'needs_rescope'
+// (OAuth completed but the granted scopes can't run this provider's operations —
+// e.g. Google's granular-consent checkboxes were left unticked), 'no_mailbox'
+// (the account exists but has no mailbox/service behind it — a Workspace account
+// on a Microsoft-mail domain), 'unusable' (probe failed for another reason).
+export interface ProbeResult {
+  status: 'connected' | 'needs_rescope' | 'no_mailbox' | 'unusable';
+  /** One human-readable sentence for the Hub's status chip. */
+  detail?: string;
+  /** Scopes the credential actually carries, when the probe can read them. */
+  grantedScopes?: string[];
+  /** Probed account identity (e.g. the mailbox email) — becomes account_label. */
+  accountLabel?: string | null;
+  /** Extra provider facts worth persisting under meta.probe. */
+  meta?: Record<string, unknown>;
+}
+
 export interface ConnectionProvider {
   provider: string;
   displayName: string;
@@ -112,6 +193,29 @@ export interface ConnectionProvider {
   // Connect-path maturity. Omitted ⇒ 'ready'. See Maturity above.
   maturity?: Maturity;
 
+  // NOTE: a connection's scope (personal 'user' vs org-shared 'tenant') is NOT
+  // declared on the adapter. The live value is connections_registry.connection_mode
+  // (the platform-controlled overlay + rollback lever). Marketplace connectors
+  // seed it by declaring `connection_mode` in the MANIFEST (first publish only —
+  // the registry column is authoritative afterward, and reclassifying a live
+  // provider is a guarded staff console action). Built-ins still seed from
+  // registry-state's DEFAULT_USER_MODE_PROVIDERS, which stays the fail-closed
+  // fallback for unreadable registry reads.
+
+  // OAuth scopes this provider's operations actually NEED — unlike `scopes`
+  // (display-only), these are compared against the granted scope string by the
+  // connect-time probe; missing entries mark the connection 'needs_rescope'.
+  requiredScopes?: string[];
+
+  // Connect-time health probe: one cheap read (a profile fetch) that proves the
+  // credential can actually operate, run after the OAuth reports success and on
+  // demand from the Hub's "Check connection". Omitted ⇒ the connection is
+  // trusted as-is (status stays whatever the OAuth layer reported).
+  probe?(
+    cred: { accessToken: string; meta: Record<string, unknown> },
+    ctx?: OperationContext,
+  ): Promise<ProbeResult>;
+
   // 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
@@ -204,6 +308,9 @@ export interface ConnectionProvider {
 // sees it. Keep `call` pure-ish: do the request, return JSON-serializable data.
 export interface ConnectionOperation {
   description?: string;
+  // Platform-only provider primitive. It remains available to trusted internal callers that
+  // invoke the adapter directly, but is omitted from catalogs and agent/user operation surfaces.
+  internal?: boolean;
   // Access class, for grant scoping + install consent. Omitted ⇒ 'write' (the
   // most restrictive assumption: unlabeled ops require the write scope and are
   // listed as writes on the consent screen).
@@ -224,6 +331,45 @@ export interface ConnectionOperation {
   ): Promise<unknown>;
 }
 
+/** An operation's input schema: anything with `safeParse` (zod, valibot, a hand-rolled check). */
+export type OperationInputSchema = ConnectionOperation['inputSchema'];
+
+/**
+ * The `args` a `call` receives for an input schema: what the schema parses to, when it says (a
+ * Standard Schema — zod among them — declares its output type), intersected with an open record;
+ * an open record when it does not. The intersection is deliberate: known keys are typed, and any
+ * other key still reads as `unknown`, so code written against `Record<string, unknown>` keeps
+ * compiling.
+ */
+export type OperationArgs<S> = S extends { readonly '~standard': { readonly types?: infer T } }
+  ? NonNullable<T> extends { readonly output: infer O }
+    ? O extends Record<string, unknown>
+      ? O & Record<string, unknown>
+      : Record<string, unknown>
+    : Record<string, unknown>
+  : Record<string, unknown>;
+
+/** A ConnectionOperation whose `call` is typed by its own input schema (see defineProvider). */
+export interface TypedConnectionOperation<S extends OperationInputSchema> extends Omit<
+  ConnectionOperation,
+  'inputSchema' | 'call'
+> {
+  inputSchema: S;
+  call(
+    cred: { accessToken: string; meta: Record<string, unknown> },
+    args: OperationArgs<S>,
+    ctx?: OperationContext,
+  ): Promise<unknown>;
+}
+
+/** What `defineProvider` takes: a ConnectionProvider whose operations are typed by their schemas. */
+export type ProviderDefinition<Ops extends Record<string, OperationInputSchema>> = Omit<
+  ConnectionProvider,
+  'operations'
+> & {
+  operations?: { [K in keyof Ops]: TypedConnectionOperation<Ops[K]> };
+};
+
 // Machine-readable failure classes. The capability proxy maps these to HTTP
 // codes + health-machine outcomes; a provider outage must never read as a
 // broken connector, and an auth failure must revoke, not retry.
@@ -237,7 +383,16 @@ export type OperationErrorCode =
   | 'connector_error'
   | 'auth_revoked'
   | 'egress_blocked'
-  | 'rate_limited';
+  | 'rate_limited'
+  // The CONNECTOR refused the call on policy — typically an action that must be attributable
+  // reached it unattended. A denial, not a failure: it does not count against the connector's
+  // health or the provider's circuit breaker, so refusing correctly cannot degrade you.
+  | 'forbidden'
+  // The provider ANSWERED and rejected what the caller sent — bad args, an unknown record, a
+  // failed validation. The caller's fault, not the provider's: like `forbidden` it does not count
+  // against health or the circuit breaker, so one client's bad input cannot shed the connector
+  // for every tenant.
+  | 'invalid_request';
 
 // Throw from a ConnectionOperation.call to surface a typed, agent-safe failure
 // (maps to a 4xx with a clean message — never leaks the credential).
@@ -280,8 +435,20 @@ export class EgressViolationError extends OperationError {
 //   - a provider key that isn't lowercase-kebab (must match the URL segment and
 //     the connections_registry row)
 //
+// It also TYPES each operation's `call`: `args` is what the operation's own
+// inputSchema parses to (z.infer of a zod schema, or any Standard Schema's
+// output), so `args.limit` is a number when the schema says so — no casts. Known
+// keys are typed; any other key still reads as `unknown`, exactly as it did when
+// `args` was a bare Record<string, unknown>, so existing connectors that annotate
+// `args` or parse it themselves compile unchanged.
+//
 // Usage: see keemakr-core's lib/connections/providers/_template.ts.
-export function defineProvider(p: ConnectionProvider): ConnectionProvider {
+export function defineProvider<
+  Ops extends Record<string, OperationInputSchema> = Record<string, OperationInputSchema>,
+>(definition: ProviderDefinition<Ops>): ConnectionProvider {
+  // The typed operations are a narrowing of ConnectionOperation's, never a widening: each `call`
+  // accepts at least what its schema parses to, which is all the platform ever passes it.
+  const p = definition as unknown as ConnectionProvider;
   if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(p.provider)) {
     throw new Error(
       `connections: provider key '${p.provider}' must be lowercase-kebab (e.g. 'mailchimp', 'google-ads')`,

package/src/manifest.ts

@@ -26,11 +26,107 @@ const domainPattern =
 // ('contacts.search', 'weather.current'), hyphens allowed within a segment.
 const opName = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
 
+// Top-level JSON Schema keywords an operation's declared input may NOT use. Each one lets the
+// input mean something its top-level `properties` do not say — a union or intersection of shapes,
+// a negation or a condition, a pattern of names, a reference resolved elsewhere — and the declared
+// input exists precisely so that the list of argument names a caller may send can be READ off it:
+// by a reviewer, by the forwarder that refuses anything else, and by channel reach, which consents
+// to an operation only when it can see that no argument lets the caller pick the resource.
+const REFUSED_INPUT_KEYWORDS = [
+  'oneOf',
+  'anyOf',
+  'allOf',
+  'not',
+  'if',
+  'then',
+  'else',
+  'patternProperties',
+  'dependentSchemas',
+  '$ref',
+  '$dynamicRef',
+] as const;
+
+/** The most arguments one operation may declare, and the longest a declared input may be. */
+const MAX_INPUT_PROPERTIES = 100;
+const MAX_INPUT_SCHEMA_BYTES = 16_384;
+
+/**
+ * An operation's declared INPUT, as a JSON Schema object: the arguments a caller may send and
+ * nothing else. Optional, and read by core only for the lanes that have no adapter code to carry a
+ * schema of their own — remote (Lane B) and MCP connectors. There, core builds the operation's
+ * input validator from it (unknown arguments refused, required ones and primitive types checked),
+ * and channel reach can name the operation only when it is declared.
+ *
+ * Deliberately narrow: `type: 'object'`, `properties` listed, `additionalProperties: false`, and
+ * none of the keywords above at the top level. Property schemas are ordinary JSON Schema; core
+ * checks their `type` and `enum` and leaves the rest to the connector.
+ */
+export const operationInputJsonSchema = z
+  .looseObject({
+    type: z.literal('object'),
+    properties: z.record(
+      z.string().min(1).max(100),
+      z.record(z.string(), z.unknown(), 'each property must be a JSON Schema object'),
+    ),
+    required: z.array(z.string()).max(MAX_INPUT_PROPERTIES).optional(),
+    additionalProperties: z.literal(
+      false,
+      'input_schema must set additionalProperties: false — an operation that accepts arguments it does not list cannot be reviewed by its arguments',
+    ),
+    description: z.string().max(500).optional(),
+  })
+  .superRefine((schema, ctx) => {
+    for (const keyword of REFUSED_INPUT_KEYWORDS) {
+      if (keyword in schema) {
+        ctx.addIssue({
+          code: 'custom',
+          path: [keyword],
+          message: `input_schema may not use '${keyword}' at the top level — declare the arguments as plain properties`,
+        });
+      }
+    }
+    const names = Object.keys(schema.properties);
+    if (names.length > MAX_INPUT_PROPERTIES) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['properties'],
+        message: `input_schema may declare at most ${MAX_INPUT_PROPERTIES} properties`,
+      });
+    }
+    const seen = new Set<string>();
+    for (const [i, name] of (schema.required ?? []).entries()) {
+      if (!names.includes(name)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['required', i],
+          message: `required names '${name}', which is not one of its properties`,
+        });
+      }
+      if (seen.has(name)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['required', i],
+          message: `required names '${name}' twice`,
+        });
+      }
+      seen.add(name);
+    }
+    if (JSON.stringify(schema).length > MAX_INPUT_SCHEMA_BYTES) {
+      ctx.addIssue({
+        code: 'custom',
+        message: `input_schema must be at most ${MAX_INPUT_SCHEMA_BYTES} characters of JSON`,
+      });
+    }
+  });
+
 export const connectorOperationDeclaration = z.object({
   name: z.string().regex(opName, 'operation names are lowercase, dot/hyphen-scoped'),
   readWrite: z.enum(['read', 'write']),
   idempotent: z.boolean(),
   description: z.string().max(500).optional(),
+  // OPTIONAL, and it must stay optional: stored manifests of already-published versions are
+  // re-parsed with the current schema at every publish, and they do not carry it.
+  input_schema: operationInputJsonSchema.optional(),
 });
 
 export const connectorManifestSchema = z
@@ -46,6 +142,19 @@ export const connectorManifestSchema = z
     // publish gate. Optional (the adapter is authoritative); declaring it lets
     // the upload preview show it before any code runs.
     auth_kind: z.enum(['oauth2', 'api_key', 'app_password']).optional(),
+    // OWNERSHIP axis (orthogonal to `surface`): 'user' = each member connects
+    // their OWN account (one row per member, invisible to everyone else — a
+    // personal mailbox/drive/calendar); 'tenant' = one org-shared connection.
+    // Declare 'user' whenever the credential is one person's own account.
+    //
+    // Contract: this value SEEDS connections_registry.connection_mode at FIRST
+    // publish only — the platform column is authoritative afterward. Changing
+    // it in a later version raises a publish-diff warning and does NOT apply;
+    // live reclassification is a guarded staff console action (adopt/clean-cut).
+    // NEVER make this required, and never make the schema strict: stored
+    // manifests of already-published versions are re-parsed with the current
+    // schema at every publish, and only a defaulted optional field survives that.
+    connection_mode: z.enum(['tenant', 'user']).default('tenant'),
     // The operator-sdk contract version the connector targets (semver).
     sdk_version: z.string().regex(/^\d+\.\d+\.\d+$/, 'sdk_version must be exact semver'),
     // Module (relative path inside the bundle) whose named export is the
@@ -170,6 +279,7 @@ export const connectorManifestSchema = z
   });
 
 export type ConnectorOperationDeclaration = z.infer<typeof connectorOperationDeclaration>;
+export type OperationInputJsonSchema = z.infer<typeof operationInputJsonSchema>;
 export type ConnectorManifest = z.infer<typeof connectorManifestSchema>;
 
 // Parse + normalize an entry.json object. Throws ZodError on invalid input;