@pikku/addon-meta-conversions 0.1.1 → 0.1.3

package/dist/.pikku/function/pikku-function-types.gen.ts

@@ -1,15 +1,21 @@
 /**
- * This file was generated by @pikku/cli@0.12.6
+ * This file was generated by @pikku/cli@0.12.96
  */
 /**
  * Core function, middleware, and permission types for all wirings
  */
 
-import { CorePikkuFunctionConfig, CorePikkuAuth, CorePikkuAuthConfig, CorePikkuPermission, CorePikkuMiddleware, CorePermissionGroup, addMiddleware as addMiddlewareCore, addPermission as addPermissionCore, PikkuWire, PickRequired } from '@pikku/core'
+import type { CorePikkuMiddleware, CorePermissionGroup, ListInput, ListOutput, PikkuWire, PickRequired, SecretlessServices, SecretService } from '@pikku/core'
+import type { CorePikkuFunctionConfig, CorePikkuAuth, CorePikkuAuthConfig, CorePikkuPermission } from '@pikku/core/function'
+import { pikkuAuth as pikkuAuthCore } from '@pikku/core/function'
+import {
+  addTagMiddleware as addTagMiddlewareCore,
+  addGlobalMiddleware as addGlobalMiddlewareCore,
+  addGlobalPermission as addGlobalPermissionCore,
+} from '@pikku/core/middleware'
 import { pikkuState as __pikkuState, CreateWireServices } from '@pikku/core/internal'
-import { pikkuAuth as pikkuAuthCore } from '@pikku/core'
-import { PikkuError } from '@pikku/core/errors'
 import type { NodeType } from '@pikku/core/node'
+import type { ScopeId } from '../scopes/pikku-scopes.gen.js'
 import type { StandardSchemaV1 } from '@standard-schema/spec'
 import { CorePikkuFunction, CorePikkuFunctionSessionless } from '@pikku/core/function'
 
@@ -19,13 +25,37 @@ import type { Services } from '../../types/application-types.d.js'
 import type { Config } from '../../types/application-types.d.js'
 import type { TypedPikkuRPC, FlattenedRPCMap } from '../rpc/pikku-rpc-wirings-map.internal.gen.d.js'
 import type { RequiredSingletonServices, RequiredWireServices } from '../pikku-services.gen.js'
-import type { TypedWorkflow } from '../workflow/pikku-workflow-types.gen.js'
+import type { TypedWorkflow, TypedScenario, TypedPersonas } from '../workflow/pikku-workflow-types.gen.js'
 
 export type { SingletonServices as SingletonServices }
 export type { Services as Services }
 export type Session = UserSession
 
 
+/**
+ * The services a wired function actually receives. The inspector records which
+ * services each wired `func`, `permissions` and `middleware` destructures and
+ * emits them as `RequiredSingletonServices`; intersecting that here makes those
+ * services **non-optional** at every call site. A service is optional only when
+ * nothing destructures it — in which case it is never created either. This is
+ * why an `if (!service)` guard inside a function body is always dead code.
+ */
+export type WiredSingletonServices = RequiredSingletonServices & SingletonServices
+export type WiredServices = SecretlessServices<RequiredSingletonServices & Services>
+
+/** `WiredSingletonServices` without `secrets`, for auth gates. */
+export type WiredAuthServices = SecretlessServices<WiredSingletonServices>
+
+/**
+ * `WiredServices` with `secrets` restored, for the console's secret-admin
+ * functions. Reached by declaring `secretBroker: true` on a `pikkuFunc` config.
+ *
+ * Declaring it does not grant the service. The runner hands out the real
+ * `SecretService` only to the functions the inspector marks as secret brokers;
+ * every other function still receives the throwing accessor.
+ */
+export type WiredSecretBrokerServices = WiredServices & { secrets: SecretService }
+
 /**
  * Inline node configuration for function definitions.
  */
@@ -43,7 +73,7 @@ export type NodeConfig = {
  * @template In - The input type that the permission check will receive
  * @template RequiredServices - The services required for this permission check
  */
-export type PikkuPermission<In = unknown, RequiredServices extends Services = Services> = CorePikkuPermission<In, RequiredServices, PikkuWire<In, never, false, Session>>
+export type PikkuPermission<In = unknown, RequiredServices extends SecretlessServices<Services> = WiredServices> = CorePikkuPermission<In, RequiredServices, PikkuWire<In, never, false, Session>>
 
 /**
  * Type-safe middleware definition that can access your application's services and session.
@@ -51,12 +81,12 @@ export type PikkuPermission<In = unknown, RequiredServices extends Services = Se
  *
  * @template RequiredServices - The services required for this middleware
  */
-export type PikkuMiddleware<RequiredServices extends SingletonServices = SingletonServices> = CorePikkuMiddleware<RequiredServices>
+export type PikkuMiddleware<RequiredServices extends SingletonServices = WiredSingletonServices> = CorePikkuMiddleware<RequiredServices>
 
 /**
  * Configuration object for creating a permission with metadata
  */
-export type PikkuPermissionConfig<In = unknown, RequiredServices extends Services = Services> = {
+export type PikkuPermissionConfig<In = unknown, RequiredServices extends SecretlessServices<Services> = WiredServices> = {
   /** The permission function */
   func: PikkuPermission<In, RequiredServices>
   /** Optional human-readable name for the permission */
@@ -101,12 +131,12 @@ export const pikkuPermission = <In>(
  *
  * @template RequiredServices - The services required for this auth check
  */
-export type PikkuAuth<RequiredServices extends SingletonServices = SingletonServices> = CorePikkuAuth<RequiredServices, Session>
+export type PikkuAuth<RequiredServices extends SecretlessServices<SingletonServices> = WiredAuthServices> = CorePikkuAuth<RequiredServices, Session>
 
 /**
  * Configuration object for creating an auth permission with metadata
  */
-export type PikkuAuthConfig<RequiredServices extends SingletonServices = SingletonServices> = CorePikkuAuthConfig<RequiredServices, Session>
+export type PikkuAuthConfig<RequiredServices extends SecretlessServices<SingletonServices> = WiredAuthServices> = CorePikkuAuthConfig<RequiredServices, Session>
 
 /**
  * Factory function for creating auth-only permissions with tree-shaking support.
@@ -128,7 +158,7 @@ export type PikkuAuthConfig<RequiredServices extends SingletonServices = Singlet
  * })
  * \`\`\`
  */
-export const pikkuAuth = <RequiredServices extends SingletonServices = SingletonServices>(
+export const pikkuAuth = <RequiredServices extends SecretlessServices<SingletonServices> = WiredAuthServices>(
   auth: PikkuAuth<RequiredServices> | PikkuAuthConfig<RequiredServices>
 ): PikkuPermission<any, any> => {
   return pikkuAuthCore(auth as any) as any
@@ -137,7 +167,7 @@ export const pikkuAuth = <RequiredServices extends SingletonServices = Singleton
 /**
  * Configuration object for creating middleware with metadata
  */
-export type PikkuMiddlewareConfig<RequiredServices extends SingletonServices = SingletonServices> = {
+export type PikkuMiddlewareConfig<RequiredServices extends SingletonServices = WiredSingletonServices> = {
   /** The middleware function */
   func: PikkuMiddleware<RequiredServices>
   /** Optional human-readable name for the middleware */
@@ -169,7 +199,7 @@ export type PikkuMiddlewareConfig<RequiredServices extends SingletonServices = S
  * })
  * ```
  */
-export const pikkuMiddleware = <RequiredServices extends SingletonServices = SingletonServices>(
+export const pikkuMiddleware = <RequiredServices extends SingletonServices = WiredSingletonServices>(
   middleware: PikkuMiddleware<RequiredServices> | PikkuMiddlewareConfig<RequiredServices>
 ): PikkuMiddleware<RequiredServices> => {
   return typeof middleware === 'function' ? middleware : middleware.func
@@ -230,7 +260,7 @@ export const pikkuPermissionFactory = <In = any>(
  * @template In - The input type (same as the function it describes)
  * @template RequiredServices - The services required for this description function
  */
-export type PikkuApprovalDescription<In = unknown, RequiredServices extends Services = Services> = (
+export type PikkuApprovalDescription<In = unknown, RequiredServices extends SecretlessServices<Services> = WiredServices> = (
   services: RequiredServices,
   data: In
 ) => Promise<string>
@@ -248,7 +278,7 @@ export type PikkuApprovalDescription<In = unknown, RequiredServices extends Serv
  * )
  * ```
  */
-export const pikkuApprovalDescription = <In = unknown, RequiredServices extends Services = Services>(
+export const pikkuApprovalDescription = <In = unknown, RequiredServices extends SecretlessServices<Services> = WiredServices>(
   fn: PikkuApprovalDescription<In, RequiredServices>
 ): PikkuApprovalDescription<In, RequiredServices> => {
   return fn
@@ -266,13 +296,13 @@ export type PikkuFunctionSessionless<
   In = unknown,
   Out = never,
   RequiredWires extends keyof PikkuWire = never,
-  RequiredServices extends Services = Services
+  RequiredServices extends SecretlessServices<Services> = WiredServices
 > = CorePikkuFunctionSessionless<
     In,
     Out,
     RequiredServices,
     Session,
-    PickRequired<PikkuWire<In, Out, false, Session, TypedPikkuRPC, null, any, TypedWorkflow>, RequiredWires>
+    PickRequired<PikkuWire<In, Out, false, Session, TypedPikkuRPC, null, any, TypedWorkflow, unknown, TypedScenario, TypedPersonas>, RequiredWires>
   >
 
 /**
@@ -287,13 +317,13 @@ export type PikkuFunction<
   In = unknown,
   Out = never,
   RequiredWires extends keyof PikkuWire = 'session',
-  RequiredServices extends Services = Services
+  RequiredServices extends SecretlessServices<Services> = WiredServices
 > = CorePikkuFunction<
     In,
     Out,
     RequiredServices,
     Session,
-    PickRequired<PikkuWire<In, Out, true, Session, TypedPikkuRPC, null, any, TypedWorkflow>, RequiredWires>
+    PickRequired<PikkuWire<In, Out, true, Session, TypedPikkuRPC, null, any, TypedWorkflow, unknown, TypedScenario, TypedPersonas>, RequiredWires>
   >
 
 /**
@@ -313,70 +343,66 @@ export type PikkuFunctionConfig<
   In = unknown,
   Out = unknown,
   RequiredWires extends keyof PikkuWire = never,
-  PikkuFunc extends PikkuFunction<In, Out, RequiredWires> | PikkuFunctionSessionless<In, Out, RequiredWires> = PikkuFunction<In, Out, RequiredWires> | PikkuFunctionSessionless<In, Out, RequiredWires>,
+  PikkuFunc extends PikkuFunction<In, Out, RequiredWires, any> | PikkuFunctionSessionless<In, Out, RequiredWires, any> = PikkuFunction<In, Out, RequiredWires> | PikkuFunctionSessionless<In, Out, RequiredWires>,
   InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined
-> = CorePikkuFunctionConfig<PikkuFunc, PikkuPermission<In>, PikkuMiddleware, InputSchema, OutputSchema>
+> = CorePikkuFunctionConfig<PikkuFunc, PikkuPermission<In>, PikkuMiddleware, InputSchema, OutputSchema, ScopeId>
 
 /**
  * Configuration object for Pikku functions with Zod schema validation.
  * Use this when you want to define input/output schemas using Zod.
  * Types are automatically inferred from the schemas.
  */
+type SchemaInferred<S, Fallback = unknown> = S extends StandardSchemaV1
+  ? InferSchemaOutput<S>
+  : Fallback
+
+/**
+ * Schema-overload variant for pikkuFunc. Derived from CorePikkuFunctionConfig
+ * so adding a field on the core type automatically propagates here.
+ */
 export type PikkuFunctionConfigWithSchema<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined,
-  RequiredWires extends keyof PikkuWire = never
-> = {
-  name?: string
-  tags?: string[]
-  expose?: boolean
-  mcp?: boolean
-  internal?: boolean
-  approvalRequired?: boolean
-  approvalDescription?: InputSchema extends StandardSchemaV1 ? PikkuApprovalDescription<InferSchemaOutput<InputSchema>> : never
-  func: PikkuFunction<
-    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
-    OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
-    RequiredWires
-  > | PikkuFunctionSessionless<
-    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
-    OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
-    RequiredWires
-  >
-  auth?: boolean
-  permissions?: InputSchema extends StandardSchemaV1 ? CorePermissionGroup<PikkuPermission<InferSchemaOutput<InputSchema>>> : undefined
-  middleware?: PikkuMiddleware[]
+  RequiredWires extends keyof PikkuWire = never,
+  RequiredServices extends SecretlessServices<Services> = WiredServices
+> = Omit<
+  CorePikkuFunctionConfig<
+    | PikkuFunction<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires, RequiredServices>
+    | PikkuFunctionSessionless<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires, RequiredServices>,
+    CorePikkuPermission<any>,
+    PikkuMiddleware,
+    undefined,
+    undefined,
+    ScopeId
+  >,
+  'func' | 'input' | 'output' | 'permissions' | 'approvalDescription'
+> & {
+  func:
+    | PikkuFunction<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires, RequiredServices>
+    | PikkuFunctionSessionless<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires, RequiredServices>
   input?: InputSchema
   output?: OutputSchema
-  node?: NodeConfig
-  errors?: Array<typeof PikkuError>
+  permissions?: InputSchema extends StandardSchemaV1
+    ? CorePermissionGroup<PikkuPermission<InferSchemaOutput<InputSchema>>>
+    : undefined
+  approvalDescription?: InputSchema extends StandardSchemaV1
+    ? PikkuApprovalDescription<InferSchemaOutput<InputSchema>>
+    : never
 }
 
 /**
  * Creates a Pikku function that can be either session-aware or sessionless.
  * This is the main function wrapper for creating API endpoints.
  *
- * Supports two patterns:
- * 1. Generic types: `pikkuFunc<Input, Output>({ func: ... })`
- * 2. Zod schemas: `pikkuFunc({ input: z.object(...), output: z.object(...), func: ... })`
+ * Define the input and output with Zod schemas — the function's types are
+ * inferred from them, and the schemas double as runtime validation.
  *
- * @template In - Input type for the function (inferred from schema if provided)
- * @template Out - Output type for the function (inferred from schema if provided)
- * @param func - Function definition, either direct function or configuration object
+ * @param config - Function definition with `input`/`output` Zod schemas and `func`.
  * @returns The normalized configuration object
  *
  * @example
  * ```typescript
- * // Pattern 1: Using generic types
- * const createUser = pikkuFunc<{name: string, email: string}, {id: number}>({
- *   func: async ({db}, input) => {
- *     const user = await db.users.create(input)
- *     return { id: user.id }
- *   }
- * })
- *
- * // Pattern 2: Using Zod schemas (types inferred automatically)
  * const createUserInput = z.object({ name: z.string(), email: z.string() })
  * const createUserOutput = z.object({ id: z.number() })
  *
@@ -391,6 +417,12 @@ export type PikkuFunctionConfigWithSchema<
  * })
  * ```
  */
+export function pikkuFunc<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+>(
+  config: PikkuFunctionConfigWithSchema<InputSchema, OutputSchema, 'session' | 'rpc', WiredSecretBrokerServices> & { secretBroker: true }
+): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'session' | 'rpc'>
 export function pikkuFunc<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined
@@ -406,60 +438,78 @@ export function pikkuFunc(func: any) {
   return typeof func === 'function' ? { func } : func
 }
 
+export type PikkuListFunction<
+  F extends Record<string, unknown> = {},
+  Row = unknown,
+  S extends string = never
+> =
+  | PikkuFunction<ListInput<F, S>, ListOutput<Row>, 'session' | 'rpc'>
+  | PikkuFunctionSessionless<
+      ListInput<F, S>,
+      ListOutput<Row>,
+      'session' | 'rpc'
+    >
+
+export const pikkuListFunc = <
+  F extends Record<string, unknown> = {},
+  Row = unknown,
+  S extends string = never
+>(
+  config: PikkuFunctionConfig<
+    ListInput<F, S>,
+    ListOutput<Row>,
+    'session' | 'rpc'
+  >
+): PikkuFunctionConfig<ListInput<F, S>, ListOutput<Row>, 'session' | 'rpc'> => {
+  return pikkuFunc(config)
+}
+
 /**
  * Configuration object for sessionless Pikku functions with Zod schema validation.
  */
+/**
+ * Schema-overload variant for pikkuSessionlessFunc. Derived from
+ * CorePikkuFunctionConfig to stay in sync with the generic-typed config.
+ */
 export type PikkuFunctionSessionlessConfigWithSchema<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined,
-  RequiredWires extends keyof PikkuWire = never
-> = {
-  name?: string
-  description?: string
-  tags?: string[]
-  expose?: boolean
-  mcp?: boolean
-  internal?: boolean
-  remote?: boolean
-  approvalRequired?: boolean
-  approvalDescription?: InputSchema extends StandardSchemaV1 ? PikkuApprovalDescription<InferSchemaOutput<InputSchema>> : never
+  RequiredWires extends keyof PikkuWire = never,
+  RequiredServices extends SecretlessServices<Services> = WiredServices
+> = Omit<
+  CorePikkuFunctionConfig<
+    PikkuFunctionSessionless<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires, RequiredServices>
+  >,
+  'func' | 'input' | 'output' | 'permissions' | 'approvalDescription'
+> & {
   func: PikkuFunctionSessionless<
-    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
-    OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
-    RequiredWires
+    SchemaInferred<InputSchema>,
+    SchemaInferred<OutputSchema>,
+    RequiredWires,
+    RequiredServices
   >
-  auth?: boolean
-  permissions?: InputSchema extends StandardSchemaV1 ? CorePermissionGroup<PikkuPermission<InferSchemaOutput<InputSchema>>> : undefined
-  middleware?: PikkuMiddleware[]
   input?: InputSchema
   output?: OutputSchema
-  node?: NodeConfig
-  errors?: Array<typeof PikkuError>
+  permissions?: InputSchema extends StandardSchemaV1
+    ? CorePermissionGroup<PikkuPermission<InferSchemaOutput<InputSchema>>>
+    : undefined
+  approvalDescription?: InputSchema extends StandardSchemaV1
+    ? PikkuApprovalDescription<InferSchemaOutput<InputSchema>>
+    : never
 }
 
 /**
  * Creates a sessionless Pikku function that doesn't require user authentication.
  * Use this for public endpoints, webhooks, or background tasks.
  *
- * Supports two patterns:
- * 1. Generic types: `pikkuSessionlessFunc<Input, Output>({ func: ... })`
- * 2. Zod schemas: `pikkuSessionlessFunc({ input: z.object(...), func: ... })`
+ * Define the input and output with Zod schemas — the function's types are
+ * inferred from them, and the schemas double as runtime validation.
  *
- * @template In - Input type for the function (inferred from schema if provided)
- * @template Out - Output type for the function (inferred from schema if provided)
- * @param func - Function definition, either direct function or configuration object
+ * @param config - Function definition with `input`/`output` Zod schemas and `func`.
  * @returns The normalized configuration object
  *
  * @example
  * ```typescript
- * // Pattern 1: Using generic types
- * const healthCheck = pikkuSessionlessFunc<void, {status: string}>({
- *   func: async ({logger}) => {
- *     return { status: 'healthy' }
- *   }
- * })
- *
- * // Pattern 2: Using Zod schemas
  * const greetInput = z.object({ name: z.string() })
  * const greetOutput = z.object({ message: z.string() })
  *
@@ -474,14 +524,15 @@ export type PikkuFunctionSessionlessConfigWithSchema<
  */
 export function pikkuSessionlessFunc<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
-  OutputSchema extends StandardSchemaV1 | undefined = undefined
+  OutputSchema extends StandardSchemaV1 | undefined = undefined,
+  RequiredServices extends SecretlessServices<Services> = WiredServices
 >(
-  config: PikkuFunctionSessionlessConfigWithSchema<InputSchema, OutputSchema, 'session' | 'rpc'>
+  config: PikkuFunctionSessionlessConfigWithSchema<InputSchema, OutputSchema, 'session' | 'rpc', RequiredServices>
 ): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'session' | 'rpc'>
-export function pikkuSessionlessFunc<In, Out = unknown>(
+export function pikkuSessionlessFunc<In, Out = unknown, RequiredServices extends SecretlessServices<Services> = WiredServices>(
   func:
-    | PikkuFunctionSessionless<In, Out, 'session' | 'rpc'>
-    | PikkuFunctionConfig<In, Out, 'session' | 'rpc'>
+    | PikkuFunctionSessionless<In, Out, 'session' | 'rpc', RequiredServices>
+    | PikkuFunctionConfig<In, Out, 'session' | 'rpc', PikkuFunctionSessionless<In, Out, 'session' | 'rpc', RequiredServices>>
 ): PikkuFunctionConfig<In, Out, 'session' | 'rpc'>
 export function pikkuSessionlessFunc(func: any) {
   return typeof func === 'function' ? { func } : func
@@ -512,27 +563,23 @@ export const pikkuVoidFunc = (
 }
 
 /**
- * Creates a wrapper function for addon package functions that are exposed via RPC.
- * This allows you to wire addon functions to any wiring type (HTTP, queue, etc.)
- * without type compatibility issues.
+ * References a registered function by name for use in any wiring.
+ * Works for both local and addon functions — resolves via RPC at runtime.
  *
- * @template Name - The RPC method name (must be a key in FlattenedRPCMap)
- * @param rpcName - The name of the RPC method to invoke
- * @returns A Pikku function that proxies calls to the addon RPC method
+ * @template Name - The function name (must be a key in FlattenedRPCMap)
+ * @param rpcName - The name of the function to reference
+ * @returns A Pikku function config that proxies calls via RPC
  *
  * @example
  * ```typescript
- * // Wire an addon function via HTTP
- * wireHTTP({
- *   auth: false,
- *   method: 'get',
- *   route: '/addon/hello',
- *   func: addon('ext:hello'),
- *   tags: ['addon'],
- * })
+ * // Use in agent tools
+ * tools: [ref('todos:listTodos'), ref('myLocalFunc')]
+ *
+ * // Use in HTTP wiring
+ * wireHTTP({ route: '/greet', method: 'post', func: ref('greet') })
  * ```
  */
-export const addon = <Name extends keyof FlattenedRPCMap>(
+export const ref = <Name extends keyof FlattenedRPCMap>(
   rpcName: Name
 ): PikkuFunctionConfig<
   FlattenedRPCMap[Name]['input'],
@@ -550,6 +597,43 @@ export const addon = <Name extends keyof FlattenedRPCMap>(
   >
 }
 
+/**
+ * Declares a capability the connected client answers, reachable from any
+ * `wireChannel` function as `channel.remote(name, input)`.
+ *
+ * There is no `func`: this side owns the contract, the client owns the body.
+ * The `description` is what a person is shown when asked to approve the call,
+ * so write it for them rather than for the caller.
+ *
+ * @example
+ * ```typescript
+ * export const localCheckoutOutput = z.object({ sha: z.string(), branch: z.string() })
+ *
+ * export const localCheckout = pikkuRemoteChannelFunc({
+ *   description: 'Read the current commit and branch of your working tree',
+ *   output: localCheckoutOutput,
+ * })
+ * ```
+ */
+export function pikkuRemoteChannelFunc<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+>(
+  config: Omit<
+    PikkuFunctionSessionlessConfigWithSchema<InputSchema, OutputSchema, 'session' | 'rpc'>,
+    'func'
+  >
+): PikkuFunctionConfig<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, 'session' | 'rpc'> {
+  return {
+    ...config,
+    func: async (_services: any, _data: any, _wire: any) => {
+      throw new Error(
+        `${config.title ?? 'This'} is a remote channel capability and has no local implementation — reach it with channel.remote() on the channel whose client exposes it.`
+      )
+    },
+  } as any
+}
+
 /**
  * Creates a Pikku config factory.
  * Use this to define your application's configuration factory.
@@ -591,12 +675,27 @@ export const pikkuConfig = (
  * ```
  */
 export const pikkuServices = (
-  func: (config: Config, existingServices: Partial<SingletonServices>) => Promise<RequiredSingletonServices>
+  func: (config: Config, existingServices: Partial<SingletonServices>) => Promise<Partial<Omit<RequiredSingletonServices, 'auth'>>>
 ) => {
   return async (config: Config, existingServices: Partial<SingletonServices> = {}) => {
-    const services = await func(config, existingServices)
-    __pikkuState(null, 'package', 'singletonServices', services as any)
-    return services
+    const createdServices = await func(config, existingServices)
+    const services = { ...existingServices, ...createdServices }
+    const authFactory = __pikkuState(null, 'package', 'authFactory')
+    if (authFactory) {
+      let authInstance: Promise<unknown> | undefined
+      ;(services as any).auth = () => {
+        authInstance ??= Promise.resolve()
+          .then(() => authFactory(services as any))
+          .catch((error) => {
+            authInstance = undefined
+            throw error
+          })
+        return authInstance
+      }
+    }
+    const resolved = services as RequiredSingletonServices
+    __pikkuState(null, 'package', 'singletonServices', resolved as any)
+    return resolved
   }
 }
 
@@ -629,58 +728,70 @@ export const pikkuWireServices = (
 }
 
 /**
- * Adds global middleware for a specific tag.
- *
- * This function allows you to register middleware that will be applied to
- * any wiring (HTTP, Channel, Queue, Scheduler, MCP) that includes the matching tag.
- *
- * @param tag - The tag that the middleware should apply to.
- * @param middleware - The middleware array to apply for the specified tag.
- *
- * @throws Error if middleware for the tag already exists.
+ * Tag-scoped middleware. Applies to any wiring that carries the matching tag.
  *
  * @example
- * ```typescript
- * // Add admin middleware for admin endpoints
- * addMiddleware('admin', [adminMiddleware])
- *
- * // Add authentication middleware for auth endpoints
- * addMiddleware('auth', [authMiddleware])
- *
- * // Add logging middleware for all API endpoints
- * addMiddleware('api', [loggingMiddleware])
- * ```
+ * addTagMiddleware('admin', [adminMiddleware])
  */
-export const addMiddleware = (tag: string, middleware: PikkuMiddleware[]) => {
-  addMiddlewareCore(tag, middleware as any, '@pikku/addon-meta-conversions')
+export const addTagMiddleware = (tag: string, middleware: PikkuMiddleware[]) => {
+  addTagMiddlewareCore(tag, middleware as any, '@pikku/addon-meta-conversions')
 }
 
 /**
- * Adds global permissions for a specific tag.
- *
- * This function allows you to register permissions that will be applied to
- * any wiring (HTTP, Channel, Queue, Scheduler, MCP) that includes the matching tag.
+ * Wire-agnostic global middleware. Runs at the top of every wiring's
+ * middleware chain — before wire-, tag-, and function-level entries.
  *
- * @param tag - The tag that the permissions should apply to.
- * @param permissions - The permissions array or object to apply for the specified tag.
- *
- * @throws Error if permissions for the tag already exist.
+ * Resolution order: global -> wire -> tag -> function.
  *
  * @example
- * ```typescript
- * // Add admin permissions for admin endpoints
- * addPermission('admin', [adminPermission])
+ * addGlobalMiddleware([telemetryMiddleware])
+ */
+export const addGlobalMiddleware = (middleware: PikkuMiddleware[]) => {
+  addGlobalMiddlewareCore(middleware as any, '@pikku/addon-meta-conversions')
+}
+
+/**
+ * Wire-agnostic global permissions. Runs at the top of every wiring's
+ * permission resolution — before wire-, tag-, and function-level entries.
  *
- * // Add authentication permissions for auth endpoints
- * addPermission('auth', [authPermission])
+ * Resolution order: global -> wire -> tag -> function.
  *
- * // Add read permissions for all API endpoints (as object)
- * addPermission('api', { read: readPermission })
- * ```
+ * @example
+ * addGlobalPermission([signedInUser])
+ */
+export const addGlobalPermission = <In = unknown>(permissions: CorePermissionGroup<PikkuPermission<In>> | PikkuPermission<In>[]) => {
+  addGlobalPermissionCore(permissions as any, '@pikku/addon-meta-conversions')
+}
+
+export { wireAddon, wireRemoteAddon } from '@pikku/core/rpc'
+export type { WireAddonConfig, WireRemoteAddonConfig, RemoteAddonAuth } from '@pikku/core/rpc'
+
+
+/**
+ * Addon contract references. Generated from each wired addon's published
+ * contract metadata — no addon source is imported. Functions are proxied via
+ * ref() (RPC) exactly like ref('namespace:fn').
  */
-export const addPermission = <In = unknown>(tag: string, permissions: CorePermissionGroup<PikkuPermission<In>> | PikkuPermission<In>[]) => {
-  addPermissionCore(tag, permissions as any, '@pikku/addon-meta-conversions')
+const __addonHttp = {} as const
+const __addonChannel = {} as const
+const __addonCli = {} as const
+
+export const refHTTP = <Name extends keyof typeof __addonHttp>(
+  name: Name,
+  options?: { basePath?: string }
+): (typeof __addonHttp)[Name] => {
+  const contract = __addonHttp[name] as any
+  return (
+    options?.basePath !== undefined
+      ? { ...contract, basePath: options.basePath }
+      : contract
+  ) as (typeof __addonHttp)[Name]
 }
 
-export { wireAddon } from '@pikku/core'
-export type { WireAddonConfig } from '@pikku/core'
+export const refChannel = <Name extends keyof typeof __addonChannel>(
+  name: Name
+): (typeof __addonChannel)[Name] => __addonChannel[name]
+
+export const refCLI = <Name extends keyof typeof __addonCli>(
+  name: Name
+): (typeof __addonCli)[Name] => __addonCli[name]