@pikku/core 0.12.72 → 0.12.77

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

@@ -27,7 +27,6 @@ addError(RPCNotFoundError, {
   message: 'RPC function not found.',
 })
 
-/** A `wireRemoteAddon` namespace is missing a usable `serverUrl`. */
 export class RemoteAddonConfigError extends PikkuError {
   constructor(namespace: string, detail: string) {
     super(`Remote addon '${namespace}' is misconfigured: ${detail}`)
@@ -38,7 +37,6 @@ addError(RemoteAddonConfigError, {
   message: 'Remote addon is misconfigured.',
 })
 
-/** The hosted addon returned a non-2xx response for a remote RPC. */
 export class RemoteAddonRequestError extends PikkuError {
   public readonly httpStatus: number
   constructor(
@@ -61,13 +59,13 @@ 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 } from '../ai-agent/ai-agent-stream.js'
+import {
+  streamAIAgent,
+  resumeAIAgent,
+  interruptAIAgent,
+} from '../ai-agent/ai-agent-stream.js'
 import { wrapChannelWithAGUI } from '../ai-agent/ai-agent-agui.js'
 
-/**
- * Resolve a namespaced function reference to package and function names
- * Uses pikkuState to look up the namespace -> package mapping
- */
 export const resolveNamespace = (
   namespacedFunction: string
 ): ResolvedFunction | null => {
@@ -92,18 +90,10 @@ export const resolveNamespace = (
   }
 }
 
-/**
- * Resolve a bare (non-namespaced) RPC name to its pikkuFuncId, preferring
- * the caller's addon package when provided. Returns the function name plus
- * the package scope that resolved it (null = root), so callers can thread
- * the scope into runPikkuFunc without a second lookup.
- */
 const resolvePikkuFunction = (
   rpcName: string,
   packageName: string | null = null
 ): { pikkuFuncId: string; packageName: string | null } => {
-  // Addon-scoped calls: try the caller's package function meta first.
-  // (RPC meta only lives in root; addon functions are registered under their package.)
   if (packageName) {
     const pkgFunctions = pikkuState(packageName, 'function', 'meta')
     const pkgMeta = pkgFunctions?.[rpcName]
@@ -135,7 +125,30 @@ const resolvePikkuFunction = (
   return { pikkuFuncId: rpcMeta, packageName: null }
 }
 
-// Context-aware RPC client for use within services
+/**
+ * Marks an addon RPC name that could not be resolved. Module-private on purpose:
+ * resolution failure must never be conflated with an `RPCNotFoundError` thrown by
+ * a function that already started executing, and it must never escape to callers.
+ */
+const NOT_RESOLVED = Symbol('pikku:rpc-not-resolved')
+
+type AddonCall =
+  | {
+      kind: 'remote'
+      namespace: string
+      fnName: string
+      addonConfig: ResolvedFunction['addonConfig']
+    }
+  | {
+      kind: 'local'
+      namespacedFunction: string
+      packageName: string
+      pikkuFuncId: string
+      auth: boolean | undefined
+      tags: string[]
+      addonInstance: AddonInstance
+    }
+
 export class ContextAwareRPCService {
   constructor(
     private services: CoreServices,
@@ -179,48 +192,22 @@ export class ContextAwareRPCService {
       ...this.wire,
     }
 
-    // Check addon namespace first (e.g. 'stripe:createCharge')
     if (funcName.includes(':')) {
-      try {
-        return await this.invokeAddonFunction<In, Out>(
-          funcName,
+      const addonCall = this.resolveAddonFunction(funcName)
+      if (addonCall !== NOT_RESOLVED) {
+        return await this.executeAddonFunction<In, Out>(
+          addonCall,
           data,
           updatedWire
         )
-      } catch (addonErr) {
-        if (!(addonErr instanceof RPCNotFoundError)) throw addonErr
-        // Not an addon — fall through to local lookup
       }
     }
 
-    // Bare name: resolve via caller's package scope first (if any), then root.
-    // Note: intra-addon bare calls do NOT re-apply the addon's external
-    // addonConfig.auth/tags — those gates are only applied on the external
-    // 'namespace:func' boundary via invokeAddonFunction.
+    let resolved: { pikkuFuncId: string; packageName: string | null }
     try {
-      const resolved = resolvePikkuFunction(funcName, this.packageName)
-      const addonInstance = resolved.packageName
-        ? addonInstanceForNamespace(
-            this.wire.addonNamespace,
-            resolved.packageName
-          )
-        : undefined
-      return await runPikkuFunc<In, Out>(
-        'rpc',
-        funcName,
-        resolved.pikkuFuncId,
-        {
-          auth: this.options.requiresAuth,
-          singletonServices: this.services,
-          data: () => data,
-          wire: updatedWire,
-          packageName: resolved.packageName,
-          addonInstance,
-        }
-      )
+      resolved = resolvePikkuFunction(funcName, this.packageName)
     } catch (e) {
       if (e instanceof RPCNotFoundError) {
-        // Fall back to deployment service (e.g. CF service binding, Lambda Invoke)
         if (this.services.deploymentService) {
           const session =
             this.wire.getSession && typeof this.wire.getSession === 'function'
@@ -236,23 +223,34 @@ export class ContextAwareRPCService {
       }
       throw e
     }
+
+    const addonInstance = resolved.packageName
+      ? addonInstanceForNamespace(
+          this.wire.addonNamespace,
+          resolved.packageName
+        )
+      : undefined
+    return await runPikkuFunc<In, Out>('rpc', funcName, resolved.pikkuFuncId, {
+      auth: this.options.requiresAuth,
+      singletonServices: this.services,
+      data: () => data,
+      wire: updatedWire,
+      packageName: resolved.packageName,
+      addonInstance,
+    })
   }
 
   /**
-   * Invoke a function from an addon package
-   * Addon packages register their functions in pikkuState under their package name.
-   * The function is executed using the parent services (shared singleton services).
-   * @private
+   * Resolution half of an addon RPC call: never executes anything, so an
+   * `RPCNotFoundError` thrown by the function itself can never be mistaken for
+   * an unresolvable name.
    */
-  private async invokeAddonFunction<In = any, Out = any>(
-    namespacedFunction: string,
-    data: In,
-    wire: PikkuRawWire
-  ): Promise<Out> {
-    // Resolve namespace to package name
+  private resolveAddonFunction(
+    namespacedFunction: string
+  ): AddonCall | typeof NOT_RESOLVED {
     const resolved = resolveNamespace(namespacedFunction)
     if (!resolved) {
-      throw new RPCNotFoundError(namespacedFunction)
+      return NOT_RESOLVED
     }
 
     const namespace = namespacedFunction.slice(
@@ -260,72 +258,81 @@ export class ContextAwareRPCService {
       namespacedFunction.indexOf(':')
     )
 
-    // wireRemoteAddon: the addon ships as a devDependency (types only) and its
-    // handlers run on the host — dispatch over HTTP, not through local meta.
     if (resolved.addonConfig?.remote) {
-      return this.invokeRemoteAddonFunction<In, Out>(
+      const addonConfig = pikkuState(null, 'addons', 'packages').get(namespace)
+      if (!addonConfig?.remote) {
+        return NOT_RESOLVED
+      }
+      return {
+        kind: 'remote',
         namespace,
-        resolved.function,
-        data
-      )
+        fnName: resolved.function,
+        addonConfig,
+      }
     }
 
-    // Get the function meta from the addon package
-    // Addon packages use function meta, not RPC meta
     const addonFunctionMeta = pikkuState(resolved.package, 'function', 'meta')
     const funcMeta = addonFunctionMeta[resolved.function]
     if (!funcMeta) {
-      throw new RPCNotFoundError(namespacedFunction)
-    }
-    const funcName = funcMeta.pikkuFuncId || resolved.function
-
-    const auth = resolved.addonConfig?.auth ?? this.options.requiresAuth
-    const tags = [
-      ...(resolved.addonConfig?.tags ?? []),
-      ...(funcMeta.tags ?? []),
-    ]
-
-    // The namespace is the consumer-facing wireAddon name; it selects the
-    // per-instance singleton services and secret/variable/credential overrides.
-    const addonInstance: AddonInstance = {
-      namespace,
-      secretOverrides: resolved.addonConfig?.secretOverrides,
-      variableOverrides: resolved.addonConfig?.variableOverrides,
-      credentialOverrides: resolved.addonConfig?.credentialOverrides,
+      return NOT_RESOLVED
     }
 
-    // Execute the function using runPikkuFunc with the addon package's state
-    // We use the parent services (this.services) since addon packages share services
-    // Pass the function's tags so tag-based middleware/permissions are applied
-    return runPikkuFunc<In, Out>('rpc', namespacedFunction, funcName, {
-      auth,
-      singletonServices: this.services,
-      data: () => data,
-      wire,
+    return {
+      kind: 'local',
+      namespacedFunction,
       packageName: resolved.package,
-      tags,
-      addonInstance,
-    })
+      pikkuFuncId: funcMeta.pikkuFuncId || resolved.function,
+      auth: resolved.addonConfig?.auth ?? this.options.requiresAuth,
+      tags: [...(resolved.addonConfig?.tags ?? []), ...(funcMeta.tags ?? [])],
+      addonInstance: {
+        namespace,
+        secretOverrides: resolved.addonConfig?.secretOverrides,
+        variableOverrides: resolved.addonConfig?.variableOverrides,
+        credentialOverrides: resolved.addonConfig?.credentialOverrides,
+      },
+    }
   }
 
   /**
-   * Dispatch a `wireRemoteAddon` RPC over HTTP to the hosting service.
-   *
-   * The consumer sends the addon's own function name (not the namespaced form)
-   * to the host's `/remote/rpc/:rpcName` endpoint, authenticating as a client
-   * with the token bound in `wireRemoteAddon({ auth })`. The addon's handlers
-   * live on the host, so there is no local function meta to resolve.
+   * Execution half of an addon RPC call. Must never be called from inside a
+   * `try` that catches `RPCNotFoundError`.
    */
+  private async executeAddonFunction<In = any, Out = any>(
+    addonCall: AddonCall,
+    data: In,
+    wire: PikkuRawWire
+  ): Promise<Out> {
+    if (addonCall.kind === 'remote') {
+      return this.invokeRemoteAddonFunction<In, Out>(
+        addonCall.namespace,
+        addonCall.fnName,
+        data,
+        addonCall.addonConfig
+      )
+    }
+
+    return runPikkuFunc<In, Out>(
+      'rpc',
+      addonCall.namespacedFunction,
+      addonCall.pikkuFuncId,
+      {
+        auth: addonCall.auth,
+        singletonServices: this.services,
+        data: () => data,
+        wire,
+        packageName: addonCall.packageName,
+        tags: addonCall.tags,
+        addonInstance: addonCall.addonInstance,
+      }
+    )
+  }
+
   private async invokeRemoteAddonFunction<In = any, Out = any>(
     namespace: string,
     fnName: string,
-    data: In
+    data: In,
+    cfg: ResolvedFunction['addonConfig']
   ): Promise<Out> {
-    const cfg = pikkuState(null, 'addons', 'packages').get(namespace)
-    if (!cfg?.remote) {
-      throw new RPCNotFoundError(`${namespace}:${fnName}`)
-    }
-
     const serverUrl =
       typeof cfg.serverUrl === 'function'
         ? await cfg.serverUrl(this.services)
@@ -364,7 +371,6 @@ export class ContextAwareRPCService {
     )
 
     if (!res.ok) {
-      // Best-effort body read to enrich the thrown error (mirrors postRpc).
       const detail = (await res.text().catch(() => '')).slice(0, 300)
       throw new RemoteAddonRequestError(namespace, remoteFn, res.status, detail)
     }
@@ -387,25 +393,16 @@ export class ContextAwareRPCService {
     }
 
     if (rpcName.includes(':')) {
-      return this.invokeAddonFunction<In, Out>(rpcName, data, mergedWire)
+      const addonCall = this.resolveAddonFunction(rpcName)
+      if (addonCall === NOT_RESOLVED) {
+        throw new RPCNotFoundError(rpcName)
+      }
+      return this.executeAddonFunction<In, Out>(addonCall, data, mergedWire)
     }
 
+    let resolved: { pikkuFuncId: string; packageName: string | null }
     try {
-      const resolved = resolvePikkuFunction(rpcName, this.packageName)
-      const addonInstance = resolved.packageName
-        ? addonInstanceForNamespace(
-            this.wire.addonNamespace,
-            resolved.packageName
-          )
-        : undefined
-      return await runPikkuFunc<In, Out>('rpc', rpcName, resolved.pikkuFuncId, {
-        auth: this.options.requiresAuth,
-        singletonServices: this.services,
-        data: () => data,
-        wire: mergedWire,
-        packageName: resolved.packageName,
-        addonInstance,
-      })
+      resolved = resolvePikkuFunction(rpcName, this.packageName)
     } catch (e) {
       if (e instanceof RPCNotFoundError && this.services.deploymentService) {
         const session =
@@ -421,6 +418,21 @@ export class ContextAwareRPCService {
       }
       throw e
     }
+
+    const addonInstance = resolved.packageName
+      ? addonInstanceForNamespace(
+          this.wire.addonNamespace,
+          resolved.packageName
+        )
+      : undefined
+    return await runPikkuFunc<In, Out>('rpc', rpcName, resolved.pikkuFuncId, {
+      auth: this.options.requiresAuth,
+      singletonServices: this.services,
+      data: () => data,
+      wire: mergedWire,
+      packageName: resolved.packageName,
+      addonInstance,
+    })
   }
 
   public async startWorkflow<In = any>(
@@ -519,6 +531,15 @@ export class ContextAwareRPCService {
           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 }[],
@@ -570,12 +591,10 @@ export class ContextAwareRPCService {
   }
 }
 
-// RPC Service class for the global interface
 export class PikkuRPCService<
   Services extends CoreServices,
   TypedRPC = PikkuRPC,
 > {
-  // Convenience function for initializing
   getContextRPCService(
     services: Services,
     wire: PikkuRawWire,
@@ -615,5 +634,4 @@ export class PikkuRPCService<
   }
 }
 
-// Create a singleton instance
 export const rpcService = new PikkuRPCService()

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

@@ -1,3 +1,5 @@
+import type { AgentInterruptResult } from '../ai-agent/ai-agent-interrupt.js'
+
 export type PikkuRPC<
   Invoke extends (...args: any[]) => any = (...args: any[]) => any,
   Remote extends (...args: any[]) => any = (...args: any[]) => any,
@@ -24,6 +26,15 @@ export type PikkuRPC<
       approvals: { toolCallId: string; approved: boolean }[],
       expectedAgentName?: string
     ) => Promise<any>
+    /** Stop an in-flight run. Needs no channel — it ends a stream rather than
+     *  continuing one — so it is reachable over a plain RPC while the stream
+     *  itself is held open elsewhere. Resolves `stopped: false` when there was
+     *  nothing left to stop, and names any tools still executing — their side
+     *  effects have already happened and are not undone by interrupting. */
+    interrupt: (
+      runId: string,
+      reason?: 'speech' | 'user' | 'timeout'
+    ) => Promise<AgentInterruptResult>
   }
 }
 
@@ -33,17 +44,11 @@ export type RPCMeta = {
   remote?: boolean
 }
 
-/**
- * Type for RPC handlers
- */
 export interface RPCHandler<Input, Output> {
   input: Input
   output: Output
 }
 
-/**
- * Resolved function reference from namespace
- */
 export interface ResolvedFunction {
   package: string
   function: string

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

@@ -2,7 +2,7 @@ import { beforeEach, describe, test } from 'node:test'
 import assert from 'node:assert/strict'
 
 import { resetPikkuState, pikkuState } from '../../pikku-state.js'
-import { wireAddon } from './wire-addon.js'
+import { resolveAddonScopes, wireAddon } from './wire-addon.js'
 
 beforeEach(() => {
   resetPikkuState()
@@ -17,6 +17,7 @@ describe('wireAddon', () => {
       auth: true,
       mcp: true,
       tags: ['payments', 'billing'],
+      scopes: ['admin'],
       secretOverrides: { apiKey: 'STRIPE_API_KEY' },
       variableOverrides: { region: 'AWS_REGION' },
       credentialOverrides: { oauth: 'stripeOAuth' },
@@ -27,6 +28,7 @@ describe('wireAddon', () => {
       rpcEndpoint: 'https://rpc.example.com',
       auth: true,
       tags: ['payments', 'billing'],
+      scopes: ['admin'],
       secretOverrides: { apiKey: 'STRIPE_API_KEY' },
       variableOverrides: { region: 'AWS_REGION' },
       credentialOverrides: { oauth: 'stripeOAuth' },
@@ -57,4 +59,44 @@ describe('wireAddon', () => {
       tags: ['new'],
     })
   })
+
+  test('omits scopes entirely when none are declared', () => {
+    wireAddon({ name: 'stripe', package: '@addon/stripe' })
+
+    assert.equal(
+      'scopes' in pikkuState(null, 'addons', 'packages').get('stripe')!,
+      false
+    )
+  })
+})
+
+describe('resolveAddonScopes', () => {
+  test('returns nothing for a package that is not a wired addon', () => {
+    wireAddon({ name: 'stripe', package: '@addon/stripe', scopes: ['admin'] })
+
+    assert.deepEqual(resolveAddonScopes('@addon/other'), [])
+    assert.deepEqual(resolveAddonScopes(null), [])
+  })
+
+  test('reads the scopes of the named namespace', () => {
+    wireAddon({ name: 'live', package: '@addon/stripe', scopes: ['admin'] })
+    wireAddon({ name: 'test', package: '@addon/stripe', scopes: ['sandbox'] })
+
+    assert.deepEqual(resolveAddonScopes('@addon/stripe', 'live'), ['admin'])
+    assert.deepEqual(resolveAddonScopes('@addon/stripe', 'test'), ['sandbox'])
+  })
+
+  test('unions every namespace when the caller has no namespace', () => {
+    wireAddon({ name: 'live', package: '@addon/stripe', scopes: ['admin'] })
+    wireAddon({ name: 'test', package: '@addon/stripe', scopes: ['sandbox'] })
+
+    assert.deepEqual(resolveAddonScopes('@addon/stripe'), ['admin', 'sandbox'])
+  })
+
+  test('falls back to the package union when the namespace names another package', () => {
+    wireAddon({ name: 'live', package: '@addon/stripe', scopes: ['admin'] })
+    wireAddon({ name: 'mail', package: '@addon/mail' })
+
+    assert.deepEqual(resolveAddonScopes('@addon/stripe', 'mail'), ['admin'])
+  })
 })

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

@@ -1,4 +1,6 @@
 import { pikkuState } from '../../pikku-state.js'
+import { getTagGroups } from '../../utils.js'
+import type { CorePikkuMiddleware } from '../../types/core.types.js'
 
 export type WireAddonConfig = {
   name: string
@@ -7,6 +9,8 @@ export type WireAddonConfig = {
   auth?: boolean
   mcp?: boolean
   tags?: string[]
+  /** Required of every function in the addon, on top of the function's own. */
+  scopes?: string[]
   secretOverrides?: Record<string, string>
   variableOverrides?: Record<string, string>
   credentialOverrides?: Record<string, string>
@@ -18,6 +22,7 @@ export const wireAddon = (config: WireAddonConfig): void => {
     rpcEndpoint: config.rpcEndpoint,
     auth: config.auth,
     tags: config.tags,
+    ...(config.scopes ? { scopes: config.scopes } : {}),
     ...(config.secretOverrides
       ? { secretOverrides: config.secretOverrides }
       : {}),
@@ -29,3 +34,97 @@ export const wireAddon = (config: WireAddonConfig): void => {
       : {}),
   })
 }
+
+/**
+ * The addon configs a running function is governed by: the named instance when
+ * the caller resolved one, every instance of the package otherwise.
+ *
+ * knowledge: decisions/security/addon-scopes-are-resolved-where-the-function-runs.md
+ */
+const governingAddonConfigs = (
+  packageName: string | null,
+  namespace?: string
+) => {
+  if (!packageName) {
+    return []
+  }
+
+  const addons = pikkuState(null, 'addons', 'packages')
+  if (!addons) {
+    return []
+  }
+
+  if (namespace) {
+    const config = addons.get(namespace)
+    if (config?.package === packageName) {
+      return [config]
+    }
+  }
+
+  return [...addons.values()].filter((config) => config?.package === packageName)
+}
+
+const unionOf = (
+  packageName: string | null,
+  namespace: string | undefined,
+  field: 'scopes' | 'tags'
+): string[] => {
+  const values = new Set<string>()
+  for (const config of governingAddonConfigs(packageName, namespace)) {
+    for (const value of config[field] ?? []) {
+      values.add(value)
+    }
+  }
+  return [...values]
+}
+
+/**
+ * knowledge: decisions/security/addon-scopes-are-resolved-where-the-function-runs.md
+ */
+export const resolveAddonScopes = (
+  packageName: string | null,
+  namespace?: string
+): string[] => unionOf(packageName, namespace, 'scopes')
+
+/**
+ * knowledge: decisions/security/addon-auth-and-tags-only-tighten.md
+ */
+export const resolveAddonTags = (
+  packageName: string | null,
+  namespace?: string
+): string[] => unionOf(packageName, namespace, 'tags')
+
+/**
+ * True when any governing instance requires a session. `auth: false` is not
+ * honoured here — on a direct wiring it would weaken the wiring's own gate.
+ *
+ * knowledge: decisions/security/addon-auth-and-tags-only-tighten.md
+ */
+export const resolveAddonAuth = (
+  packageName: string | null,
+  namespace?: string
+): boolean =>
+  governingAddonConfigs(packageName, namespace).some(
+    (config) => config.auth === true
+  )
+
+/**
+ * Addon tags name middleware the *consuming app* registered, so they resolve
+ * against the root tag groups rather than the addon package's own.
+ *
+ * knowledge: decisions/security/addon-auth-and-tags-only-tighten.md
+ */
+export const resolveAddonTagMiddleware = (
+  packageName: string | null,
+  namespace?: string
+): CorePikkuMiddleware[] => {
+  const tags = resolveAddonTags(packageName, namespace)
+  if (tags.length === 0) {
+    return []
+  }
+
+  const tagGroups = pikkuState(null, 'middleware', 'tagGroup')
+  return tags.flatMap(
+    (tag) => getTagGroups(tagGroups, tag).flat() as CorePikkuMiddleware[]
+  )
+}