@pikku/core 0.12.8 → 0.12.10

package/src/wirings/ai-agent/ai-agent-prepare.ts

@@ -11,6 +11,7 @@ import type {
 } from './ai-agent.types.js'
 import type { AIAgentRunnerParams } from '../../services/ai-agent-runner-service.js'
 import { PikkuError } from '../../errors/error-handler.js'
+import { AIProviderNotConfiguredError } from '../../errors/errors.js'
 import { pikkuState, getSingletonServices } from '../../pikku-state.js'
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js'
 import type { SessionService } from '../../services/user-session-service.js'
@@ -520,7 +521,7 @@ export async function prepareAgentRun(
 
   const agentRunner = singletonServices.aiAgentRunner
   if (!agentRunner) {
-    throw new Error('AIAgentRunnerService not available in singletonServices')
+    throw new AIProviderNotConfiguredError()
   }
 
   if (agent.dynamicWorkflows && singletonServices.workflowService) {

package/src/wirings/ai-agent/ai-agent-runner.test.ts

@@ -5,6 +5,7 @@ import { resetPikkuState, pikkuState } from '../../pikku-state.js'
 import { runAIAgent } from './ai-agent-runner.js'
 import type { CoreAIAgent, PikkuAIMiddlewareHooks } from './ai-agent.types.js'
 import type { AIAgentStepResult } from '../../services/ai-agent-runner-service.js'
+import { AIProviderNotConfiguredError } from '../../errors/errors.js'
 
 beforeEach(() => {
   resetPikkuState()
@@ -42,6 +43,39 @@ const makeStepResult = (
 })
 
 describe('runAIAgent', () => {
+  test('throws AIProviderNotConfiguredError when aiAgentRunner is missing', async () => {
+    addTestAgent('no-provider-agent')
+
+    const mockServices = {
+      logger: {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      },
+      aiRunState: {
+        createRun: async () => 'run-no-provider',
+        updateRun: async () => {},
+      },
+    } as any
+
+    pikkuState(null, 'package', 'singletonServices', mockServices)
+
+    await assert.rejects(
+      () =>
+        runAIAgent(
+          'no-provider-agent',
+          { message: 'hello', threadId: 't', resourceId: 'r' },
+          {}
+        ),
+      (error: unknown) => {
+        assert.ok(error instanceof AIProviderNotConfiguredError)
+        assert.match((error as Error).message, /AI provider/)
+        return true
+      }
+    )
+  })
+
   test('marks run as failed when runner throws', async () => {
     addTestAgent('failing-agent')
 

package/src/wirings/ai-agent/ai-agent-runner.ts

@@ -31,6 +31,7 @@ import {
 import { checkForApprovals, appendStepMessages } from './ai-agent-stream.js'
 import { pikkuState, getSingletonServices } from '../../pikku-state.js'
 import { resolveModelConfig } from './ai-agent-model-config.js'
+import { AIProviderNotConfiguredError } from '../../errors/errors.js'
 import { randomUUID } from 'crypto'
 
 export async function runAIAgent(
@@ -367,7 +368,7 @@ export async function resumeAIAgentSync(
   const memoryConfig = agent.memory
   const agentRunner = singletonServices.aiAgentRunner
   if (!agentRunner) {
-    throw new Error('AIAgentRunnerService not available')
+    throw new AIProviderNotConfiguredError()
   }
 
   const approvedIds = new Set(

package/src/wirings/ai-agent/ai-agent-stream.ts

@@ -10,6 +10,7 @@ import type {
   AIAgentMemoryConfig,
 } from './ai-agent.types.js'
 import { pikkuState, getSingletonServices } from '../../pikku-state.js'
+import { AIProviderNotConfiguredError } from '../../errors/errors.js'
 import {
   combineChannelMiddleware,
   wrapChannelWithMiddleware,
@@ -748,7 +749,7 @@ export async function resumeAIAgent(
   const memoryConfig = agent.memory
   const agentRunner = singletonServices.aiAgentRunner
   if (!agentRunner) {
-    throw new Error('AIAgentRunnerService not available in singletonServices')
+    throw new AIProviderNotConfiguredError()
   }
 
   if (!input.approved) {

package/src/wirings/channel/local/local-channel-runner.ts

@@ -5,6 +5,8 @@ import { processMessageHandlers } from '../channel-handler.js'
 import type { CoreChannel, RunChannelOptions } from '../channel.types.js'
 import { PikkuLocalChannelHandler } from './local-channel-handler.js'
 import type { PikkuWire, WireServices } from '../../../types/core.types.js'
+import { isProduction } from '../../../env.js'
+import { getErrorResponse } from '../../../errors/error-handler.js'
 import { handleHTTPError } from '../../../handle-error.js'
 import {
   PikkuSessionService,
@@ -121,9 +123,10 @@ export const runLocalChannel = async ({
             }
           } catch (e: any) {
             singletonServices.logger.error(`Error handling onConnect: ${e}`)
+            const errorResponse = getErrorResponse(e)
             channel.send({
-              error: e.message || 'Unknown error',
-              errorName: e.constructor?.name,
+              error: errorResponse?.message ?? (isProduction() ? 'Internal server error' : e.message),
+              ...(!isProduction() && { errorName: e.constructor?.name }),
             })
           }
         }
@@ -143,9 +146,10 @@ export const runLocalChannel = async ({
             })
           } catch (e: any) {
             singletonServices.logger.error(`Error handling onDisconnect: ${e}`)
+            const errorResponse = getErrorResponse(e)
             channel.send({
-              error: e.message || 'Unknown error',
-              errorName: e.constructor?.name,
+              error: errorResponse?.message ?? (isProduction() ? 'Internal server error' : e.message),
+              ...(!isProduction() && { errorName: e.constructor?.name }),
             })
           }
         }
@@ -165,9 +169,10 @@ export const runLocalChannel = async ({
           await channel.send(result)
         } catch (e: any) {
           singletonServices.logger.error(e)
+          const errorResponse = getErrorResponse(e)
           channel.send({
-            error: e.message || 'Unknown error',
-            errorName: e.constructor?.name,
+            error: errorResponse?.message ?? (isProduction() ? 'Internal server error' : e.message),
+            ...(!isProduction() && { errorName: e.constructor?.name }),
           })
           setTimeout(() => channel.close(), 200)
         }

package/src/wirings/credential/credential.types.ts

@@ -0,0 +1,28 @@
+import type { OAuth2CredentialConfig } from '../secret/secret.types.js'
+
+export type CoreCredential<T = unknown> = {
+  name: string
+  displayName: string
+  description?: string
+  type: 'singleton' | 'wire'
+  schema: T
+  oauth2?: OAuth2CredentialConfig & {
+    appCredentialSecretId: string
+  }
+}
+
+export type CredentialDefinitionMeta = {
+  name: string
+  displayName: string
+  description?: string
+  type: 'singleton' | 'wire'
+  schema?: Record<string, unknown> | string
+  oauth2?: OAuth2CredentialConfig & {
+    appCredentialSecretId: string
+  }
+  sourceFile?: string
+}
+
+export type CredentialDefinitionsMeta = Record<string, CredentialDefinitionMeta>
+
+export type CredentialDefinitions = CredentialDefinitionMeta[]

package/src/wirings/credential/index.ts

@@ -0,0 +1,8 @@
+export { wireCredential } from './wire-credential.js'
+export { validateAndBuildCredentialDefinitionsMeta } from './validate-credential-definitions.js'
+export type {
+  CoreCredential,
+  CredentialDefinitionMeta,
+  CredentialDefinitionsMeta,
+  CredentialDefinitions,
+} from './credential.types.js'

package/src/wirings/credential/validate-credential-definitions.ts

@@ -0,0 +1,64 @@
+import type {
+  CredentialDefinitions,
+  CredentialDefinitionsMeta,
+} from './credential.types.js'
+
+export interface SchemaRefLike {
+  variableName: string
+  sourceFile: string
+}
+
+export function validateAndBuildCredentialDefinitionsMeta(
+  definitions: CredentialDefinitions,
+  schemaLookup: Map<string, SchemaRefLike>
+): CredentialDefinitionsMeta {
+  const meta: CredentialDefinitionsMeta = {}
+
+  for (const def of definitions) {
+    const existing = meta[def.name]
+
+    if (existing) {
+      if (def.schema && existing.schema) {
+        const defSchemaRef = schemaLookup.get(def.schema as string)
+        const existingSchemaRef = schemaLookup.get(existing.schema as string)
+
+        if (defSchemaRef && existingSchemaRef) {
+          if (
+            defSchemaRef.variableName !== existingSchemaRef.variableName ||
+            defSchemaRef.sourceFile !== existingSchemaRef.sourceFile
+          ) {
+            throw new Error(
+              `Credential '${def.name}' is defined with different schemas.\n` +
+                `  First definition: ${existing.sourceFile} (schema: ${existingSchemaRef.variableName})\n` +
+                `  Second definition: ${def.sourceFile} (schema: ${defSchemaRef.variableName})\n` +
+                `Credentials sharing a name must use the same schema.`
+            )
+          }
+        }
+      }
+
+      if (def.type !== existing.type) {
+        throw new Error(
+          `Credential '${def.name}' is defined with different types.\n` +
+            `  First definition: ${existing.sourceFile} (type: ${existing.type})\n` +
+            `  Second definition: ${def.sourceFile} (type: ${def.type})\n` +
+            `Credentials sharing a name must use the same type.`
+        )
+      }
+
+      continue
+    }
+
+    meta[def.name] = {
+      name: def.name,
+      displayName: def.displayName,
+      description: def.description,
+      type: def.type,
+      schema: def.schema,
+      oauth2: def.oauth2,
+      sourceFile: def.sourceFile,
+    }
+  }
+
+  return meta
+}

package/src/wirings/credential/wire-credential.ts

@@ -0,0 +1,49 @@
+import type { CoreCredential } from './credential.types.js'
+
+/**
+ * No-op function for declaring credentials.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing.
+ *
+ * @example
+ * ```typescript
+ * // Per-user API key
+ * wireCredential({
+ *   name: 'stripe',
+ *   displayName: 'Stripe API Key',
+ *   type: 'wire',
+ *   schema: z.object({ apiKey: z.string() }),
+ * })
+ *
+ * // Per-user OAuth
+ * wireCredential({
+ *   name: 'google-sheets',
+ *   displayName: 'Google Sheets',
+ *   type: 'wire',
+ *   schema: z.object({ accessToken: z.string(), refreshToken: z.string() }),
+ *   oauth2: {
+ *     appCredentialSecretId: 'GOOGLE_OAUTH_APP',
+ *     authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+ *     tokenUrl: 'https://oauth2.googleapis.com/token',
+ *     scopes: ['https://www.googleapis.com/auth/spreadsheets'],
+ *     tokenSecretId: 'GOOGLE_OAUTH_TOKENS',
+ *   }
+ * })
+ *
+ * // Platform-level OAuth (singleton)
+ * wireCredential({
+ *   name: 'slack',
+ *   displayName: 'Slack',
+ *   type: 'singleton',
+ *   schema: z.object({ accessToken: z.string(), refreshToken: z.string() }),
+ *   oauth2: {
+ *     appCredentialSecretId: 'SLACK_OAUTH_APP',
+ *     authorizationUrl: 'https://slack.com/oauth/v2/authorize',
+ *     tokenUrl: 'https://slack.com/api/oauth.v2.access',
+ *     scopes: ['chat:write', 'channels:read'],
+ *     tokenSecretId: 'SLACK_OAUTH_TOKENS',
+ *   }
+ * })
+ * ```
+ */
+export const wireCredential = <T>(_config: CoreCredential<T>): void => {}

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

@@ -32,6 +32,11 @@ import {
   getCreateWireServices,
 } from '../../pikku-state.js'
 import { PikkuSessionService } from '../../services/user-session-service.js'
+import { getErrorResponse } from '../../errors/error-handler.js'
+import {
+  PikkuCredentialWireService,
+  createMiddlewareCredentialWireProps,
+} from '../../services/credential-wire-service.js'
 import { handleHTTPError } from '../../handle-error.js'
 import { pikkuState } from '../../pikku-state.js'
 import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js'
@@ -298,6 +303,7 @@ const executeRoute = async (
   }
 ) => {
   const userSession = new PikkuSessionService<CoreUserSession>()
+  const credentialWire = new PikkuCredentialWireService()
   const { params, route, meta } = matchedRoute
   const { singletonServices, createWireServices, skipUserSession, requestId } =
     services
@@ -376,6 +382,7 @@ const executeRoute = async (
     setSession: (s: any) => userSession.setInitial(s),
     getSession: () => userSession.get(),
     hasSessionChanged: () => userSession.sessionChanged,
+    ...createMiddlewareCredentialWireProps(credentialWire),
   }
 
   result = await runPikkuFunc(
@@ -395,6 +402,7 @@ const executeRoute = async (
       tags: route.tags,
       wire,
       sessionService: userSession,
+      credentialWireService: credentialWire,
       packageName: meta.packageName,
     }
   )
@@ -530,7 +538,7 @@ export const fetchData = async <In, Out>(
         apiRoute,
         apiType,
       })
-      throw new NotFoundError(`Route not found: ${apiRoute}`)
+      throw new NotFoundError()
     }
 
     // Execute the matched route along with its middleware and session management
@@ -552,10 +560,11 @@ export const fetchData = async <In, Out>(
       // For SSE routes, send error through the stream since the response is already in stream mode
       singletonServices.logger.error(e instanceof Error ? e.message : e)
       try {
+        const errorResponse = getErrorResponse(e)
         response.arrayBuffer(
           JSON.stringify({
             type: 'error',
-            errorText: e instanceof Error ? e.message : String(e),
+            errorText: errorResponse?.message ?? 'Internal server error',
           })
         )
         response.arrayBuffer(JSON.stringify({ type: 'done' }))

package/src/wirings/http/pikku-fetch-http-request.ts

@@ -105,6 +105,9 @@ export class PikkuFetchHTTPRequest<In = unknown>
     const merged: Record<string, unknown> = {}
     for (const part of parts) {
       for (const [key, value] of Object.entries(part)) {
+        if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+          continue
+        }
         if (key in merged && !valuesAreEquivalent(merged[key], value)) {
           throw new UnprocessableContentError(
             `Conflicting values for key "${key}": "${merged[key]}" vs "${value}"`
@@ -141,7 +144,14 @@ export class PikkuFetchHTTPRequest<In = unknown>
         body = { data: buffer }
       } else if (contentType === 'application/x-www-form-urlencoded') {
         const text = await this.request.text()
-        body = Object.fromEntries(new URLSearchParams(text))
+        const params = new URLSearchParams(text)
+        let count = 0
+        for (const _ of params) {
+          if (++count > 256) {
+            throw new UnprocessableContentError('Too many form parameters')
+          }
+        }
+        body = Object.fromEntries(params)
       } else {
         throw new UnprocessableContentError(
           `Unsupported content type ${contentType}`

package/src/wirings/oauth2/index.ts

@@ -1,3 +1,4 @@
 export { OAuth2Client } from './oauth2-client.js'
-export { wireOAuth2Credential } from './wire-oauth2-credential.js'
+export { createOAuth2Handler } from './oauth2-routes.js'
+export type { CreateOAuth2HandlerOptions } from './oauth2-routes.js'
 export type { OAuth2AppCredential, OAuth2Token } from './oauth2.types.js'

package/src/wirings/oauth2/oauth2-client.ts

@@ -30,7 +30,8 @@ import type { SecretService } from '../../services/secret-service.js'
  * })
  * ```
  */
-const DEFAULT_TIMEOUT_MS = 30000
+const DEFAULT_TIMEOUT_MS = 30_000
+const TOKEN_EXPIRY_BUFFER_MS = 60_000
 
 /**
  * Helper to fetch with a timeout using AbortController.
@@ -145,18 +146,15 @@ export class OAuth2Client {
    * Uses a promise lock to prevent concurrent refresh attempts.
    */
   private async refreshAndGetToken(): Promise<string> {
-    // If already refreshing, wait for that to complete
     if (this.refreshPromise) {
       const token = await this.refreshPromise
       return token.accessToken
     }
 
-    // Start refresh
     this.refreshPromise = this.doRefreshToken()
 
     try {
       const token = await this.refreshPromise
-      this.cachedToken = token
       return token.accessToken
     } finally {
       this.refreshPromise = null
@@ -211,9 +209,8 @@ export class OAuth2Client {
       scope: data.scope,
     }
 
-    // Cache and persist the refreshed token
-    this.cachedToken = token
     await this.secrets.setSecretJSON(this.oauth2Config.tokenSecretId, token)
+    this.cachedToken = token
 
     return token
   }
@@ -225,8 +222,7 @@ export class OAuth2Client {
     if (!token.expiresAt) {
       return true // No expiry info, assume valid
     }
-    // Add 60 second buffer to account for clock skew
-    return token.expiresAt > Date.now() + 60000
+    return token.expiresAt > Date.now() + TOKEN_EXPIRY_BUFFER_MS
   }
 
   /**

package/src/wirings/oauth2/oauth2-routes.ts

@@ -0,0 +1,234 @@
+import type { CredentialService } from '../../services/credential-service.js'
+import type { SecretService } from '../../services/secret-service.js'
+import type { JWTService } from '../../services/jwt-service.js'
+import type { CredentialDefinitionsMeta } from '../credential/credential.types.js'
+import type { OAuth2Token } from './oauth2.types.js'
+import { OAuth2Client } from './oauth2-client.js'
+
+const TOKEN_EXPIRY_BUFFER_MS = 60_000
+
+export type CreateOAuth2HandlerOptions = {
+  credentialsMeta: CredentialDefinitionsMeta
+  basePath?: string
+}
+
+type OAuth2RouteContext = {
+  credentialsMeta: CredentialDefinitionsMeta
+  basePath: string
+}
+
+function getCredentialMeta(ctx: OAuth2RouteContext, name: string) {
+  const meta = ctx.credentialsMeta[name]
+  if (!meta) {
+    throw new Error(`Credential '${name}' not found`)
+  }
+  if (!meta.oauth2) {
+    throw new Error(`Credential '${name}' is not an OAuth2 credential`)
+  }
+  return meta
+}
+
+/**
+ * Creates OAuth2 route handlers for user credential management.
+ *
+ * Returns individual handler functions for connect/callback/disconnect/status
+ * that handle the OAuth2 authorization code flow and store tokens in CredentialService.
+ *
+ * @example
+ * ```typescript
+ * const oauth2 = createOAuth2Handler({ credentialsMeta })
+ *
+ * const oauth2Routes = defineHTTPRoutes({
+ *   auth: true,
+ *   basePath: '/credentials',
+ *   routes: {
+ *     connect: { method: 'get', route: '/:name/connect', func: oauth2.connect },
+ *     callback: { method: 'get', route: '/:name/callback', func: oauth2.callback, auth: false },
+ *     disconnect: { method: 'delete', route: '/:name', func: oauth2.disconnect },
+ *     status: { method: 'get', route: '/:name/status', func: oauth2.status },
+ *   },
+ * })
+ *
+ * wireHTTPRoutes({ routes: { credentials: oauth2Routes } })
+ * ```
+ */
+export const createOAuth2Handler = (options: CreateOAuth2HandlerOptions) => {
+  const basePath = options.basePath ?? '/credentials'
+  const ctx: OAuth2RouteContext = {
+    credentialsMeta: options.credentialsMeta,
+    basePath,
+  }
+
+  const connectHandler = async (
+    services: {
+      secrets: SecretService
+      jwt: JWTService
+      credentialService: CredentialService
+    },
+    _data: any,
+    wire: any
+  ) => {
+    const { name } = wire.http.request.params()
+    const meta = getCredentialMeta(ctx, name)
+    const queryParams = wire.http.request.query()
+    const redirectUrl = queryParams.redirect_url || queryParams.redirect
+
+    const oauth2Client = new OAuth2Client(
+      meta.oauth2!,
+      meta.oauth2!.appCredentialSecretId,
+      services.secrets
+    )
+
+    const userId = wire.session?.userId
+    if (!userId) {
+      throw new Error('Authentication required for OAuth2 connect')
+    }
+
+    const state = await services.jwt.encode(
+      { value: 10, unit: 'minute' },
+      {
+        userId,
+        credentialName: name,
+        redirectUrl,
+      }
+    )
+
+    let origin = wire.http.request.header('origin')
+    if (!origin) {
+      const host = wire.http.request.header('host')
+      if (!host) {
+        throw new Error(
+          'Unable to determine request origin for OAuth2 callback'
+        )
+      }
+      const protocol = wire.http.request.header('x-forwarded-proto') || 'http'
+      origin = `${protocol}://${host}`
+    }
+    const callbackUrl = `${origin}${basePath}/${name}/callback`
+    const authUrl = await oauth2Client.getAuthorizationUrl(state, callbackUrl)
+
+    return Response.redirect(authUrl, 302)
+  }
+
+  const callbackHandler = async (
+    services: {
+      secrets: SecretService
+      jwt: JWTService
+      credentialService: CredentialService
+      logger: any
+    },
+    _data: any,
+    wire: any
+  ) => {
+    const { name } = wire.http.request.params()
+    const meta = getCredentialMeta(ctx, name)
+    const queryParams = wire.http.request.query()
+    const code = queryParams.code as string | undefined
+    const state = queryParams.state as string | undefined
+
+    if (!code || !state) {
+      throw new Error('Missing code or state parameter')
+    }
+
+    let statePayload: {
+      userId: string
+      credentialName: string
+      redirectUrl?: string
+    }
+    try {
+      statePayload = await services.jwt.decode(state)
+    } catch {
+      throw new Error('Invalid or expired OAuth2 state')
+    }
+
+    if (statePayload.credentialName !== name) {
+      throw new Error('Credential name mismatch in state')
+    }
+
+    const oauth2Client = new OAuth2Client(
+      meta.oauth2!,
+      meta.oauth2!.appCredentialSecretId,
+      services.secrets
+    )
+
+    let origin = wire.http.request.header('origin')
+    if (!origin) {
+      const host = wire.http.request.header('host')
+      if (!host) {
+        throw new Error(
+          'Unable to determine request origin for OAuth2 callback'
+        )
+      }
+      const protocol = wire.http.request.header('x-forwarded-proto') || 'http'
+      origin = `${protocol}://${host}`
+    }
+    const callbackUrl = `${origin}${basePath}/${name}/callback`
+    const tokens = await oauth2Client.exchangeCode(code, callbackUrl)
+
+    await services.credentialService.set(name, tokens, statePayload.userId)
+
+    services.logger.info(
+      `OAuth2 tokens stored for user '${statePayload.userId}', credential '${name}'`
+    )
+
+    if (statePayload.redirectUrl) {
+      return Response.redirect(statePayload.redirectUrl, 302)
+    } else {
+      return { success: true, credentialName: name }
+    }
+  }
+
+  const disconnectHandler = async (
+    services: { credentialService: CredentialService; logger: any },
+    _data: any,
+    wire: any
+  ) => {
+    const { name } = wire.http.request.params()
+    const userId = wire.session?.userId
+    if (!userId) {
+      throw new Error('Authentication required')
+    }
+    await services.credentialService.delete(name, userId)
+    services.logger.info(
+      `OAuth2 credential '${name}' disconnected for user '${userId}'`
+    )
+    return { success: true }
+  }
+
+  const statusHandler = async (
+    services: { credentialService: CredentialService },
+    _data: any,
+    wire: any
+  ) => {
+    const { name } = wire.http.request.params()
+    const userId = wire.session?.userId
+    if (!userId) {
+      throw new Error('Authentication required')
+    }
+
+    const credential = await services.credentialService.get<OAuth2Token>(
+      name,
+      userId
+    )
+
+    if (!credential) {
+      return { connected: false }
+    }
+
+    return {
+      connected: true,
+      hasRefreshToken: !!credential.refreshToken,
+      expiresAt: credential.expiresAt,
+      isExpired: credential.expiresAt
+        ? credential.expiresAt < Date.now() + TOKEN_EXPIRY_BUFFER_MS
+        : false,
+    }
+  }
+
+  return {
+    connect: { func: connectHandler } as any,
+    callback: { func: callbackHandler } as any,
+    disconnect: { func: disconnectHandler } as any,
+    status: { func: statusHandler } as any,
+  }
+}