@pikku/core 0.12.107 → 0.12.111

package/src/wirings/mcp/mcp-runner.ts

@@ -1,330 +0,0 @@
-import type { PikkuRawWire } from '../../types/core.types.js'
-import type { PikkuHTTP } from '../http/http.types.js'
-import type {
-  CoreMCPResource,
-  CoreMCPPrompt,
-  JsonRpcRequest,
-  JsonRpcResponse,
-  JsonRpcErrorResponse,
-  PikkuMCP,
-} from './mcp.types.js'
-import type {
-  CorePikkuFunctionConfig,
-  CorePikkuFunctionSessionless,
-} from '../../function/functions.types.js'
-import { getErrorResponse } from '../../errors/error-handler.js'
-import { isProduction } from '../../env.js'
-import {
-  pikkuState,
-  getSingletonServices,
-  getCreateWireServices,
-} from '../../pikku-state.js'
-import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
-import { resolveNamespace } from '../rpc/rpc-runner.js'
-import { BadRequestError, NotFoundError } from '../../errors/errors.js'
-import {
-  PikkuSessionService,
-  createMiddlewareSessionWireProps,
-} from '../../services/user-session-service.js'
-export class MCPError extends Error {
-  constructor(public readonly error: JsonRpcErrorResponse) {
-    super(error?.message || 'MCP Error')
-    this.name = 'MCPError'
-    this.stack = new Error().stack
-  }
-}
-
-export type RunMCPEndpointParams<Tools extends string = any> = {
-  mcp?: PikkuMCP<Tools>
-  /**
-   * The HTTP request the MCP call arrived on, when it arrived over HTTP.
-   *
-   * Auth middleware reads the session off `wire.http.request` — every
-   * implementation opens with `if (!http?.request) return` — so without this an
-   * MCP call reaches the function unauthenticated no matter what middleware the
-   * app has registered, and a tool fronting a session-requiring function can
-   * only ever answer 'Authentication required'.
-   *
-   * Left undefined for transports that have no request to offer, such as stdio.
-   * Those remain anonymous, which is a property of the transport rather than a
-   * default chosen here.
-   */
-  http?: PikkuHTTP
-  /** Defaults to enabled outside production. */
-  exposeErrors?: boolean
-}
-
-export const wireMCPResource = <
-  PikkuFunctionConfig extends CorePikkuFunctionConfig<
-    CorePikkuFunctionSessionless<any, any>
-  > = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, any>>,
->(
-  mcpResource: CoreMCPResource<PikkuFunctionConfig>
-) => {
-  const resourcesMeta = pikkuState(null, 'mcp', 'resourcesMeta')
-  const mcpResourceMeta = resourcesMeta[mcpResource.uri]
-  if (!mcpResourceMeta) {
-    console.warn(
-      `[pikku] Skipping MCP resource '${mcpResource.uri}' — metadata not found. Consider moving this wiring to its own file.`
-    )
-    return
-  }
-  addFunction(mcpResourceMeta.pikkuFuncId, mcpResource.func)
-  const resources = pikkuState(null, 'mcp', 'resources')
-  if (resources.has(mcpResource.uri)) {
-    throw new Error(`MCP resource already exists: ${mcpResource.uri}`)
-  }
-  resources.set(mcpResource.uri, mcpResource)
-}
-
-export const wireMCPPrompt = <
-  PikkuFunctionConfig extends CorePikkuFunctionConfig<
-    CorePikkuFunctionSessionless<any, any>
-  > = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, any>>,
->(
-  mcpPrompt: CoreMCPPrompt<PikkuFunctionConfig>
-) => {
-  const promptsMeta = pikkuState(null, 'mcp', 'promptsMeta')
-  const mcpPromptMeta = promptsMeta[mcpPrompt.name]
-  if (!mcpPromptMeta) {
-    console.warn(
-      `[pikku] Skipping MCP prompt '${mcpPrompt.name}' — metadata not found. Consider moving this wiring to its own file.`
-    )
-    return
-  }
-  addFunction(mcpPromptMeta.pikkuFuncId, mcpPrompt.func)
-  const prompts = pikkuState(null, 'mcp', 'prompts')
-  if (prompts.has(mcpPrompt.name)) {
-    throw new Error(`MCP prompt already exists: ${mcpPrompt.name}`)
-  }
-  prompts.set(mcpPrompt.name, mcpPrompt)
-}
-
-export async function runMCPResource(
-  request: JsonRpcRequest,
-  params: RunMCPEndpointParams,
-  uri: string
-) {
-  let endpoint: CoreMCPResource | undefined
-  let pikkuFuncId: string | undefined
-  let extractedParams: Record<string, string> = {}
-
-  const metas = pikkuState(null, 'mcp', 'resourcesMeta')
-  const endpoints = pikkuState(null, 'mcp', 'resources')
-
-  // The key the resource's meta (and its middleware) is stored under. For a
-  // templated resource this is the template, not the concrete request URI — so
-  // it must be carried forward, or the meta lookup downstream misses and the
-  // resource's declared middleware (including auth) is silently skipped.
-  let metaKey = uri
-
-  if (endpoints.has(uri)) {
-    endpoint = endpoints.get(uri)
-    pikkuFuncId = metas[uri]?.pikkuFuncId
-  } else {
-    for (const [uriTemplate, value] of endpoints.entries()) {
-      const paramNames = Array.from(
-        uriTemplate.matchAll(/\{([^}]+)\}/g),
-        (m) => m[1]
-      )
-
-      const regexPattern = uriTemplate.replace(/\{[^}]+\}/g, '([^/]+)')
-      const regex = new RegExp(`^${regexPattern}$`)
-      const match = uri.match(regex)
-
-      if (match) {
-        endpoint = value
-        metaKey = uriTemplate
-        pikkuFuncId = metas[uriTemplate]?.pikkuFuncId
-
-        for (let i = 0; i < paramNames.length; i++) {
-          extractedParams[paramNames[i]!] = match[i + 1]! // match[0] is the full match
-        }
-        break
-      }
-    }
-  }
-
-  return await runMCPPikkuFunc(
-    {
-      ...request,
-      params: { ...request.params, ...extractedParams },
-    },
-    'resource',
-    uri,
-    endpoint,
-    pikkuFuncId,
-    { ...params, mcp: { ...params.mcp, uri } } as RunMCPEndpointParams<
-      keyof CoreMCPResource
-    >,
-    metaKey
-  )
-}
-
-export async function runMCPTool(
-  request: JsonRpcRequest,
-  params: RunMCPEndpointParams,
-  name: string
-) {
-  const meta = pikkuState(null, 'mcp', 'toolsMeta')[name]
-  return await runMCPPikkuFunc(
-    request,
-    'tool',
-    name,
-    undefined,
-    meta?.pikkuFuncId,
-    params
-  )
-}
-
-export async function runMCPPrompt(
-  request: JsonRpcRequest,
-  params: RunMCPEndpointParams,
-  name: string
-) {
-  const endpoint = pikkuState(null, 'mcp', 'prompts').get(name)
-  const meta = pikkuState(null, 'mcp', 'promptsMeta')[name]
-  return await runMCPPikkuFunc(
-    request,
-    'prompt',
-    name,
-    endpoint,
-    meta?.pikkuFuncId,
-    params
-  )
-}
-
-async function runMCPPikkuFunc(
-  request: JsonRpcRequest,
-  type: 'resource' | 'tool' | 'prompt',
-  name: string,
-  mcp: CoreMCPResource | CoreMCPPrompt | undefined,
-  pikkuFuncId: string | undefined,
-  { mcp: mcpWire, http, exposeErrors = !isProduction() }: RunMCPEndpointParams,
-  // The key the endpoint's meta is stored under. Differs from `name` only for a
-  // templated resource, where `name` is the concrete URI and the meta lives
-  // under the template. Defaults to `name` for tools and prompts.
-  metaKey: string = name
-): Promise<JsonRpcResponse> {
-  const singletonServices = getSingletonServices()
-  const createWireServices = getCreateWireServices()
-
-  try {
-    if (request.jsonrpc !== '2.0') {
-      throw new BadRequestError(
-        'Invalid JSON-RPC version, only supoorted version is 2.0'
-      )
-    }
-
-    if (mcp === undefined && type !== 'tool') {
-      throw new NotFoundError(
-        `MCP '${type}' registration not found for '${name}'`
-      )
-    }
-
-    if (!pikkuFuncId) {
-      throw new NotFoundError(
-        `MCP '${type}' PikkuFunction Mapping not found for '${name}'`
-      )
-    }
-
-    singletonServices.logger.debug(`Running MCP ${type}: ${name}`)
-
-    const mcpSessionService = new PikkuSessionService(
-      singletonServices.sessionStore
-    )
-    const wire: PikkuRawWire = {
-      mcp: mcpWire,
-      // Only when the transport supplied one. Setting `http: undefined`
-      // explicitly would be the same to a reader and different to a spread.
-      ...(http ? { http } : {}),
-      ...createMiddlewareSessionWireProps(mcpSessionService),
-    }
-
-    let meta: any
-    if (type === 'resource') {
-      meta = pikkuState(null, 'mcp', 'resourcesMeta')[metaKey]
-    } else if (type === 'tool') {
-      meta = pikkuState(null, 'mcp', 'toolsMeta')[metaKey]
-    } else if (type === 'prompt') {
-      meta = pikkuState(null, 'mcp', 'promptsMeta')[metaKey]
-    }
-
-    let resolvedFuncName = pikkuFuncId
-    let resolvedPackageName: string | null = meta?.packageName ?? null
-    if (pikkuFuncId.includes(':')) {
-      const resolved = resolveNamespace(pikkuFuncId)
-      if (resolved) {
-        resolvedFuncName = resolved.function
-        resolvedPackageName = resolved.package
-      }
-    }
-
-    let result = await runPikkuFunc(
-      'mcp',
-      `${type}:${name}`,
-      resolvedFuncName,
-      {
-        singletonServices,
-        createWireServices,
-        data: () => request.params,
-        inheritedMiddleware: meta?.middleware,
-        wireMiddleware: mcp?.middleware,
-        tags: mcp?.tags,
-        wire,
-        sessionService: mcpSessionService,
-        packageName: resolvedPackageName,
-      }
-    )
-
-    if (type === 'tool' && meta?.outputSchema !== 'MCPToolResponse') {
-      result = [{ type: 'text', text: JSON.stringify(result) }]
-    }
-
-    return {
-      id: request.id,
-      result,
-    }
-  } catch (e: any) {
-    singletonServices.logger.error(
-      `Error running MCP ${type} '${name}':`,
-      e.constructor
-    )
-    const errorResponse = getErrorResponse(e)
-    if (errorResponse?.mcpCode) {
-      throw new MCPError({
-        id: request.id,
-        code: errorResponse.mcpCode,
-        message: errorResponse.message,
-      })
-    } else {
-      if (errorResponse) {
-        singletonServices.logger.warn(
-          `Got error without a mapping: ${errorResponse.message}`
-        )
-      }
-      throw new MCPError({
-        id: request.id,
-        code: -32603,
-        message: 'Internal error',
-        // knowledge: decisions/security/mcp-internal-error-details-are-double-gated-on-production.md
-        data:
-          exposeErrors && !isProduction() && e instanceof Error
-            ? { message: e.message, stack: e.stack }
-            : undefined,
-      })
-    }
-  }
-}
-
-export const getMCPResourcesMeta = () => {
-  return pikkuState(null, 'mcp', 'resourcesMeta')
-}
-
-export const getMCPToolsMeta = () => {
-  return pikkuState(null, 'mcp', 'toolsMeta')
-}
-
-export const getMCPPromptsMeta = () => {
-  return pikkuState(null, 'mcp', 'promptsMeta')
-}

package/src/wirings/mcp/mcp.types.ts

@@ -1,199 +0,0 @@
-import type {
-  CorePikkuFunctionConfig,
-  CorePikkuFunctionSessionless,
-  CorePikkuPermission,
-} from '../../function/functions.types.js'
-import type {
-  CorePikkuMiddleware,
-  MiddlewareMetadata,
-} from '../../middleware/middleware.types.js'
-/** "user/{userId}/post/{postId}" => "userId" | "postId" */
-type ExtractMCPURIParams<S extends string> =
-  S extends `${string}{${infer Param}}/${infer Rest}`
-    ? Param | ExtractMCPURIParams<Rest>
-    : S extends `${string}{${infer Param}}`
-      ? Param
-      : never
-
-/** Resolves to a tuple of error strings, not `never`, so the mismatch surfaces in the type error. */
-export type AssertMCPResourceURIParams<In, URI extends string> =
-  ExtractMCPURIParams<URI> extends keyof In
-    ? unknown
-    : [
-        'Error: MCP Resource URI parameters',
-        ExtractMCPURIParams<URI>,
-        'not in input type',
-        keyof In,
-      ]
-
-export type PikkuMCP<Tools extends string = any> = {
-  uri?: string
-  sendResourceUpdated: (uri: string) => void
-  enableResources: (resources: Record<string, boolean>) => Promise<boolean>
-  enablePrompts: (prompts: Record<string, boolean>) => Promise<boolean>
-  enableTools: (tools: Record<Tools, boolean>) => Promise<boolean>
-}
-
-export type MCPResourceMeta = Record<
-  string,
-  Omit<CoreMCPResource, 'func' | 'middleware'> & {
-    pikkuFuncId: string
-    inputSchema: string | null
-    outputSchema: string | null
-    middleware?: MiddlewareMetadata[] // tag + explicit, already merged
-  }
->
-
-export type MCPToolMeta = Record<
-  string,
-  Omit<CoreMCPTool, 'func' | 'middleware'> & {
-    pikkuFuncId: string
-    inputSchema: string | null
-    outputSchema: string | null
-    middleware?: MiddlewareMetadata[] // tag + explicit, already merged
-  }
->
-
-export type MCPPromptMeta = Record<
-  string,
-  Omit<CoreMCPPrompt, 'func' | 'middleware'> & {
-    pikkuFuncId: string
-    inputSchema: string | null
-    outputSchema: string | null
-    arguments: Array<{
-      name: string
-      description: string
-      required: boolean
-    }>
-    middleware?: MiddlewareMetadata[] // tag + explicit, already merged
-  }
->
-
-export type CoreMCPResource<
-  PikkuFunctionConfig = CorePikkuFunctionConfig<
-    CorePikkuFunctionSessionless<any, any>
-  >,
-  PikkuPermission = CorePikkuPermission<any, any>,
-  PikkuMiddleware = CorePikkuMiddleware<any>,
-> = {
-  /** How the client addresses this resource. `{name}` marks a parameter, and every parameter must be a key of the function's input schema. */
-  uri: string
-  /** The name a human sees in a client's resource list. */
-  title: string
-  /** What the resource holds, written for the model deciding whether to read it. */
-  description: string
-  /** A one-line description for listings, where the full `description` is too long. */
-  summary?: string
-  /** Names of error classes this may throw, so the client is told which failures are its own fault. */
-  errors?: string[]
-  /** The media type of what the function returns, so the client knows whether it is text, JSON or an image. */
-  mimeType?: string
-  /** Size in bytes, where it is known ahead of the read. A client uses it to decide whether to fetch at all. */
-  size?: number
-  /** Whether the function returns the content in chunks rather than at once. */
-  streaming?: boolean
-  /** The function to run. It is sessionless: an MCP client is not a logged-in user. */
-  func: PikkuFunctionConfig
-  /** Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
-  tags?: string[]
-  /** Wraps every call: tracing, rate limiting, whatever the transport does not do. */
-  middleware?: PikkuMiddleware[]
-}
-
-export type CoreMCPTool<
-  PikkuFunctionConfig = CorePikkuFunctionConfig<
-    CorePikkuFunctionSessionless<any, any>
-  >,
-  PikkuPermission = CorePikkuPermission<any, any>,
-  PikkuMiddleware = CorePikkuMiddleware<any>,
-> = {
-  /** How the model calls this tool. It is the tool's identity, so renaming it breaks any client that already knows it. */
-  name: string
-  /** The name a human sees, where the calling `name` is not readable. */
-  title?: string
-  /** What the tool does and when to reach for it. This is what the model decides on, so it earns more care than the rest of this object. */
-  description?: string
-  /** A one-line description for listings, where the full `description` is too long. */
-  summary?: string
-  /** Names of error classes this may throw, so the client is told which failures are its own fault. */
-  errors?: string[]
-  /** The function to run. It is sessionless: an MCP client is not a logged-in user. */
-  func: PikkuFunctionConfig
-  /** Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
-  tags?: string[]
-  /** Whether the function returns its result in chunks rather than at once. */
-  streaming?: boolean
-  /** Wraps every call: tracing, rate limiting, whatever the transport does not do. */
-  middleware?: PikkuMiddleware[]
-}
-
-export type CoreMCPPrompt<
-  PikkuFunctionConfig = CorePikkuFunctionConfig<
-    CorePikkuFunctionSessionless<any, MCPPromptResponse>
-  >,
-  PikkuPermission = CorePikkuPermission<any, any>,
-  PikkuMiddleware = CorePikkuMiddleware<any>,
-> = {
-  /** How the client asks for this prompt. */
-  name: string
-  /** What the prompt is for, written for the human picking it out of a list. */
-  description: string
-  /** A one-line description for listings, where the full `description` is too long. */
-  summary?: string
-  /** Names of error classes this may throw, so the client is told which failures are its own fault. */
-  errors?: string[]
-  /** The function to run. It is sessionless: an MCP client is not a logged-in user. */
-  func: PikkuFunctionConfig
-  /** Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
-  tags?: string[]
-  /** Wraps every call: tracing, rate limiting, whatever the transport does not do. */
-  middleware?: PikkuMiddleware[]
-}
-
-export type JsonRpcRequest = {
-  jsonrpc: string
-  id?: string | number | null
-  params?: any
-}
-
-export type JsonRpcResponse = {
-  id?: string | number | null
-  result?: any
-}
-
-export type JsonRpcErrorResponse = {
-  id?: string | number | null
-  code: number
-  message: string
-  data?: any
-}
-
-export type MCPPromptMessage = {
-  role: 'user' | 'assistant' | 'system'
-  content: {
-    type: 'text' | 'image'
-    text: string
-    data?: string
-  }
-}
-
-export type MCPPromptResponse = MCPPromptMessage[]
-
-export type MCPResourceMessage = {
-  uri: string
-  text: string
-}
-
-export type MCPResourceResponse = MCPResourceMessage[]
-
-export type MCPToolMessage =
-  | {
-      type: 'text'
-      text: string
-    }
-  | {
-      type: 'image'
-      data: string // base64
-    }
-
-export type MCPToolResponse = MCPToolMessage[]

package/src/wirings/node/index.ts

@@ -1,2 +0,0 @@
-export type { CoreNodeConfig, NodeType } from './node.types.js'
-export type { NodesMeta } from './node.types.js'

package/src/wirings/node/node.types.ts

@@ -1,23 +0,0 @@
-export type NodeType = 'trigger' | 'action' | 'end'
-
-export type CoreNodeConfig = {
-  displayName: string
-  category: string
-  type: NodeType
-  errorOutput?: boolean
-}
-
-export type NodeMeta = {
-  name: string
-  displayName: string
-  category: string
-  type: NodeType
-  rpc: string
-  description?: string
-  errorOutput: boolean
-  inputSchemaName: string | null
-  outputSchemaName: string | null
-  tags?: string[]
-}
-
-export type NodesMeta = Record<string, NodeMeta>

package/src/wirings/oauth2/index.ts

@@ -1 +0,0 @@
-export type { OAuth2AppCredential, OAuth2Token } from './oauth2.types.js'

package/src/wirings/oauth2/oauth2.types.ts

@@ -1,12 +0,0 @@
-export type OAuth2AppCredential = {
-  clientId: string
-  clientSecret?: string // Optional for PKCE flows
-}
-
-export type OAuth2Token = {
-  accessToken: string
-  refreshToken?: string
-  expiresAt?: number // Unix timestamp
-  tokenType: string
-  scope?: string
-}

package/src/wirings/persona/define-personas.ts

@@ -1,33 +0,0 @@
-import type { CorePersonas } from './persona.types.js'
-
-/**
- * No-op function for declaring personas.
- * This exists purely for TypeScript type checking and will be tree-shaken.
- * The CLI extracts metadata via AST parsing and generates a `PersonaId` union
- * and a `personas.gen.json` the console and `pikku persona run` read off disk —
- * describing, listing or running one never has to load the app.
- *
- * `definePersonas` rather than `defineVirtualUsers` because declaring is not
- * running: a persona that exists only to be acted upon (the account an admin
- * bans, the colleague a document is shared with) is seeded and never run.
- *
- * Exactly one `definePersonas(...)` is allowed per codebase, so there is one
- * place to read the cast from and one place to add to. A second call — even in
- * the same file — fails the build.
- *
- * @example
- * ```typescript
- * definePersonas({
- *   susan: {
- *     name: 'Susan',
- *     jobTitle: 'Buys for a small café',
- *     roles: ['buyer'],
- *     personality: 'Hunts cheap deals. Tries three coupon codes before giving up.',
- *     goals: ['Get the weekly order in under five minutes'],
- *     disposition: 'careless',
- *     account: {},
- *   },
- * })
- * ```
- */
-export const definePersonas = (_config: CorePersonas): void => {}

package/src/wirings/persona/index.ts

@@ -1,75 +0,0 @@
-export { definePersonas } from './define-personas.js'
-export {
-  isRunnablePersona,
-  roleMismatchMessage,
-  runnablePersonas,
-  validateAndBuildPersonasMeta,
-  verifyPersonaRoles,
-} from './validate-personas.js'
-export type { RoleVerification } from './validate-personas.js'
-export {
-  personaEnvironmentErrors,
-  personaEnvironmentRefusal,
-} from './persona-environments.js'
-export type {
-  PersonaEnvironment,
-  PersonaEnvironmentSubject,
-} from './persona-environments.js'
-export { personaEmail, personaEmails } from './persona-email.js'
-export {
-  APP_SCOPE_ROOT,
-  appScopeId,
-  buildAppScopeDefinition,
-} from './persona-app-scopes.js'
-export type {
-  MailboxAllowlist,
-  PersonaMailbox,
-  ReceivedEmail,
-} from './persona-mailbox.js'
-export type {
-  CorePersona,
-  CorePersonas,
-  PersonaAccountMeta,
-  PersonaDefinitions,
-  PersonaMeta,
-  PersonasMeta,
-} from './persona.types.js'
-
-/**
- * Signing in as a persona and talking to a stage over HTTP.
- *
- * Deliberately reached through this entry point rather than `@pikku/core/services`.
- * `HttpPersona` pulls in the actor-flow conversation runner and, through it, the
- * agent runner — none of which a production server has any use for. Exporting it
- * from the services barrel put that chain in the module graph of every app that
- * imports services, which only a bundler could remove and an unbundled Node or
- * Lambda deploy would load outright.
- */
-export {
-  HttpPersona,
-  createHttpPersonas,
-  type HttpPersonasConfig,
-} from '../../services/http-personas.js'
-export {
-  ActorSignIn,
-  OperatorSignIn,
-  establishOperatorSession,
-  IMPERSONATE_USER_ID_HEADER,
-  type ActorSecretResolver,
-  type PersonaSignIn,
-  type OperatorSignInOptions,
-  type OperatorSessionResult,
-  authMount,
-} from '../../services/persona-sign-in.js'
-export {
-  ACTOR_ROOT_SECRET_MIN_LENGTH,
-  ACTOR_SECRET_INFO,
-  ACTOR_SECRET_NAME,
-  actorSecretSubject,
-  deriveActorSecret,
-  verifyActorSecret,
-} from '../../services/persona-actor-secret.js'
-export {
-  postScenarioJson,
-  readScenarioHttpResponse,
-} from '../../services/personas-service.js'