@pikku/core 0.12.79 → 0.12.82

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,
@@ -289,6 +284,8 @@ export class ContextAwareRPCService {
         secretOverrides: resolved.addonConfig?.secretOverrides,
         variableOverrides: resolved.addonConfig?.variableOverrides,
         credentialOverrides: resolved.addonConfig?.credentialOverrides,
+        globalSecrets: resolved.addonConfig?.globalSecrets,
+        globalCredentials: resolved.addonConfig?.globalCredentials,
       },
     }
   }
@@ -405,10 +402,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 +456,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 +478,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 +517,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
@@ -60,6 +67,10 @@ export interface ResolvedFunction {
     secretOverrides?: Record<string, string>
     variableOverrides?: Record<string, string>
     credentialOverrides?: Record<string, string>
+    /** Set by the consuming app: hand this instance the unscoped `SecretService` */
+    globalSecrets?: string
+    /** Set by the consuming app: hand this instance the unscoped `CredentialService` */
+    globalCredentials?: string
     /** Set by `wireRemoteAddon`: dispatch this namespace's RPCs over HTTP */
     remote?: boolean
     serverUrl?: string | ((services: any) => string | Promise<string>)

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

@@ -14,6 +14,19 @@ export type WireAddonConfig = {
   secretOverrides?: Record<string, string>
   variableOverrides?: Record<string, string>
   credentialOverrides?: Record<string, string>
+  /**
+   * Hands this instance the whole `SecretService` instead of one scoped to the
+   * secrets it declared. The value is the reason, recorded in the deploy
+   * manifest — an addon that names secrets at runtime cannot be scoped, and
+   * only the consuming app, never the addon, can grant it.
+   */
+  globalSecrets?: string
+  /**
+   * Hands this instance the whole `CredentialService` instead of one narrowed
+   * to the credentials it declared. The value is the reason, recorded in the
+   * deploy manifest, and only the consuming app can grant it.
+   */
+  globalCredentials?: string
 }
 
 export const wireAddon = (config: WireAddonConfig): void => {
@@ -32,6 +45,10 @@ export const wireAddon = (config: WireAddonConfig): void => {
     ...(config.credentialOverrides
       ? { credentialOverrides: config.credentialOverrides }
       : {}),
+    ...(config.globalSecrets ? { globalSecrets: config.globalSecrets } : {}),
+    ...(config.globalCredentials
+      ? { globalCredentials: config.globalCredentials }
+      : {}),
   })
 }
 
@@ -61,7 +78,9 @@ const governingAddonConfigs = (
     }
   }
 
-  return [...addons.values()].filter((config) => config?.package === packageName)
+  return [...addons.values()].filter(
+    (config) => config?.package === packageName
+  )
 }
 
 const unionOf = (

package/src/wirings/scheduler/index.ts

@@ -7,5 +7,4 @@ export { logSchedulers } from './log-schedulers.js'
 export type {
   CoreScheduledTask,
   ScheduledTasksMeta,
-  PikkuScheduledTask,
 } from './scheduler.types.js'

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/index.ts

@@ -6,5 +6,4 @@ export type {
   CorePikkuTriggerFunction,
   CorePikkuTriggerFunctionConfig,
   CoreTrigger,
-  PikkuTrigger,
 } from './trigger.types.js'

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/index.ts

@@ -18,25 +18,16 @@
  */
 export type {
   ApiCatalogueEntry,
-  IntentRecord,
   IntentSource,
-  IntentStatus,
-  StepRecord,
-  VirtualUserAction,
-  VirtualUserBudget,
   VirtualUserDisposition,
   VirtualUserFinding,
-  VirtualUserFindingKind,
   VirtualUserRunResult,
-  VirtualUserTally,
   VirtualUserTarget,
 } from './virtual-user.types.js'
 export { PRODUCTION_DISPOSITION } from './virtual-user.types.js'
 export {
   runVirtualUser,
-  rememberIds,
   type RunVirtualUserParams,
-  type VirtualUserCallContext,
 } from './run-virtual-user.js'
 export {
   personaScopes,
@@ -57,26 +48,19 @@ export {
 } from './virtual-user-dispositions.js'
 export {
   catalogueClassification,
-  catalogueIndex,
   catalogueLookup,
-  describeEntry,
   isReadOnly,
   reachableCatalogue,
-  renderCatalogue,
   unreachableCatalogue,
 } from './virtual-user-catalogue.js'
 export {
-  reachableAgents,
   type AgentReachability,
   type ReachableAgent,
 } from './virtual-user-agents.js'
 export {
   IntentStack,
   intentsForPersona,
-  type IntentMove,
-  type ScheduledTick,
 } from './virtual-user-intents.js'
-export { createRng, type VirtualUserRng } from './virtual-user-rng.js'
 export {
   deriveCatalogue,
   deriveIntents,

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({

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

@@ -143,8 +143,12 @@ const msg = (role: AIMessage['role'], content: string): AIMessage => ({
 })
 
 /** Read a structured result, falling back to parsing JSON out of the text. */
-const readObject = <T>(result: { object?: unknown; text?: string }): T | null => {
-  if (result.object && typeof result.object === 'object') return result.object as T
+const readObject = <T>(result: {
+  object?: unknown
+  text?: string
+}): T | null => {
+  if (result.object && typeof result.object === 'object')
+    return result.object as T
   if (result.text) {
     try {
       return JSON.parse(result.text) as T
@@ -201,7 +205,11 @@ export const rememberIds = (
     return into
   }
   for (const [key, value] of Object.entries(body)) {
-    if (typeof value === 'string' && MEMORABLE.test(key) && value.length < 200) {
+    if (
+      typeof value === 'string' &&
+      MEMORABLE.test(key) &&
+      value.length < 200
+    ) {
       into[key] = value
     } else if (typeof value === 'object') {
       rememberIds(value, into, depth + 1)
@@ -237,7 +245,10 @@ const personaInstructions = (
     '',
     agents.length
       ? `Assistants you can talk to:\n${agents
-          .map((agent) => `- ${agent.name}${agent.description ? `: ${agent.description}` : ''}`)
+          .map(
+            (agent) =>
+              `- ${agent.name}${agent.description ? `: ${agent.description}` : ''}`
+          )
           .join('\n')}`
       : '',
     fixtures.length ? `Files you have: ${fixtures.join(', ')}` : '',
@@ -351,7 +362,10 @@ export const runVirtualUser = async (
       stoppedBy = 'budget-duration'
       break
     }
-    if (budget?.mutations !== undefined && tally.mutations >= budget.mutations) {
+    if (
+      budget?.mutations !== undefined &&
+      tally.mutations >= budget.mutations
+    ) {
       stoppedBy = 'budget-mutations'
       break
     }
@@ -402,10 +416,7 @@ export const runVirtualUser = async (
         )
       )
     }
-    // Whether this user trusts its notes this turn or goes and looks again.
-    // `stale` almost always trusts them, a newcomer has none to trust, and an
-    // auditor checks nearly everything — which is the whole difference between
-    // those runs, expressed as one roll rather than as prose.
+    // knowledge: decisions/internals/a-virtual-user-decides-whether-to-trust-memory-once-per-turn.md
     if (Object.keys(memory).length && !rng.chance(profile.reReadRate)) {
       messages.push(
         msg(
@@ -448,7 +459,9 @@ export const runVirtualUser = async (
 
     if (!raw || typeof raw.kind !== 'string') {
       steps.push(record)
-      messages.push(msg('user', 'That was not a valid action. Choose one action.'))
+      messages.push(
+        msg('user', 'That was not a valid action. Choose one action.')
+      )
       continue
     }
 
@@ -550,10 +563,7 @@ export const runVirtualUser = async (
       continue
     }
 
-    // What may be called is decided once, when the catalogue is narrowed: a
-    // read-only disposition is never offered a mutation and an approval-gated
-    // endpoint is never offered at all, so `index` is the gate and there is no
-    // second one here to drift out of step with it.
+    // knowledge: decisions/internals/the-virtual-user-catalogue-is-the-only-gate-on-what-may-be-called.md
     const mutating = !isReadOnly(entry)
 
     const args = readArgs((action as { args?: unknown }).args)
@@ -566,7 +576,10 @@ export const runVirtualUser = async (
       try {
         response = await target.call(entry.name, args)
       } catch (error) {
-        record.findingKinds = [...(record.findingKinds ?? []), 'transport-error']
+        record.findingKinds = [
+          ...(record.findingKinds ?? []),
+          'transport-error',
+        ]
         addFinding({
           kind: 'transport-error',
           detail: `${entry.name} threw: ${(error as Error).message}`,

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

@@ -45,7 +45,10 @@ describe('reachableAgents', () => {
 
   test('carries the description through, which is what the model chooses on', () => {
     const [router] = reachableAgents(AGENTS, ['content:write'])
-    assert.equal(router!.description, 'Routes requests to the right domain agent')
+    assert.equal(
+      router!.description,
+      'Routes requests to the right domain agent'
+    )
   })
 
   test('omits description rather than passing undefined', () => {