@pikku/core 0.12.1 → 0.12.3

package/src/wirings/http/http.types.ts

@@ -1,6 +1,5 @@
 import type { SerializeOptions } from 'cookie'
 import type { StandardSchemaV1 } from '@standard-schema/spec'
-import type { PikkuError } from '../../errors/error-handler.js'
 import type {
   CorePikkuMiddleware,
   CommonWireMeta,
@@ -36,6 +35,7 @@ export type RunHTTPWiringOptions = Partial<{
   logWarningsForStatusCodes: number[]
   coerceDataFromSchema: boolean
   bubbleErrors: boolean
+  exposeErrors: boolean
   generateRequestId: () => string
 }>
 
@@ -59,16 +59,6 @@ export type HTTPHeadersSchema = StandardSchemaV1<
   Record<string, string | string[] | undefined>
 >
 
-/**
- * Documentation config for OpenAPI generation
- */
-export type HTTPRouteDocsConfig = {
-  description?: string
-  response?: string
-  errors?: Array<typeof PikkuError>
-  tags?: string[]
-}
-
 /**
  * Common HTTP route configuration shared between wireHTTP and wireHTTPRoutes
  */
@@ -77,7 +67,6 @@ export type HTTPRouteBaseConfig = {
   timeout?: number
   tags?: string[]
   headers?: HTTPHeadersSchema
-  docs?: HTTPRouteDocsConfig
 }
 
 /**
@@ -271,6 +260,7 @@ export interface PikkuHTTPRequest<In = unknown> {
   data(): Promise<In>
   json(): Promise<unknown>
   arrayBuffer(): Promise<ArrayBuffer>
+  headers(): Record<string, string>
   header(headerName: string): string | null
   cookie(name?: string): string | null
   params(): Partial<Record<string, string | string[]>>
@@ -293,6 +283,7 @@ export interface PikkuHTTPResponse<Out = unknown> {
       | ReadableStream
   ): this
   json(data: Out): this
+  send?(data: string | ArrayBuffer | Buffer): this
   redirect(location: string, status?: number): this
   close?: () => void
   setMode?: (mode: 'stream') => void

package/src/wirings/http/index.ts

@@ -11,12 +11,15 @@ export {
 } from './http-runner.js'
 
 export { wireHTTPRoutes, defineHTTPRoutes } from './http-routes.js'
+export { toWebRequest, applyWebResponse } from './web-request.js'
 
 export type {
   AssertHTTPWiringParams,
   CoreHTTPFunctionWiring,
   HTTPMethod,
   HTTPRouteBaseConfig,
+  HTTPRouteContract,
+  HTTPRouteMap,
   HTTPWiringsMeta,
   PikkuHTTPRequest,
   PikkuHTTPResponse,

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

@@ -43,6 +43,10 @@ export class PikkuFetchHTTPRequest<In = unknown>
     return this.request.arrayBuffer()
   }
 
+  public headers(): Record<string, string> {
+    return Object.fromEntries(this.request.headers.entries())
+  }
+
   /**
    * Retrieves the value of a specific header.
    * @param headerName - The name of the header to retrieve.

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

@@ -83,10 +83,10 @@ export class PikkuFetchHTTPResponse implements PikkuHTTPResponse {
     return this
   }
 
-  // public body(body: BodyInit): this {
-  //   this.#body = body
-  //   return this
-  // }
+  public send(data: any): this {
+    this.#body = data
+    return this
+  }
 
   public redirect(location: string, status: number = 302): this {
     if (

package/src/wirings/http/web-request.test.ts

@@ -0,0 +1,236 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { toWebRequest, applyWebResponse } from './web-request.js'
+import type {
+  PikkuHTTPRequest,
+  PikkuHTTPResponse,
+  PikkuQuery,
+} from './http.types.js'
+
+const createMockRequest = (
+  overrides: Partial<{
+    method: string
+    path: string
+    headers: Record<string, string>
+    query: Record<string, string>
+    body: ArrayBuffer
+  }> = {}
+): PikkuHTTPRequest => ({
+  method: () => (overrides.method ?? 'get') as any,
+  path: () => overrides.path ?? '/test',
+  headers: () => overrides.headers ?? {},
+  header: (name: string) =>
+    (overrides.headers ?? {})[name.toLowerCase()] ?? null,
+  cookie: () => null,
+  params: () => ({}),
+  setParams: () => {},
+  query: () => (overrides.query ?? {}) as PikkuQuery,
+  json: async () => ({}),
+  arrayBuffer: async () => overrides.body ?? new ArrayBuffer(0),
+  data: async () => ({}) as any,
+})
+
+const createMockResponse = () => {
+  const state = {
+    statusCode: 0,
+    headers: {} as Record<string, string | string[]>,
+    body: null as string | null,
+    redirectUrl: null as string | null,
+    redirectStatus: null as number | null,
+  }
+
+  const res: PikkuHTTPResponse = {
+    status(code: number) {
+      state.statusCode = code
+      return res
+    },
+    header(name: string, value: string | string[]) {
+      state.headers[name.toLowerCase()] = value
+      return res
+    },
+    cookie() {
+      return res
+    },
+    json() {
+      return res
+    },
+    arrayBuffer(data: any) {
+      state.body = typeof data === 'string' ? data : null
+      return res
+    },
+    redirect(location: string, status?: number) {
+      state.redirectUrl = location
+      state.redirectStatus = status ?? 302
+      return res
+    },
+  }
+
+  return { res, state }
+}
+
+describe('toWebRequest', () => {
+  test('converts a GET request with correct URL and method', async () => {
+    const req = createMockRequest({
+      method: 'get',
+      path: '/api/test',
+      headers: { host: 'example.com' },
+    })
+
+    const webReq = toWebRequest(req)
+
+    assert.equal(webReq.method, 'GET')
+    assert.equal(new URL(webReq.url).pathname, '/api/test')
+    assert.equal(new URL(webReq.url).host, 'example.com')
+    assert.equal(webReq.body, null)
+  })
+
+  test('copies query parameters', async () => {
+    const req = createMockRequest({
+      query: { search: 'hello', page: '2' },
+    })
+
+    const webReq = toWebRequest(req)
+    const url = new URL(webReq.url)
+
+    assert.equal(url.searchParams.get('search'), 'hello')
+    assert.equal(url.searchParams.get('page'), '2')
+  })
+
+  test('copies all headers', async () => {
+    const req = createMockRequest({
+      headers: {
+        'content-type': 'application/json',
+        authorization: 'Bearer abc123',
+        host: 'localhost',
+      },
+    })
+
+    const webReq = toWebRequest(req)
+
+    assert.equal(webReq.headers.get('content-type'), 'application/json')
+    assert.equal(webReq.headers.get('authorization'), 'Bearer abc123')
+  })
+
+  test('uses custom baseUrl when provided', async () => {
+    const req = createMockRequest({ path: '/callback' })
+
+    const webReq = toWebRequest(req, 'https://myapp.com')
+    const url = new URL(webReq.url)
+
+    assert.equal(url.origin, 'https://myapp.com')
+    assert.equal(url.pathname, '/callback')
+  })
+
+  test('falls back to localhost when no host header', async () => {
+    const req = createMockRequest({ path: '/test' })
+
+    const webReq = toWebRequest(req)
+    const url = new URL(webReq.url)
+
+    assert.equal(url.host, 'localhost')
+  })
+
+  test('POST request includes streaming body', async () => {
+    const bodyContent = JSON.stringify({
+      username: 'admin',
+      password: 'secret',
+    })
+    const encoder = new TextEncoder()
+    const bodyBuffer = encoder.encode(bodyContent).buffer as ArrayBuffer
+
+    const req = createMockRequest({
+      method: 'post',
+      path: '/signin',
+      headers: { 'content-type': 'application/json', host: 'localhost' },
+      body: bodyBuffer,
+    })
+
+    const webReq = toWebRequest(req)
+
+    assert.equal(webReq.method, 'POST')
+    assert.notEqual(webReq.body, null)
+
+    const text = await webReq.text()
+    assert.equal(text, bodyContent)
+  })
+
+  test('GET request has no body', async () => {
+    const req = createMockRequest({ method: 'get' })
+    const webReq = toWebRequest(req)
+    assert.equal(webReq.body, null)
+  })
+
+  test('HEAD request has no body', async () => {
+    const req = createMockRequest({ method: 'head' })
+    const webReq = toWebRequest(req)
+    assert.equal(webReq.body, null)
+  })
+
+  test('OPTIONS request has no body', async () => {
+    const req = createMockRequest({ method: 'options' })
+    const webReq = toWebRequest(req)
+    assert.equal(webReq.body, null)
+  })
+})
+
+describe('applyWebResponse', () => {
+  test('copies status code', async () => {
+    const { res, state } = createMockResponse()
+    const webRes = new Response('OK', { status: 201 })
+
+    await applyWebResponse(res, webRes)
+
+    assert.equal(state.statusCode, 201)
+  })
+
+  test('copies response headers', async () => {
+    const { res, state } = createMockResponse()
+    const webRes = new Response('', {
+      status: 200,
+      headers: {
+        'content-type': 'text/html',
+        'x-custom': 'value',
+      },
+    })
+
+    await applyWebResponse(res, webRes)
+
+    assert.equal(state.headers['content-type'], 'text/html')
+    assert.equal(state.headers['x-custom'], 'value')
+  })
+
+  test('handles redirect via location header', async () => {
+    const { res, state } = createMockResponse()
+    const webRes = new Response(null, {
+      status: 302,
+      headers: { location: 'https://github.com/login/oauth/authorize' },
+    })
+
+    await applyWebResponse(res, webRes)
+
+    assert.equal(state.redirectUrl, 'https://github.com/login/oauth/authorize')
+    assert.equal(state.statusCode, 302)
+  })
+
+  test('writes text body', async () => {
+    const { res, state } = createMockResponse()
+    const webRes = new Response('{"session": true}', {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    })
+
+    await applyWebResponse(res, webRes)
+
+    assert.equal(state.body, '{"session": true}')
+  })
+
+  test('does not write empty body', async () => {
+    const { res, state } = createMockResponse()
+    const webRes = new Response(null, { status: 204 })
+
+    await applyWebResponse(res, webRes)
+
+    assert.equal(state.body, null)
+    assert.equal(state.statusCode, 204)
+  })
+})

package/src/wirings/http/web-request.ts

@@ -0,0 +1,104 @@
+import type { PikkuHTTPRequest } from './http.types.js'
+import type { PikkuHTTPResponse } from './http.types.js'
+
+/**
+ * Converts a PikkuHTTPRequest into a Web API Request.
+ * Useful for bridging Pikku routes to libraries that expect standard Web Request objects.
+ */
+export function toWebRequest(req: PikkuHTTPRequest, baseUrl?: string): Request {
+  const url = new URL(
+    req.path(),
+    baseUrl ?? `http://${req.header('host') ?? 'localhost'}`
+  )
+
+  const query = req.query()
+  for (const [key, value] of Object.entries(query)) {
+    if (value != null) {
+      url.searchParams.set(key, String(value))
+    }
+  }
+
+  const headers = new Headers(req.headers())
+
+  const method = req.method().toUpperCase()
+  const hasBody = !['GET', 'HEAD', 'OPTIONS'].includes(method)
+
+  if (!hasBody) {
+    return new Request(url, { method, headers })
+  }
+
+  return new Request(url, {
+    method,
+    headers,
+    body: new ReadableStream({
+      async start(controller) {
+        try {
+          const buffer = await req.arrayBuffer()
+          if (buffer.byteLength > 0) {
+            controller.enqueue(new Uint8Array(buffer))
+          } else {
+            // arrayBuffer may be empty if body was pre-parsed (e.g., Express middleware)
+            const contentType = (
+              headers.get('content-type') || ''
+            ).toLowerCase()
+            const parsed = await req.json()
+            if (
+              parsed &&
+              typeof parsed === 'object' &&
+              Object.keys(parsed as any).length > 0
+            ) {
+              let reconstructed: string
+              if (contentType.includes('application/x-www-form-urlencoded')) {
+                reconstructed = new URLSearchParams(
+                  parsed as Record<string, string>
+                ).toString()
+              } else {
+                reconstructed = JSON.stringify(parsed)
+              }
+              controller.enqueue(new TextEncoder().encode(reconstructed))
+            }
+          }
+        } catch {
+          // Empty body
+        }
+        controller.close()
+      },
+    }),
+    // @ts-ignore - duplex is needed for streaming body in Node.js
+    duplex: 'half',
+  })
+}
+
+const SKIP_RESPONSE_HEADERS = new Set(['content-length', 'transfer-encoding'])
+
+/**
+ * Applies a Web API Response to a PikkuHTTPResponse.
+ * Copies status, headers (including Set-Cookie), redirects, and body.
+ */
+export async function applyWebResponse(
+  res: PikkuHTTPResponse,
+  webResponse: Response
+): Promise<void> {
+  res.status(webResponse.status)
+
+  webResponse.headers.forEach((value, name) => {
+    const lower = name.toLowerCase()
+    if (SKIP_RESPONSE_HEADERS.has(lower)) {
+      return
+    }
+    if (lower === 'location') {
+      res.redirect(value, webResponse.status)
+    } else {
+      res.header(name, value)
+    }
+  })
+
+  const body = await webResponse.text()
+  if (body) {
+    if (res.send) {
+      res.send(body)
+    } else {
+      res.arrayBuffer(body)
+    }
+  }
+}

package/src/wirings/mcp/mcp-endpoint-registry.ts

@@ -44,7 +44,7 @@ export class MCPEndpointRegistry {
           name: tool.name,
           title: tool.title,
           description: tool.description,
-          inputSchema: tool.parameters,
+          inputSchema: tool.parameters ?? { type: 'object' },
           outputSchema: tool.returns,
           enabled: tool.enabled !== undefined ? tool.enabled : true,
         })

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

@@ -19,6 +19,7 @@ import {
   getCreateWireServices,
 } from '../../pikku-state.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
+import { resolveNamespace } from '../rpc/rpc-runner.js'
 import {
   BadRequestError,
   NotFoundError,
@@ -231,18 +232,35 @@ async function runMCPPikkuFunc(
       meta = pikkuState(null, 'mcp', 'promptsMeta')[name]
     }
 
-    let result = await runPikkuFunc('mcp', `${type}:${name}`, pikkuFuncId, {
-      singletonServices,
-      createWireServices,
-      data: () => request.params,
-      inheritedMiddleware: meta?.middleware,
-      wireMiddleware: mcp?.middleware,
-      inheritedPermissions: meta?.permissions,
-      wirePermissions: mcp?.permissions,
-      tags: mcp?.tags,
-      wire,
-      sessionService: mcpSessionService,
-    })
+    // Resolve namespaced function IDs (e.g., 'swaggerPetstore:findPetsByStatus')
+    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,
+        inheritedPermissions: meta?.permissions,
+        wirePermissions: mcp?.permissions,
+        tags: mcp?.tags,
+        wire,
+        sessionService: mcpSessionService,
+        packageName: resolvedPackageName,
+      }
+    )
 
     if (type === 'tool' && meta?.outputSchema !== 'MCPToolResponse') {
       result = [{ type: 'text', text: JSON.stringify(result) }]

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

@@ -4,7 +4,7 @@ import type { CoreUserSession } from '../../types/core.types.js'
 import { runPikkuFunc } from '../../function/function-runner.js'
 import { pikkuState } from '../../pikku-state.js'
 import { ForbiddenError } from '../../errors/errors.js'
-import { PikkuError } from '../../errors/error-handler.js'
+import { PikkuError, addError } from '../../errors/error-handler.js'
 import type { PikkuRPC, ResolvedFunction } from './rpc-types.js'
 import { parseVersionedId } from '../../version.js'
 import { encryptJSON } from '../../crypto-utils.js'
@@ -16,18 +16,22 @@ export class RPCNotFoundError extends PikkuError {
     this.rpcName = rpcName
   }
 }
+addError(RPCNotFoundError, {
+  status: 404,
+  mcpCode: -32601,
+  message: 'RPC function not found.',
+})
 import type { AIAgentInput } from '../ai-agent/ai-agent.types.js'
 import type { AIStreamChannel } from '../ai-agent/ai-agent.types.js'
 import type { StreamAIAgentOptions } from '../ai-agent/ai-agent-prepare.js'
-import { runAIAgent } from '../ai-agent/ai-agent-runner.js'
+import { runAIAgent, resumeAIAgentSync } from '../ai-agent/ai-agent-runner.js'
 import { streamAIAgent, resumeAIAgent } from '../ai-agent/ai-agent-stream.js'
-import { approveAIAgent } from '../ai-agent/ai-agent-registry.js'
 
 /**
  * Resolve a namespaced function reference to package and function names
  * Uses pikkuState to look up the namespace -> package mapping
  */
-const resolveNamespace = (
+export const resolveNamespace = (
   namespacedFunction: string
 ): ResolvedFunction | null => {
   const colonIndex = namespacedFunction.indexOf(':')
@@ -38,16 +42,16 @@ const resolveNamespace = (
   const namespace = namespacedFunction.substring(0, colonIndex)
   const functionName = namespacedFunction.substring(colonIndex + 1)
 
-  const addons = pikkuState(null, 'rpc', 'addons')
+  const addons = pikkuState(null, 'addons', 'packages')
   const pkgConfig = addons.get(namespace)
   if (!pkgConfig) {
     return null
   }
 
   return {
-    namespace,
     package: pkgConfig.package,
     function: functionName,
+    addonConfig: pkgConfig,
   }
 }
 
@@ -90,7 +94,7 @@ export class ContextAwareRPCService {
       functionMeta = pikkuState(null, 'function', 'meta')[funcName]
     }
     if (!functionMeta) {
-      throw new Error(`Function not found: ${funcName}`)
+      throw new RPCNotFoundError(funcName)
     }
     if (!functionMeta.expose) {
       throw new ForbiddenError()
@@ -165,11 +169,11 @@ export class ContextAwareRPCService {
     }
     const funcName = funcMeta.pikkuFuncId || resolved.function
 
-    const addonConfig = pikkuState(null, 'rpc', 'addons').get(
-      resolved.namespace
-    )
-    const auth = addonConfig?.auth ?? this.options.requiresAuth
-    const tags = [...(addonConfig?.tags ?? []), ...(funcMeta.tags ?? [])]
+    const auth = resolved.addonConfig?.auth ?? this.options.requiresAuth
+    const tags = [
+      ...(resolved.addonConfig?.tags ?? []),
+      ...(funcMeta.tags ?? []),
+    ]
 
     // Execute the function using runPikkuFunc with the addon package's state
     // We use the parent services (this.services) since addon packages share services
@@ -201,6 +205,11 @@ export class ContextAwareRPCService {
           }
         : undefined,
     }
+
+    if (rpcName.includes(':')) {
+      return this.invokeAddonFunction<In, Out>(rpcName, data, mergedWire)
+    }
+
     return runPikkuFunc<In, Out>(
       'rpc',
       rpcName,
@@ -250,13 +259,21 @@ export class ContextAwareRPCService {
           runId: result.runId,
           result: result.object ?? result.text,
           usage: result.usage,
+          ...(result.status === 'suspended' && {
+            status: 'suspended' as const,
+            pendingApprovals: result.pendingApprovals,
+          }),
         }
       },
       stream: async (
         agentName: string,
-        input:
-          | { message: string; threadId: string; resourceId: string }
-          | Record<string, unknown>,
+        input: {
+          message: string
+          threadId: string
+          resourceId: string
+          model?: string
+          temperature?: number
+        },
         options?: StreamAIAgentOptions
       ) => {
         const channel = this.wire.channel as unknown as AIStreamChannel
@@ -289,14 +306,18 @@ export class ContextAwareRPCService {
         approvals: { toolCallId: string; approved: boolean }[],
         expectedAgentName?: string
       ) => {
-        if (!this.services.aiRunState)
-          throw new Error('AIRunStateService not available')
-        return approveAIAgent(
-          this.services.aiRunState,
-          runId,
-          approvals,
-          expectedAgentName
-        )
+        const result = await resumeAIAgentSync(runId, approvals, {
+          sessionService: this.options.sessionService,
+        }, expectedAgentName)
+        return {
+          runId: result.runId,
+          result: result.object ?? result.text,
+          usage: result.usage,
+          ...(result.status === 'suspended' && {
+            status: 'suspended' as const,
+            pendingApprovals: result.pendingApprovals,
+          }),
+        }
       },
     }
   }
@@ -313,7 +334,7 @@ export class ContextAwareRPCService {
     const colonIndex = funcName.indexOf(':')
     if (colonIndex !== -1) {
       const namespace = funcName.substring(0, colonIndex)
-      const addons = pikkuState(null, 'rpc', 'addons')
+      const addons = pikkuState(null, 'addons', 'packages')
       const pkgConfig = addons.get(namespace)
       endpoint = pkgConfig?.rpcEndpoint
     }

package/src/wirings/rpc/rpc-types.ts

@@ -45,7 +45,12 @@ export interface RPCHandler<Input, Output> {
  * Resolved function reference from namespace
  */
 export interface ResolvedFunction {
-  namespace: string
   package: string
   function: string
+  addonConfig: {
+    package: string
+    auth?: boolean
+    tags?: string[]
+    rpcEndpoint?: string
+  }
 }

package/src/wirings/rpc/wire-addon.ts

@@ -5,13 +5,14 @@ export type WireAddonConfig = {
   package: string
   rpcEndpoint?: string
   auth?: boolean
+  mcp?: boolean
   tags?: string[]
   secretOverrides?: Record<string, string>
   variableOverrides?: Record<string, string>
 }
 
 export const wireAddon = (config: WireAddonConfig): void => {
-  pikkuState(null, 'rpc', 'addons').set(config.name, {
+  pikkuState(null, 'addons', 'packages').set(config.name, {
     package: config.package,
     rpcEndpoint: config.rpcEndpoint,
     auth: config.auth,