@pikku/core 0.12.63 → 0.12.66

package/src/wirings/rpc/remote-addon-auth.ts

@@ -0,0 +1,69 @@
+import type { CoreServices, PikkuRawWire } from '../../types/core.types.js'
+import { PikkuError, addError } from '../../errors/error-handler.js'
+
+/**
+ * How a `wireRemoteAddon` consumer supplies the token the hosted addon expects.
+ * This is a CLIENT authenticating to a hosted library — not the trusted mesh.
+ */
+export type RemoteAddonAuthBinding =
+  | { credentialId: string }
+  | { secretId: string }
+  | {
+      resolve: (
+        services: CoreServices,
+        wire: PikkuRawWire
+      ) => string | Promise<string>
+    }
+
+/** The addon's auth was bound but the source produced no token — fail closed. */
+export class RemoteAddonAuthError extends PikkuError {
+  public readonly namespace: string
+  constructor(namespace: string, detail: string) {
+    super(`Remote addon '${namespace}' auth could not be resolved: ${detail}`)
+    this.namespace = namespace
+  }
+}
+addError(RemoteAddonAuthError, {
+  status: 401,
+  message: 'Remote addon authentication could not be resolved.',
+})
+
+/**
+ * Resolve the bearer token for a remote addon call from the consumer's bound
+ * source. Returns `null` only when no auth is bound (a public surface).
+ *
+ * Security: the resolved token is never logged or traced; per-user credentials
+ * are read via the wire (scoped to `pikkuUserId`); an empty result fails closed.
+ */
+export async function resolveRemoteAddonToken(
+  auth: RemoteAddonAuthBinding | undefined,
+  services: CoreServices,
+  wire: PikkuRawWire,
+  namespace: string
+): Promise<string | null> {
+  if (!auth) {
+    // No auth bound → the addon declares its remote surface public.
+    return null
+  }
+
+  let token: unknown
+  if ('credentialId' in auth) {
+    if (typeof wire.getCredential !== 'function') {
+      throw new RemoteAddonAuthError(
+        namespace,
+        `credentialId '${auth.credentialId}' requires a wire with credential access`
+      )
+    }
+    token = await wire.getCredential(auth.credentialId)
+  } else if ('secretId' in auth) {
+    token = await services.secrets.getSecret(auth.secretId)
+  } else if (typeof auth.resolve === 'function') {
+    token = await auth.resolve(services, wire)
+  }
+
+  if (token === null || token === undefined || token === '') {
+    throw new RemoteAddonAuthError(namespace, 'resolved token was empty')
+  }
+
+  return String(token)
+}

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

@@ -6,9 +6,13 @@ import { pikkuState, resetPikkuState } from '../../pikku-state.js'
 import {
   ContextAwareRPCService,
   RPCNotFoundError,
+  RemoteAddonRequestError,
   resolveNamespace,
   rpcService,
 } from './rpc-runner.js'
+import { RemoteAddonAuthError } from './remote-addon-auth.js'
+import { wireAddon } from './wire-addon.js'
+import { wireRemoteAddon } from './wire-remote-addon.js'
 
 const createLogger = () => ({
   debug: () => {},
@@ -207,28 +211,12 @@ describe('ContextAwareRPCService.rpc', () => {
       { requiresAuth: true }
     )
 
-    const seenTags: string[][] = []
-    const addonTagGroup = pikkuState('@addon/stripe', 'permissions', 'tagGroup')
-    addonTagGroup['addon-tag'] = [
-      async (_services: any, _data: any, wire: any) => {
-        seenTags.push(['addon-tag', wire.wireType])
-        return true
-      },
-    ] as never
-    addonTagGroup['function-tag'] = [
-      async (_services: any, _data: any, wire: any) => {
-        seenTags.push(['function-tag', wire.wireType])
-        return true
-      },
-    ] as never
-
     const result = await service.rpc('stripe:createCharge', { amount: 10 })
 
     assert.deepEqual(result, {
       data: { amount: 10 },
       auth: 'http',
     })
-    assert.deepEqual(seenTags, [['addon-tag', 'http']])
   })
 
   test('falls back to deploymentService when rpc meta is missing', async () => {
@@ -492,6 +480,321 @@ describe('ContextAwareRPCService.remote', () => {
   })
 })
 
+describe('multi-instance addons', () => {
+  const createSecretService = () => ({
+    getSecret: async (key: string) => `secret:${key}`,
+    hasSecret: async () => true,
+    setSecret: async () => {},
+    deleteSecret: async () => {},
+    getSecrets: async () => ({}),
+  })
+
+  test('resolves per-instance secretOverrides and caches singletons per namespace', async () => {
+    const createdServices: any[] = []
+    pikkuState('@addon/slack', 'package', 'factories', {
+      createSingletonServices: async (_config: any, parent: any) => {
+        const token = await parent.secrets.getSecret('slackToken')
+        const svc = { logger: createLogger(), token }
+        createdServices.push(svc)
+        return svc
+      },
+    } as never)
+    registerFunction(
+      'send',
+      async (services: any) => ({ token: services.token }),
+      {
+        packageName: '@addon/slack',
+      }
+    )
+
+    wireAddon({
+      name: 'slack-marketing',
+      package: '@addon/slack',
+      secretOverrides: { slackToken: 'marketing_secret' },
+    })
+    wireAddon({
+      name: 'slack-support',
+      package: '@addon/slack',
+      secretOverrides: { slackToken: 'support_secret' },
+    })
+
+    const service = new ContextAwareRPCService(
+      createServices({ secrets: createSecretService() }),
+      {} as never,
+      { requiresAuth: false }
+    )
+
+    const marketing = await service.rpc('slack-marketing:send', {})
+    const support = await service.rpc('slack-support:send', {})
+
+    assert.deepEqual(marketing, { token: 'secret:marketing_secret' })
+    assert.deepEqual(support, { token: 'secret:support_secret' })
+    assert.equal(createdServices.length, 2)
+    assert.notEqual(createdServices[0], createdServices[1])
+  })
+
+  test('reuses the same per-namespace singleton across intra-addon sibling calls', async () => {
+    let factoryCalls = 0
+    pikkuState('@addon/slack', 'package', 'factories', {
+      createSingletonServices: async (_config: any, parent: any) => {
+        factoryCalls++
+        return {
+          logger: createLogger(),
+          token: await parent.secrets.getSecret('slackToken'),
+        }
+      },
+    } as never)
+
+    registerFunction(
+      'leaf',
+      async (services: any) => ({ token: services.token }),
+      {
+        packageName: '@addon/slack',
+      }
+    )
+    registerFunction(
+      'root',
+      async (_services: any, _data: any, wire: any) =>
+        wire.rpc.invoke('leaf', {}),
+      { packageName: '@addon/slack' }
+    )
+
+    wireAddon({
+      name: 'slack-marketing',
+      package: '@addon/slack',
+      secretOverrides: { slackToken: 'marketing_secret' },
+    })
+
+    const service = new ContextAwareRPCService(
+      createServices({ secrets: createSecretService() }),
+      {} as never,
+      { requiresAuth: false }
+    )
+
+    const result = await service.rpc('slack-marketing:root', {})
+
+    assert.deepEqual(result, { token: 'secret:marketing_secret' })
+    assert.equal(factoryCalls, 1)
+  })
+
+  test('resolves per-instance credentialOverrides via wire.getCredential', async () => {
+    pikkuState('@addon/slack', 'package', 'factories', {
+      createSingletonServices: async () => ({ logger: createLogger() }),
+    } as never)
+    registerFunction(
+      'whoami',
+      async (_services: any, _data: any, wire: any) => ({
+        cred: await wire.getCredential('slack'),
+      }),
+      { packageName: '@addon/slack' }
+    )
+
+    wireAddon({
+      name: 'slack-marketing',
+      package: '@addon/slack',
+      credentialOverrides: { slack: 'marketing_cred' },
+    })
+    wireAddon({
+      name: 'slack-support',
+      package: '@addon/slack',
+      credentialOverrides: { slack: 'support_cred' },
+    })
+
+    const credentialService = {
+      getAll: async (_userId: string) => ({
+        marketing_cred: { token: 'm' },
+        support_cred: { token: 's' },
+      }),
+    }
+
+    const service = new ContextAwareRPCService(
+      createServices({ credentialService }),
+      { pikkuUserId: 'user-1' } as never,
+      { requiresAuth: false }
+    )
+
+    const marketing = await service.rpc('slack-marketing:whoami', {})
+    const support = await service.rpc('slack-support:whoami', {})
+
+    assert.deepEqual(marketing, { cred: { token: 'm' } })
+    assert.deepEqual(support, { cred: { token: 's' } })
+  })
+})
+
+describe('wireRemoteAddon dispatch', () => {
+  const realFetch = globalThis.fetch
+  let calls: Array<{ url: string; init: any }> = []
+
+  const stubFetch = (
+    response: { status?: number; body?: unknown } = {}
+  ): void => {
+    const { status = 200, body = { ok: true } } = response
+    calls = []
+    globalThis.fetch = (async (url: any, init: any) => {
+      calls.push({ url: String(url), init })
+      return {
+        ok: status >= 200 && status < 300,
+        status,
+        text: async () => (body === undefined ? '' : JSON.stringify(body)),
+      }
+    }) as any
+  }
+
+  const restoreFetch = () => {
+    globalThis.fetch = realFetch
+  }
+
+  const secretService = () =>
+    ({
+      getSecret: async (key: string) => `secret-value-for-${key}`,
+      getSecrets: async () => ({}),
+      hasSecret: async () => true,
+      setSecret: async () => {},
+      deleteSecret: async () => {},
+    }) as never
+
+  test('POSTs to /remote/rpc/<fn> with { rpcName, data } and a platform bearer token', async () => {
+    stubFetch({ body: { echoed: 42 } })
+    try {
+      wireRemoteAddon({
+        name: 'registry',
+        package: '@pikkufabric/addon-registry',
+        serverUrl: 'https://api.example.com/',
+        auth: { secretId: 'REGISTRY_TOKEN' },
+      })
+
+      const service = new ContextAwareRPCService(
+        createServices({ secrets: secretService() }),
+        { traceId: 'trace-r' } as never,
+        {}
+      )
+
+      const result = await service.rpc('registry:getOpenApi', { name: 'stripe' })
+
+      assert.deepEqual(result, { echoed: 42 })
+      assert.equal(calls.length, 1)
+      assert.equal(
+        calls[0]!.url,
+        'https://api.example.com/remote/rpc/getOpenApi'
+      )
+      assert.equal(calls[0]!.init.method, 'POST')
+      assert.deepEqual(JSON.parse(calls[0]!.init.body), {
+        rpcName: 'getOpenApi',
+        data: { name: 'stripe' },
+      })
+      assert.equal(
+        calls[0]!.init.headers.authorization,
+        'Bearer secret-value-for-REGISTRY_TOKEN'
+      )
+      assert.equal(calls[0]!.init.headers['x-trace-id'], 'trace-r')
+    } finally {
+      restoreFetch()
+    }
+  })
+
+  test('resolves a per-user credential token via wire.getCredential', async () => {
+    stubFetch()
+    try {
+      wireRemoteAddon({
+        name: 'registry',
+        package: '@pikkufabric/addon-registry',
+        serverUrl: () => 'https://api.example.com',
+        auth: { credentialId: 'fabricRegistryToken' },
+      })
+
+      const service = new ContextAwareRPCService(
+        createServices(),
+        {
+          pikkuUserId: 'user-9',
+          getCredential: async (name: string) =>
+            name === 'fabricRegistryToken' ? 'user-token-9' : null,
+        } as never,
+        {}
+      )
+
+      await service.rpc('registry:getOpenApi', {})
+      assert.equal(
+        calls[0]!.init.headers.authorization,
+        'Bearer user-token-9'
+      )
+    } finally {
+      restoreFetch()
+    }
+  })
+
+  test('omits the Authorization header for a public (no auth) surface', async () => {
+    stubFetch()
+    try {
+      wireRemoteAddon({
+        name: 'registry',
+        package: '@pikkufabric/addon-registry',
+        serverUrl: 'https://api.example.com',
+      })
+
+      const service = new ContextAwareRPCService(
+        createServices(),
+        {} as never,
+        {}
+      )
+
+      await service.rpc('registry:listOpenApis', {})
+      assert.equal(calls[0]!.init.headers.authorization, undefined)
+    } finally {
+      restoreFetch()
+    }
+  })
+
+  test('fails closed when a bound credential resolves empty', async () => {
+    stubFetch()
+    try {
+      wireRemoteAddon({
+        name: 'registry',
+        package: '@pikkufabric/addon-registry',
+        serverUrl: 'https://api.example.com',
+        auth: { credentialId: 'fabricRegistryToken' },
+      })
+
+      const service = new ContextAwareRPCService(
+        createServices(),
+        { getCredential: async () => null } as never,
+        {}
+      )
+
+      await assert.rejects(
+        () => service.rpc('registry:getOpenApi', {}),
+        RemoteAddonAuthError
+      )
+      assert.equal(calls.length, 0)
+    } finally {
+      restoreFetch()
+    }
+  })
+
+  test('throws RemoteAddonRequestError on a non-2xx response', async () => {
+    stubFetch({ status: 503, body: { error: 'down' } })
+    try {
+      wireRemoteAddon({
+        name: 'registry',
+        package: '@pikkufabric/addon-registry',
+        serverUrl: 'https://api.example.com',
+      })
+
+      const service = new ContextAwareRPCService(
+        createServices(),
+        {} as never,
+        {}
+      )
+
+      await assert.rejects(
+        () => service.rpc('registry:getOpenApi', {}),
+        RemoteAddonRequestError
+      )
+    } finally {
+      restoreFetch()
+    }
+  })
+})
+
 describe('rpcService.getContextRPCService', () => {
   test('builds a typed rpc facade with depth and bound methods', async () => {
     pikkuState(null, 'rpc', 'meta').echo = 'echoFunc'

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

@@ -6,10 +6,13 @@ import type {
 import type { SessionService } from '../../services/user-session-service.js'
 import type { CoreUserSession } from '../../types/core.types.js'
 import { runPikkuFunc } from '../../function/function-runner.js'
+import type { AddonInstance } from './addon-runner.js'
+import { addonInstanceForNamespace } from './addon-runner.js'
 import { pikkuState } from '../../pikku-state.js'
 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'
 
 export class RPCNotFoundError extends PikkuError {
   public readonly rpcName: string
@@ -23,11 +26,43 @@ addError(RPCNotFoundError, {
   mcpCode: -32601,
   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}`)
+  }
+}
+addError(RemoteAddonConfigError, {
+  status: 500,
+  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(
+    namespace: string,
+    fnName: string,
+    status: number,
+    detail: string
+  ) {
+    super(
+      `Remote addon '${namespace}:${fnName}' returned ${status}${detail ? `: ${detail}` : ''}`
+    )
+    this.httpStatus = status
+  }
+}
+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 } 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
@@ -164,6 +199,12 @@ export class ContextAwareRPCService {
     // 'namespace:func' boundary via invokeAddonFunction.
     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,
@@ -174,6 +215,7 @@ export class ContextAwareRPCService {
           data: () => data,
           wire: updatedWire,
           packageName: resolved.packageName,
+          addonInstance,
         }
       )
     } catch (e) {
@@ -213,6 +255,21 @@ export class ContextAwareRPCService {
       throw new RPCNotFoundError(namespacedFunction)
     }
 
+    const namespace = namespacedFunction.slice(
+      0,
+      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>(
+        namespace,
+        resolved.function,
+        data
+      )
+    }
+
     // Get the function meta from the addon package
     // Addon packages use function meta, not RPC meta
     const addonFunctionMeta = pikkuState(resolved.package, 'function', 'meta')
@@ -228,6 +285,15 @@ export class ContextAwareRPCService {
       ...(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,
+    }
+
     // 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
@@ -238,9 +304,78 @@ export class ContextAwareRPCService {
       wire,
       packageName: resolved.package,
       tags,
+      addonInstance,
     })
   }
 
+  /**
+   * 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.
+   */
+  private async invokeRemoteAddonFunction<In = any, Out = any>(
+    namespace: string,
+    fnName: string,
+    data: In
+  ): 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)
+        : cfg.serverUrl
+    if (!serverUrl) {
+      throw new RemoteAddonConfigError(namespace, 'serverUrl resolved empty')
+    }
+
+    const remoteFn = cfg.remoteName ? cfg.remoteName(fnName) : fnName
+    const token = await resolveRemoteAddonToken(
+      cfg.remoteAuth,
+      this.services,
+      this.wire,
+      namespace
+    )
+
+    const headers: Record<string, string> = {
+      'content-type': 'application/json',
+      accept: 'application/json',
+    }
+    if (token) {
+      headers.authorization = `Bearer ${token}`
+    }
+    if (this.wire.traceId) {
+      headers['x-trace-id'] = this.wire.traceId
+    }
+
+    const base = serverUrl.replace(/\/+$/, '')
+    const res = await fetch(
+      `${base}/remote/rpc/${encodeURIComponent(remoteFn)}`,
+      {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ rpcName: remoteFn, data }),
+      }
+    )
+
+    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)
+    }
+
+    if (res.status === 204) {
+      return undefined as Out
+    }
+    const text = await res.text()
+    return (text ? JSON.parse(text) : undefined) as Out
+  }
+
   public async rpcWithWire<In = any, Out = any>(
     rpcName: string,
     data: In,
@@ -257,12 +392,19 @@ export class ContextAwareRPCService {
 
     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,
       })
     } catch (e) {
       if (e instanceof RPCNotFoundError && this.services.deploymentService) {
@@ -338,16 +480,26 @@ export class ContextAwareRPCService {
       ) => {
         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,
-          channel,
+          wrapChannelWithAGUI(channel, {
+            threadId: input.threadId,
+            getRunId: () => currentRunId,
+          }),
           {
             sessionService: this.options.sessionService,
             getCredential: this.wire.getCredential?.bind(this.wire),
           },
           undefined,
-          options
+          {
+            ...options,
+            onRunCreated: (runId) => {
+              currentRunId = runId
+              options?.onRunCreated?.(runId)
+            },
+          }
         )
       },
       resume: async (
@@ -359,7 +511,7 @@ export class ContextAwareRPCService {
         if (!channel) throw new Error('No channel available for streaming')
         await resumeAIAgent(
           { runId, ...input },
-          channel,
+          wrapChannelWithAGUI(channel, { runId }),
           {
             sessionService: this.options.sessionService,
             getCredential: this.wire.getCredential?.bind(this.wire),