@pikku/core 0.12.79 → 0.12.80

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

@@ -73,10 +73,6 @@ export interface PikkuHTTP<In = unknown> {
   response?: PikkuHTTPResponse
 }
 
-export type RequestHeaders =
-  | Record<string, string | string[] | undefined>
-  | ((headerName: string) => string | string[] | undefined)
-
 export type PikkuQuery<T = Record<string, string | undefined>> = Record<
   string,
   string | T | null | Array<T | null>
@@ -207,17 +203,6 @@ export type HTTPWiringMeta = CommonWireMeta & {
 }
 export type HTTPWiringsMeta = Record<HTTPMethod, Record<string, HTTPWiringMeta>>
 
-export type HTTPFunctionsMeta = Array<{
-  name: string
-  inputs: string[] | null
-  outputs: string[] | null
-}>
-
-export type HTTPWiringMiddleware = {
-  route: string
-  middleware: CorePikkuMiddleware[]
-}
-
 export interface PikkuHTTPRequest<In = unknown> {
   method(): HTTPMethod
   path(): string

package/src/wirings/http/index.ts

@@ -6,13 +6,7 @@ export type { PikkuFetchHTTPRequestOptions } from './pikku-fetch-http-request.js
 export { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js'
 export { logRoutes } from './log-http-routes.js'
 
-export {
-  fetch,
-  fetchData,
-  wireHTTP,
-  addHTTPMiddleware,
-  addHTTPPermission,
-} from './http-runner.js'
+export { fetch, fetchData, wireHTTP, addHTTPMiddleware } from './http-runner.js'
 
 export { wireHTTPRoutes, defineHTTPRoutes } from './http-routes.js'
 export { toWebRequest, applyWebResponse } from './web-request.js'

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

@@ -248,7 +248,7 @@ function valuesAreEquivalent(a: unknown, b: unknown): boolean {
   return coerce(a) === coerce(b)
 }
 
-function coerce(value: unknown): string | number | boolean {
+function coerce(value: unknown): unknown {
   if (typeof value === 'boolean' || typeof value === 'number') return value
   if (typeof value === 'string') {
     if (value === 'true') return true
@@ -256,5 +256,5 @@ function coerce(value: unknown): string | number | boolean {
     const num = Number(value)
     return isNaN(num) ? value : num
   }
-  return value as any
+  return value
 }

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

@@ -40,7 +40,7 @@ export function toWebRequest(req: PikkuHTTPRequest, baseUrl?: string): Request {
             if (
               parsed &&
               typeof parsed === 'object' &&
-              Object.keys(parsed as any).length > 0
+              Object.keys(parsed as object).length > 0
             ) {
               let reconstructed: string
               if (contentType.includes('application/x-www-form-urlencoded')) {

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

@@ -39,12 +39,6 @@ export type RunMCPEndpointParams<Tools extends string = any> = {
   exposeErrors?: boolean
 }
 
-export type JsonRpcError = {
-  code: number
-  message: string
-  data?: any
-}
-
 export const wireMCPResource = <
   PikkuFunctionConfig extends CorePikkuFunctionConfig<
     CorePikkuFunctionSessionless<any, any>
@@ -60,7 +54,7 @@ export const wireMCPResource = <
     )
     return
   }
-  addFunction(mcpResourceMeta.pikkuFuncId, mcpResource.func as any)
+  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}`)
@@ -83,7 +77,7 @@ export const wireMCPPrompt = <
     )
     return
   }
-  addFunction(mcpPromptMeta.pikkuFuncId, mcpPrompt.func as any)
+  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}`)
@@ -293,10 +287,6 @@ async function runMCPPikkuFunc(
   }
 }
 
-export const getMCPResources = () => {
-  return pikkuState(null, 'mcp', 'resources')
-}
-
 export const getMCPResourcesMeta = () => {
   return pikkuState(null, 'mcp', 'resourcesMeta')
 }
@@ -305,10 +295,6 @@ export const getMCPToolsMeta = () => {
   return pikkuState(null, 'mcp', 'toolsMeta')
 }
 
-export const getMCPPrompts = () => {
-  return pikkuState(null, 'mcp', 'prompts')
-}
-
 export const getMCPPromptsMeta = () => {
   return pikkuState(null, 'mcp', 'promptsMeta')
 }

package/src/wirings/persona/persona-environments.test.ts

@@ -44,7 +44,11 @@ describe('resolvePersonaEnvironments', () => {
 describe('personaEnvironmentErrors', () => {
   test('a persona that declares nothing cannot be wrong', () => {
     assert.deepEqual(
-      personaEnvironmentErrors('shopper', { disposition: 'careless' }, ENVIRONMENTS),
+      personaEnvironmentErrors(
+        'shopper',
+        { disposition: 'careless' },
+        ENVIRONMENTS
+      ),
       []
     )
   })
@@ -106,8 +110,15 @@ describe('personaEnvironmentErrors', () => {
   })
 
   test('with nothing configured it says where environments go', () => {
-    const [error] = personaEnvironmentErrors('shopper', { environments: ['x'] }, {})
-    assert.match(error!, /Declare it under 'environments' in pikku\.config\.json/)
+    const [error] = personaEnvironmentErrors(
+      'shopper',
+      { environments: ['x'] },
+      {}
+    )
+    assert.match(
+      error!,
+      /Declare it under 'environments' in pikku\.config\.json/
+    )
   })
 })
 

package/src/wirings/persona/persona.test.ts

@@ -23,7 +23,10 @@ describe('computed addresses', () => {
   })
 
   test('without a run id the address is the stable, seedable form', () => {
-    assert.equal(personaEmail('susan', 'mail.example.com'), 'susan@mail.example.com')
+    assert.equal(
+      personaEmail('susan', 'mail.example.com'),
+      'susan@mail.example.com'
+    )
   })
 
   test('an id that is not address-shaped is reduced to one', () => {
@@ -34,7 +37,10 @@ describe('computed addresses', () => {
   })
 
   test('an id with nothing usable in it is refused rather than guessed at', () => {
-    assert.throws(() => personaEmail('...', 'example.com'), /no usable email label/)
+    assert.throws(
+      () => personaEmail('...', 'example.com'),
+      /no usable email label/
+    )
   })
 
   // A synthetic domain was rejected precisely because it makes every
@@ -97,7 +103,11 @@ describe('verifying roles at sign-in', () => {
   })
 
   test('order and duplication are not drift', () => {
-    const v = verifyPersonaRoles('yasser', ['admin', 'buyer'], ['buyer', 'admin', 'buyer'])
+    const v = verifyPersonaRoles(
+      'yasser',
+      ['admin', 'buyer'],
+      ['buyer', 'admin', 'buyer']
+    )
     assert.equal(v.ok, true)
   })
 

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

@@ -1,4 +1,8 @@
-import type { PersonaDefinitions, PersonaMeta, PersonasMeta } from './persona.types.js'
+import type {
+  PersonaDefinitions,
+  PersonaMeta,
+  PersonasMeta,
+} from './persona.types.js'
 
 /**
  * Whether a persona can actually be driven by a virtual user.

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

@@ -58,7 +58,7 @@ export const wireQueueWorker = <
     func: queueWorker.func.func,
     auth: queueWorker.func.auth,
     permissions: queueWorker.func.permissions,
-    middleware: queueWorker.func.middleware as any,
+    middleware: queueWorker.func.middleware,
     tags: queueWorker.func.tags,
   })
 

package/src/wirings/rpc/addon-auth-tags.test.ts

@@ -8,11 +8,7 @@ import {
   clearMiddlewareCache,
 } from '../../middleware-runner.js'
 import { ForbiddenError } from '../../errors/errors.js'
-import {
-  resolveAddonAuth,
-  resolveAddonTags,
-  wireAddon,
-} from './wire-addon.js'
+import { resolveAddonAuth, resolveAddonTags, wireAddon } from './wire-addon.js'
 
 const ADDON_PACKAGE = '@addon/console'
 

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

@@ -13,6 +13,14 @@ import { PikkuError, addError } from '../../errors/error-handler.js'
 import type { PikkuRPC, ResolvedFunction } from './rpc-types.js'
 import { parseVersionedId } from '../../version.js'
 import { resolveRemoteAddonToken } from './remote-addon-auth.js'
+import { createAgentRPC } from '../ai-agent/agent-rpc.js'
+
+/**
+ * The session for a wire: read through `getSession` when a runner attached one,
+ * otherwise whatever was placed on the wire directly.
+ */
+const resolveWireSession = async (wire: PikkuRawWire) =>
+  typeof wire.getSession === 'function' ? await wire.getSession() : wire.session
 
 export class RPCNotFoundError extends PikkuError {
   public readonly rpcName: string
@@ -55,16 +63,6 @@ addError(RemoteAddonRequestError, {
   status: 502,
   message: 'Remote addon request failed.',
 })
-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, resumeAIAgentSync } from '../ai-agent/ai-agent-runner.js'
-import {
-  streamAIAgent,
-  resumeAIAgent,
-  interruptAIAgent,
-} from '../ai-agent/ai-agent-stream.js'
-import { wrapChannelWithAGUI } from '../ai-agent/ai-agent-agui.js'
 
 export const resolveNamespace = (
   namespacedFunction: string
@@ -209,10 +207,7 @@ export class ContextAwareRPCService {
     } catch (e) {
       if (e instanceof RPCNotFoundError) {
         if (this.services.deploymentService) {
-          const session =
-            this.wire.getSession && typeof this.wire.getSession === 'function'
-              ? await this.wire.getSession()
-              : (this.wire as any).session
+          const session = await resolveWireSession(this.wire)
           return this.services.deploymentService.invoke(
             funcName,
             data,
@@ -405,10 +400,7 @@ export class ContextAwareRPCService {
       resolved = resolvePikkuFunction(rpcName, this.packageName)
     } catch (e) {
       if (e instanceof RPCNotFoundError && this.services.deploymentService) {
-        const session =
-          this.wire.getSession && typeof this.wire.getSession === 'function'
-            ? await this.wire.getSession()
-            : (this.wire as any).session
+        const session = await resolveWireSession(this.wire)
         return this.services.deploymentService.invoke(
           rpcName,
           data,
@@ -462,108 +454,15 @@ export class ContextAwareRPCService {
     )
   }
 
-  public get agent() {
-    return {
-      run: async (agentName: string, input: AIAgentInput) => {
-        const result = await runAIAgent(agentName, input, {
-          sessionService: this.options.sessionService,
-          getCredential: this.wire.getCredential?.bind(this.wire),
-        })
-        return {
-          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
-          model?: string
-          temperature?: number
-        },
-        options?: StreamAIAgentOptions
-      ) => {
-        const channel = this.wire.channel as unknown as AIStreamChannel
-        if (!channel) throw new Error('No channel available for streaming')
-        let currentRunId: string | undefined
-        await streamAIAgent(
-          agentName,
-          input,
-          wrapChannelWithAGUI(channel, {
-            threadId: input.threadId,
-            getRunId: () => currentRunId,
-          }),
-          {
-            sessionService: this.options.sessionService,
-            getCredential: this.wire.getCredential?.bind(this.wire),
-          },
-          undefined,
-          {
-            ...options,
-            onRunCreated: (runId) => {
-              currentRunId = runId
-              options?.onRunCreated?.(runId)
-            },
-          }
-        )
-      },
-      resume: async (
-        runId: string,
-        input: { toolCallId: string; approved: boolean },
-        options?: StreamAIAgentOptions
-      ) => {
-        const channel = this.wire.channel as unknown as AIStreamChannel
-        if (!channel) throw new Error('No channel available for streaming')
-        await resumeAIAgent(
-          { runId, ...input },
-          wrapChannelWithAGUI(channel, { runId }),
-          {
-            sessionService: this.options.sessionService,
-            getCredential: this.wire.getCredential?.bind(this.wire),
-          },
-          options
-        )
-      },
-      interrupt: async (
-        runId: string,
-        reason?: 'speech' | 'user' | 'timeout'
-      ) => {
-        return interruptAIAgent(
-          { runId, ...(reason ? { reason } : {}) },
-          { sessionService: this.options.sessionService }
-        )
-      },
-      approve: async (
-        runId: string,
-        approvals: { toolCallId: string; approved: boolean }[],
-        expectedAgentName?: string
-      ) => {
-        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,
-          }),
-        }
-      },
-    }
+  /**
+   * The agent facade, built on access.
+   *
+   * The implementation lives in `ai-agent/agent-rpc.ts` so the agent surface is
+   * one file rather than a wing of this one; a getter rather than a field so a
+   * request that never touches an agent never builds it.
+   */
+  public get agent(): PikkuRPC['agent'] {
+    return createAgentRPC(this.wire, this.options)
   }
 
   public async remote<In = any, Out = any>(
@@ -577,10 +476,7 @@ export class ContextAwareRPCService {
       )
     }
 
-    const session =
-      this.wire.getSession && typeof this.wire.getSession === 'function'
-        ? await this.wire.getSession()
-        : (this.wire as any).session
+    const session = await resolveWireSession(this.wire)
 
     return this.services.deploymentService.invoke(
       funcName,
@@ -619,18 +515,44 @@ export class PikkuRPCService<
       options,
       packageName
     )
-    return {
-      depth,
-      global: false,
-      invoke: serviceRPC.rpc.bind(serviceRPC),
-      remote: serviceRPC.remote.bind(serviceRPC),
-      exposed: serviceRPC.rpcExposed.bind(serviceRPC),
-      startWorkflow: serviceRPC.startWorkflow.bind(serviceRPC),
-      get agent() {
-        return serviceRPC.agent
-      },
-      rpcWithWire: serviceRPC.rpcWithWire.bind(serviceRPC),
-    } as any
+    // `TypedRPC` is named by the caller from its generated RPC map. Nothing
+    // concrete can satisfy a type the caller has not chosen yet.
+    return new ContextRPCView(serviceRPC, depth) as TypedRPC
+  }
+}
+
+/**
+ * The per-invocation `wire.rpc`.
+ *
+ * A class rather than an object literal because `agent` has to stay lazy — most
+ * requests never touch it — and an accessor declared on an object literal is
+ * defined per instance, which drops the literal off V8's fast construction
+ * path. Measured at ~1.15µs per request as a literal against ~0.47µs here, on
+ * the hot path every request takes.
+ *
+ * knowledge: decisions/internals/the-per-invocation-rpc-view-is-a-class.md
+ */
+class ContextRPCView {
+  public readonly global = false
+  public readonly invoke: ContextAwareRPCService['rpc']
+  public readonly remote: ContextAwareRPCService['remote']
+  public readonly exposed: ContextAwareRPCService['rpcExposed']
+  public readonly startWorkflow: ContextAwareRPCService['startWorkflow']
+  public readonly rpcWithWire: ContextAwareRPCService['rpcWithWire']
+
+  constructor(
+    private readonly serviceRPC: ContextAwareRPCService,
+    public readonly depth: number
+  ) {
+    this.invoke = serviceRPC.rpc.bind(serviceRPC)
+    this.remote = serviceRPC.remote.bind(serviceRPC)
+    this.exposed = serviceRPC.rpcExposed.bind(serviceRPC)
+    this.startWorkflow = serviceRPC.startWorkflow.bind(serviceRPC)
+    this.rpcWithWire = serviceRPC.rpcWithWire.bind(serviceRPC)
+  }
+
+  get agent() {
+    return this.serviceRPC.agent
   }
 }
 

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

@@ -1,3 +1,4 @@
+import type { PikkuRawWire } from '../../types/core.types.js'
 import type { AgentInterruptResult } from '../ai-agent/ai-agent-interrupt.js'
 
 export type PikkuRPC<
@@ -12,6 +13,12 @@ export type PikkuRPC<
   invoke: Invoke
   remote: Remote
   exposed: (name: string, data: any) => Promise<any>
+  /** Invoke an RPC with explicit wire fields merged over the caller's. */
+  rpcWithWire: <In = any, Out = any>(
+    rpcName: string,
+    data: In,
+    wire: PikkuRawWire
+  ) => Promise<Out>
   startWorkflow: startWorkflow
   agent: {
     run: AgentRun

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

@@ -61,7 +61,9 @@ const governingAddonConfigs = (
     }
   }
 
-  return [...addons.values()].filter((config) => config?.package === packageName)
+  return [...addons.values()].filter(
+    (config) => config?.package === packageName
+  )
 }
 
 const unionOf = (

package/src/wirings/secret/validate-secret-definitions.test.ts

@@ -22,6 +22,28 @@ describe('validateAndBuildSecretDefinitionsMeta', () => {
     assert.strictEqual(result['stripe'].displayName, 'Stripe')
   })
 
+  test('carries allowedHosts into the meta so the egress binding is enforced', () => {
+    const definitions = [
+      {
+        name: 'notion',
+        displayName: 'Notion',
+        secretId: 'NOTION_KEY',
+        allowedHosts: ['api.notion.com', '*.notion.com'],
+        sourceFile: 'a.ts',
+      },
+    ]
+    const result = validateAndBuildSecretDefinitionsMeta(
+      definitions as any,
+      new Map()
+    )
+    // assertSecretAllowedForHost reads allowedHosts off this meta; if it is
+    // dropped here the host binding silently permits every host.
+    assert.deepStrictEqual(result['notion']!.allowedHosts, [
+      'api.notion.com',
+      '*.notion.com',
+    ])
+  })
+
   test('should allow duplicate secretId with same schema', () => {
     const schemaLookup = new Map([
       ['schema1', { variableName: 'Schema', sourceFile: 'types.ts' }],

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

@@ -56,8 +56,8 @@ export function validateAndBuildSecretDefinitionsMeta(
           schema: def.schema,
           oauth2: def.oauth2,
           rotationPeriod: def.rotationPeriod,
-          docsUrl: def.docsUrl,
           allowedHosts: def.allowedHosts,
+          docsUrl: def.docsUrl,
           sourceFile: def.sourceFile,
         }
       }
@@ -75,8 +75,8 @@ export function validateAndBuildSecretDefinitionsMeta(
         schema: def.schema,
         oauth2: def.oauth2,
         rotationPeriod: def.rotationPeriod,
-        docsUrl: def.docsUrl,
         allowedHosts: def.allowedHosts,
+        docsUrl: def.docsUrl,
         sourceFile: def.sourceFile,
       }
     }

package/src/wirings/trigger/pikku-trigger-service.ts

@@ -14,11 +14,6 @@ export type TriggerTarget = {
   startNode?: string
 }
 
-export type TriggerSourceInfo = {
-  name: string
-  input: unknown
-}
-
 export abstract class PikkuTriggerService implements TriggerService {
   protected activeTriggers = new Map<string, TriggerInstance>()
 

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

@@ -10,6 +10,7 @@ import {
   getCreateWireServices,
 } from '../../pikku-state.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
+import type { CorePikkuFunctionConfig } from '../../function/functions.types.js'
 import { PikkuMissingMetaError } from '../../errors/errors.js'
 
 export const wireTrigger = (trigger: CoreTrigger) => {
@@ -22,10 +23,10 @@ export const wireTrigger = (trigger: CoreTrigger) => {
     return
   }
 
-  addFunction(triggerMeta.pikkuFuncId, trigger.func as any)
+  addFunction(triggerMeta.pikkuFuncId, trigger.func)
 
   const triggers = pikkuState(null, 'trigger', 'triggers')
-  triggers.set(trigger.name, trigger as any)
+  triggers.set(trigger.name, trigger)
 }
 
 // knowledge: decisions/internals/trigger-declaration-is-split-from-trigger-source.md
@@ -45,11 +46,12 @@ export const wireTriggerSource = <TInput = unknown, TOutput = unknown>(
   if (triggerSources.has(source.name)) {
     throw new Error(`Trigger source already exists: ${source.name}`)
   }
-  triggerSources.set(source.name, source as any)
+  // knowledge: decisions/internals/wiring-registries-erase-the-generics-their-wire-functions-capture.md
+  triggerSources.set(source.name, source as CoreTriggerSource)
 
   addFunction(
     triggerSourceMeta.pikkuFuncId,
-    source.func as any,
+    source.func as CorePikkuFunctionConfig<any, any>,
     triggerSourceMeta.packageName
   )
 }
@@ -94,7 +96,7 @@ export async function setupTrigger<TInput = unknown, TOutput = unknown>({
     singletonServices,
     createWireServices,
     auth: false,
-    data: () => input as any,
+    data: () => input,
     wire,
     packageName: sourceMeta.packageName || null,
   })

package/src/wirings/virtual-user/run-virtual-user.test.ts

@@ -41,7 +41,11 @@ const CATALOGUE: ApiCatalogueEntry[] = [
 ]
 
 const INTENTS: IntentSource[] = [
-  { id: 'onboard', title: 'set up your first project', steps: ['sign in', 'make a project'] },
+  {
+    id: 'onboard',
+    title: 'set up your first project',
+    steps: ['sign in', 'make a project'],
+  },
 ]
 
 const PERSONA = {
@@ -84,10 +88,7 @@ const scripted = (
   return { llm, turns: () => turn }
 }
 
-const respond = <T>(
-  status: number,
-  body: T
-): ScenarioHttpResponse<T> => ({
+const respond = <T>(status: number, body: T): ScenarioHttpResponse<T> => ({
   status,
   ok: status >= 200 && status < 300,
   body,
@@ -126,7 +127,12 @@ describe('running a virtual user', () => {
       { kind: 'complete', summary: 'done' },
     ])
 
-    const result = await runVirtualUser({ ...base, target, llm, budget: { steps: 3 } })
+    const result = await runVirtualUser({
+      ...base,
+      target,
+      llm,
+      budget: { steps: 3 },
+    })
 
     // The first attempt cost a step and bought the schema; only the second
     // reached the server.
@@ -355,7 +361,9 @@ describe('what a virtual user reports', () => {
   })
 
   test('an app-specific oracle can add what the engine cannot know', async () => {
-    const target = recordingTarget(() => respond(200, { orgId: 'someone-else' }))
+    const target = recordingTarget(() =>
+      respond(200, { orgId: 'someone-else' })
+    )
     const { llm } = scripted(walkTo('listProjects'))
 
     const result = await runVirtualUser({
@@ -595,8 +603,9 @@ describe('goals and persona', () => {
   test('goals in the user’s own words become intents alongside the derived ones', async () => {
     const seen: string[] = []
     const target = recordingTarget(() => respond(200, {}))
-    const { llm } = scripted([{ kind: 'complete' }, { kind: 'complete' }], (_i, m) =>
-      seen.push(...m)
+    const { llm } = scripted(
+      [{ kind: 'complete' }, { kind: 'complete' }],
+      (_i, m) => seen.push(...m)
     )
 
     const result = await runVirtualUser({