@keemakr/operator-sdk 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keemakr/operator-sdk",
-  "version": "0.5.0",
+  "version": "0.7.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):
@@ -255,6 +318,13 @@ export interface ConnectionOperation {
   // Safe-to-retry marker. Omitted ⇒ false. The platform NEVER auto-retries a
   // non-idempotent operation; callers (agents) read this to know what is safe.
   idempotent?: boolean;
+  // The fields of the RESULT that are files a person should see: generated
+  // images, synthesized audio. `path` names them with dots and `[]` for every
+  // item of a list, e.g. `images[].url` or `audio.url`. When the Operator calls
+  // the operation, each URL becomes an image or audio card in the chat, and
+  // core keeps its own copy, so the card still works after the provider's link
+  // expires. Omitted ⇒ the result holds no media.
+  media?: ReadonlyArray<{ kind: 'image' | 'audio'; path: string }>;
   // A Standard Schema (zod/valibot/…) validating the agent-supplied args. Typed
   // loosely here so the connector contract doesn't hard-depend on zod; adapters
   // pass a zod schema and the route validates with `.parse`/`.safeParse`.
@@ -268,6 +338,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.
@@ -281,7 +390,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).
@@ -324,8 +442,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
@@ -183,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;