@onkeiki/agents 0.1.0

package/src/OpenApi.ts

@@ -0,0 +1,343 @@
+/**
+ * Builders for the compact OpenAPI documents a user connection registers with
+ * the Executor daemon.
+ *
+ * Why write a document at all, when every provider publishes one: the daemon
+ * derives the OAuth authorization request from the document's security scheme,
+ * so a published description is also a scope request. Google's Gmail
+ * description declares fourteen scopes headed by `https://mail.google.com/` —
+ * full mailbox read, send, delete and settings — which is the hardest thing to
+ * get through verification (restricted scope, brand review, annual CASA
+ * assessment) and what the consent screen would ask a stranger for over SMS.
+ * A connection that reads unread mail and sends replies needs two scopes.
+ *
+ * So the deal is: name the scopes you want and the operations you drive, and
+ * this returns the document declaring exactly that.
+ *
+ * ```ts
+ * const drive = googleOpenApiSpec({
+ *   title: 'Google Drive',
+ *   baseUrl: 'https://www.googleapis.com/drive/v3',
+ *   scopes: { 'https://www.googleapis.com/auth/drive.readonly': 'Read the user’s files' },
+ *   operations: [
+ *     { operationId: 'files.list', path: '/files', summary: 'Search the user’s files',
+ *       parameters: [{ name: 'q', in: 'query', schema: { type: 'string' } }] },
+ *   ],
+ * })
+ *
+ * mcp({ userConnections: [{ name: 'drive', spec: drive.spec, baseUrl: drive.baseUrl, ... }] })
+ * ```
+ *
+ * The checks below all catch mistakes that are invisible until a user clicks a
+ * connect link, which is the worst place to find them.
+ */
+
+export type OpenApiMethod = 'get' | 'post' | 'put' | 'patch' | 'delete'
+
+export type OpenApiParameter = {
+  readonly name: string
+  readonly in: 'path' | 'query' | 'header'
+  readonly required?: boolean
+  readonly description?: string
+  readonly schema?: unknown
+}
+
+/** A parameter declared once in `parameters` and referenced by name. */
+export type OpenApiParameterRef = { readonly ref: string }
+
+export type OpenApiOperation = {
+  /**
+   * The name the model calls the operation by, and the name a health check
+   * names (e.g. `users.messages.send`). Dotted provider-style names keep the
+   * generated tools recognizable to a model that knows the real API.
+   */
+  readonly operationId: string
+  /** Defaults to `get`. */
+  readonly method?: OpenApiMethod
+  /** Server-relative, with `{braces}` around path parameters. */
+  readonly path: string
+  readonly summary?: string
+  /**
+   * Worth writing whenever the provider does something the schema cannot say
+   * — an encoding, a 404 that is not an error, a field that must be echoed
+   * back. This is the only documentation the model gets.
+   */
+  readonly description?: string
+  readonly parameters?: ReadonlyArray<OpenApiParameter | OpenApiParameterRef>
+  readonly requestBody?: {
+    readonly required?: boolean
+    readonly description?: string
+    readonly schema: unknown
+  }
+  readonly response?: {
+    /** Success status. Defaults to `200`; a delete usually answers `204`. */
+    readonly status?: string
+    readonly description?: string
+    /** Omit for a status that has no body. */
+    readonly schema?: unknown
+  }
+}
+
+export type OAuthOpenApiSpecInput = {
+  readonly title: string
+  readonly description?: string
+  /** Document version, not the provider's API version. Defaults to `1.0`. */
+  readonly version?: string
+  /** Absolute base every path is relative to, without a trailing slash. */
+  readonly baseUrl: string
+  /** Security scheme name, e.g. `googleOAuth`. */
+  readonly schemeName: string
+  readonly authorizationUrl: string
+  readonly tokenUrl: string
+  /**
+   * Scope -> what it is for. Every one of these lands on the consent screen,
+   * so the map is the review surface: if a scope has no operation here that
+   * needs it, drop it.
+   */
+  readonly scopes: Readonly<Record<string, string>>
+  /** Shared `#/components/schemas` entries the operations `$ref`. */
+  readonly schemas?: Readonly<Record<string, unknown>>
+  /** Shared `#/components/parameters` entries, referenced by `{ ref: name }`. */
+  readonly parameters?: Readonly<Record<string, OpenApiParameter>>
+  readonly operations: ReadonlyArray<OpenApiOperation>
+}
+
+export type OAuthOpenApiSpec = {
+  /** Serialized document, ready for a user connection's `spec`. */
+  readonly spec: string
+  /** Matches the connection's `baseUrl` — the daemon calls operations there. */
+  readonly baseUrl: string
+  /** Declared scopes, in order: what the client's consent screen must allow. */
+  readonly scopes: ReadonlyArray<string>
+  /** Declared operation ids: what a `healthCheck.operation` may name. */
+  readonly operations: ReadonlyArray<string>
+}
+
+export class OpenApiSpecError extends Error {
+  override readonly name = 'OpenApiSpecError'
+}
+
+const PATH_PARAM = /\{([^}]+)\}/g
+
+function pathParameterNames(path: string): string[] {
+  return [...path.matchAll(PATH_PARAM)].map((m) => m[1]!)
+}
+
+/**
+ * An OpenAPI document with a single OAuth2 authorization-code scheme required
+ * for every operation.
+ *
+ * @throws OpenApiSpecError when the document would be accepted and then
+ * misbehave: no scopes (the daemon finds no OAuth scheme and the connection
+ * silently becomes unauthenticated), a duplicate operation id (one operation
+ * shadows the other), a path parameter nothing declares (the daemon sends
+ * `{braces}` to the provider), or a method reused on one path.
+ */
+export function oauthOpenApiSpec(input: OAuthOpenApiSpecInput): OAuthOpenApiSpec {
+  const scopes = Object.keys(input.scopes)
+  if (scopes.length === 0) {
+    throw new OpenApiSpecError(
+      `"${input.title}" declares no OAuth scopes: the daemon would find no security scheme `
+      + 'and authorize nothing.'
+    )
+  }
+  if (input.operations.length === 0) {
+    throw new OpenApiSpecError(`"${input.title}" declares no operations.`)
+  }
+  if (input.baseUrl.endsWith('/')) {
+    throw new OpenApiSpecError(
+      `baseUrl "${input.baseUrl}" ends in a slash, which doubles up with every path.`
+    )
+  }
+
+  const shared = input.parameters ?? {}
+  const paths: Record<string, Record<string, unknown>> = {}
+  const seenOperations = new Set<string>()
+
+  for (const op of input.operations) {
+    if (seenOperations.has(op.operationId)) {
+      throw new OpenApiSpecError(`Duplicate operationId "${op.operationId}".`)
+    }
+    seenOperations.add(op.operationId)
+
+    if (!op.path.startsWith('/')) {
+      throw new OpenApiSpecError(
+        `Path "${op.path}" of "${op.operationId}" has to be server-relative and start with "/".`
+      )
+    }
+
+    const parameters = (op.parameters ?? []).map((p) => {
+      if (!('ref' in p)) return p
+      if (!(p.ref in shared)) {
+        throw new OpenApiSpecError(
+          `"${op.operationId}" references parameter "${p.ref}", which is not declared.`
+        )
+      }
+      return { $ref: `#/components/parameters/${p.ref}` }
+    })
+
+    // Resolved names, so a `{userId}` answered by a shared parameter counts.
+    const declared = new Set(
+      (op.parameters ?? []).map((p) => ('ref' in p ? shared[p.ref]!.name : p.name))
+    )
+    for (const name of pathParameterNames(op.path)) {
+      if (!declared.has(name)) {
+        throw new OpenApiSpecError(
+          `"${op.operationId}" has a path parameter "{${name}}" that no parameter declares, `
+          + 'so the daemon would send the braces to the provider verbatim.'
+        )
+      }
+    }
+
+    const method = op.method ?? 'get'
+    const entry = (paths[op.path] ??= {})
+    if (method in entry) {
+      throw new OpenApiSpecError(`"${op.path}" declares ${method.toUpperCase()} twice.`)
+    }
+
+    entry[method] = {
+      operationId: op.operationId,
+      ...(op.summary ? { summary: op.summary } : {}),
+      ...(op.description ? { description: op.description } : {}),
+      ...(parameters.length > 0 ? { parameters } : {}),
+      ...(op.requestBody
+        ? {
+            requestBody: {
+              required: op.requestBody.required ?? true,
+              ...(op.requestBody.description ? { description: op.requestBody.description } : {}),
+              content: { 'application/json': { schema: op.requestBody.schema } },
+            },
+          }
+        : {}),
+      responses: {
+        [op.response?.status ?? '200']: {
+          description: op.response?.description ?? 'Success.',
+          ...(op.response?.schema
+            ? { content: { 'application/json': { schema: op.response.schema } } }
+            : {}),
+        },
+      },
+    }
+  }
+
+  const spec = {
+    openapi: '3.0.3',
+    info: {
+      title: input.title,
+      ...(input.description ? { description: input.description } : {}),
+      version: input.version ?? '1.0',
+    },
+    servers: [{ url: input.baseUrl }],
+    security: [{ [input.schemeName]: scopes }],
+    components: {
+      securitySchemes: {
+        [input.schemeName]: {
+          type: 'oauth2',
+          flows: {
+            authorizationCode: {
+              authorizationUrl: input.authorizationUrl,
+              tokenUrl: input.tokenUrl,
+              scopes: input.scopes,
+            },
+          },
+        },
+      },
+      ...(Object.keys(shared).length > 0 ? { parameters: shared } : {}),
+      ...(input.schemas && Object.keys(input.schemas).length > 0
+        ? { schemas: input.schemas }
+        : {}),
+    },
+    paths,
+  }
+
+  return {
+    spec: JSON.stringify(spec),
+    baseUrl: input.baseUrl,
+    scopes,
+    operations: [...seenOperations],
+  }
+}
+
+export const GOOGLE_AUTHORIZATION_URL = 'https://accounts.google.com/o/oauth2/v2/auth'
+export const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token'
+
+/**
+ * Scopes that cover a whole Google service rather than a use of it. Each is a
+ * restricted or sensitive scope whose consent screen reads like handing over
+ * the account, and each has a narrow sibling that does the actual job
+ * (`gmail.readonly` + `gmail.send`, `calendar.events`, `drive.file`).
+ */
+const GOOGLE_WHOLE_ACCOUNT_SCOPES = new Set([
+  'https://mail.google.com/',
+  'https://www.googleapis.com/auth/gmail.modify',
+  'https://www.googleapis.com/auth/calendar',
+  'https://www.googleapis.com/auth/drive',
+  'https://www.googleapis.com/auth/contacts',
+  'https://www.googleapis.com/auth/cloud-platform',
+])
+
+/**
+ * `oauthOpenApiSpec` with Google's endpoints and a `googleOAuth` scheme.
+ *
+ * Two Google-specific refusals, both of which otherwise surface as a dead
+ * consent screen or a scope no one meant to ask for:
+ * - `offline_access` is not a Google scope (Microsoft's is). A refresh token
+ *   comes from `access_type=offline&prompt=consent`, which the daemon appends
+ *   to the authorize URL itself.
+ * - whole-service scopes, which cost months of verification and ask a user
+ *   over SMS for their entire mailbox or calendar. Pass `allowBroadScopes`
+ *   when a connection genuinely needs one.
+ */
+export function googleOpenApiSpec(
+  input: Omit<OAuthOpenApiSpecInput, 'schemeName' | 'authorizationUrl' | 'tokenUrl'>
+    & { readonly allowBroadScopes?: boolean }
+): OAuthOpenApiSpec {
+  for (const scope of Object.keys(input.scopes)) {
+    if (scope === 'offline_access') {
+      throw new OpenApiSpecError(
+        'Google rejects "offline_access" as a scope; refresh tokens come from '
+        + 'access_type=offline, which the daemon requests for you.'
+      )
+    }
+    if (!input.allowBroadScopes && GOOGLE_WHOLE_ACCOUNT_SCOPES.has(scope)) {
+      throw new OpenApiSpecError(
+        `"${scope}" covers the whole service. Declare the narrow scopes the operations need `
+        + '(e.g. gmail.readonly + gmail.send instead of https://mail.google.com/), or pass '
+        + 'allowBroadScopes when the connection really does need it.'
+      )
+    }
+  }
+
+  return oauthOpenApiSpec({
+    ...input,
+    schemeName: 'googleOAuth',
+    authorizationUrl: GOOGLE_AUTHORIZATION_URL,
+    tokenUrl: GOOGLE_TOKEN_URL,
+  })
+}
+
+export const MICROSOFT_AUTHORIZATION_URL =
+  'https://login.microsoftonline.com/common/oauth2/v2.0/authorize'
+export const MICROSOFT_TOKEN_URL = 'https://login.microsoftonline.com/common/oauth2/v2.0/token'
+
+/**
+ * `oauthOpenApiSpec` with Microsoft identity-platform endpoints and a
+ * `microsoftOAuth` scheme. `offline_access` is added when absent: unlike
+ * Google, Microsoft only issues a refresh token when that scope is requested,
+ * and a connection without one dies at the first token expiry.
+ */
+export function microsoftOpenApiSpec(
+  input: Omit<OAuthOpenApiSpecInput, 'schemeName' | 'authorizationUrl' | 'tokenUrl'>
+): OAuthOpenApiSpec {
+  const scopes = 'offline_access' in input.scopes
+    ? input.scopes
+    : { offline_access: 'Keep access when the user is away (refresh token)', ...input.scopes }
+
+  return oauthOpenApiSpec({
+    ...input,
+    scopes,
+    schemeName: 'microsoftOAuth',
+    authorizationUrl: MICROSOFT_AUTHORIZATION_URL,
+    tokenUrl: MICROSOFT_TOKEN_URL,
+  })
+}

package/src/Plugin.ts

@@ -0,0 +1,209 @@
+import type { Effect, Layer } from 'effect'
+import type { AlertDefinition } from './Alert.js'
+import type { ToolDefinition } from './Tool.js'
+import type { AgentConfig, AgentKitConfig } from './types/config.js'
+import type { PluginMigration } from './services/PluginDb.js'
+
+// ---------------------------------------------------------------------------
+// Plugin lifecycle types
+// ---------------------------------------------------------------------------
+
+export type TurnEvent = {
+  readonly phone: string
+  readonly messages: ReadonlyArray<{ content: string; direction: 'inbound' | 'outbound' }>
+  readonly context: Record<string, unknown>
+}
+
+export type TurnResult = {
+  readonly phone: string
+  readonly response: string
+  readonly toolCalls: ReadonlyArray<{ name: string; input: unknown; output: unknown }>
+  readonly tokensUsed: { in: number; out: number }
+  readonly durationMs: number
+}
+
+export type ToolCallEvent = {
+  readonly phone: string
+  readonly toolName: string
+  readonly input: unknown
+}
+
+export type ToolCallResult = {
+  readonly phone: string
+  readonly toolName: string
+  readonly input: unknown
+  readonly output: unknown
+  readonly durationMs: number
+  readonly error?: string
+}
+
+export type RouteContext = {
+  readonly config: AgentKitConfig
+  readonly request: Request
+}
+
+export type PluginContext = {
+  readonly config: AgentKitConfig
+  readonly agentConfig: AgentConfig
+}
+
+export type SyncPayload = {
+  readonly name: string
+  readonly model: string
+  readonly tools: ReadonlyArray<{ name: string; description: string; inputSchema: unknown }>
+  readonly features: Record<string, boolean>
+  readonly extra: Record<string, unknown>
+}
+
+// ---------------------------------------------------------------------------
+// Plugin interface (Better Auth–inspired)
+// ---------------------------------------------------------------------------
+
+/**
+ * A plugin extends AgentKit with tools, hooks, routes, and layers.
+ *
+ * Modeled after Better Auth's plugin system — composable, isolated,
+ * and declarative. Each plugin owns its own config and contributes
+ * capabilities to the runtime without touching the core agent config.
+ *
+ * @example
+ * ```ts
+ * import { definePlugin } from '@onkeiki/agents'
+ *
+ * export const rateLimiter = (opts: { maxTurnsPerMinute: number }) =>
+ *   definePlugin({
+ *     id: 'rate-limiter',
+ *     hooks: {
+ *       beforeTurn: (turn) =>
+ *         Effect.gen(function* () {
+ *           // check rate, throw if exceeded
+ *           return turn
+ *         }),
+ *     },
+ *   })
+ * ```
+ */
+export type AgentKitPlugin = {
+  /** Unique plugin identifier. */
+  readonly id: string
+
+  /**
+   * Called once at boot. May return partial config overrides
+   * that are merged into the agent config (e.g. inject default tools).
+   * Similar to Better Auth's `init`.
+   */
+  readonly init?: (ctx: PluginContext) => PluginInitResult | void
+
+  /**
+   * Tools this plugin contributes to the agent.
+   */
+  readonly tools?: ReadonlyArray<ToolDefinition<any, any>>
+
+  /**
+   * Alert definitions this plugin contributes, registered with the platform
+   * alongside the agent's own `alerts` at `kit.sync()`. Additive — never
+   * overridden by the agent config.
+   */
+  readonly alerts?: ReadonlyArray<AlertDefinition>
+
+  /**
+   * HTTP routes this plugin serves (e.g. webhooks, alert execution).
+   * Keys are pathnames like "/alerts/execute".
+   * Similar to Better Auth's `endpoints`.
+   */
+  readonly routes?: Readonly<Record<string, (req: Request, ctx: RouteContext) => Promise<Response>>>
+
+  /**
+   * Lifecycle hooks around turns and tool calls.
+   * Similar to Better Auth's `hooks.before` / `hooks.after`.
+   */
+  readonly hooks?: {
+    readonly beforeTurn?: (turn: TurnEvent) => Effect.Effect<TurnEvent>
+    readonly afterTurn?: (result: TurnResult) => Effect.Effect<void>
+    readonly beforeToolCall?: (call: ToolCallEvent) => Effect.Effect<ToolCallEvent>
+    readonly afterToolCall?: (result: ToolCallResult) => Effect.Effect<ToolCallResult>
+  }
+
+  /**
+   * Global request interceptor. Return a Response to short-circuit,
+   * a modified Request to rewrite, or void to pass through.
+   * Similar to Better Auth's `onRequest`.
+   */
+  readonly onRequest?: (req: Request) => Effect.Effect<Request | Response | void>
+
+  /**
+   * Global response interceptor.
+   * Similar to Better Auth's `onResponse`.
+   */
+  readonly onResponse?: (res: Response) => Effect.Effect<Response>
+
+  /**
+   * Additional Effect layers to provide to the runtime.
+   */
+  readonly layers?: ReadonlyArray<Layer.Layer<any>>
+
+  /**
+   * Hook into the platform sync. Receives the current payload
+   * and returns a modified version. Used by plugins that need
+   * to push their own state (alerts, secrets, schemas, etc.)
+   *
+   * `name`, `model`, `features`, and `extra` from the returned payload are
+   * sent to the platform. The `tools` list is read-only context — the sync
+   * request always carries the fully-bundled tool definitions.
+   */
+  readonly onSync?: (payload: SyncPayload) => SyncPayload
+
+  /**
+   * Middleware that runs on every request before route matching.
+   * Return void to pass through, or a Response to short-circuit.
+   */
+  readonly middleware?: ReadonlyArray<{
+    readonly path: string
+    readonly handler: (req: Request, ctx: RouteContext) => Effect.Effect<Response | void>
+  }>
+
+  /**
+   * Database migrations owned by this plugin. Declared statically so they
+   * can be collected before storage initialization. Run once by the storage
+   * adapter at boot, tracked in `smskit_plugin_migrations`. Tables are
+   * NEVER dropped when the plugin is disabled — data is preserved.
+   */
+  readonly migrations?: ReadonlyArray<PluginMigration>
+}
+
+export type PluginInitResult = {
+  readonly config?: Partial<AgentConfig>
+  readonly extra?: Record<string, unknown>
+}
+
+// ---------------------------------------------------------------------------
+// Legacy Plugin type (deprecated — use AgentKitPlugin)
+// ---------------------------------------------------------------------------
+
+/**
+ * @deprecated Use `AgentKitPlugin` instead. This type is kept for backwards
+ * compatibility and will be removed in a future release.
+ */
+export type Plugin = {
+  readonly name: string
+  readonly tools?: ReadonlyArray<ToolDefinition<any, any>>
+  readonly onTurn?: (turn: TurnEvent) => Effect.Effect<TurnEvent>
+  readonly afterTurn?: (result: TurnResult) => Effect.Effect<void>
+  readonly layers?: ReadonlyArray<Layer.Layer<any>>
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Define a type-safe AgentKit plugin.
+ */
+export function definePlugin(plugin: AgentKitPlugin): AgentKitPlugin {
+  return plugin
+}
+
+/**
+ * @deprecated Use {@link AgentKitPlugin} instead. Kept for backwards compatibility.
+ */
+export type SmsKitPlugin = AgentKitPlugin