@pikku/core 0.12.63 → 0.12.66

package/dist/wirings/rpc/addon-runner.js

@@ -0,0 +1,173 @@
+import { pikkuState } from '../../pikku-state.js';
+/**
+ * Wrap a SecretService so that the logical secret names an addon reads are
+ * remapped to the actual project secret names via the instance's overrides.
+ */
+const aliasSecretService = (secrets, overrides) => {
+    const map = (key) => overrides[key] ?? key;
+    return {
+        getSecret: (key) => secrets.getSecret(map(key)),
+        hasSecret: (key) => secrets.hasSecret(map(key)),
+        setSecret: (key, value) => secrets.setSecret(map(key), value),
+        deleteSecret: (key) => secrets.deleteSecret(map(key)),
+        getSecrets: async (keys) => {
+            const result = await secrets.getSecrets(keys.map(map));
+            const out = {};
+            for (const logical of keys) {
+                const real = map(logical);
+                if (real in result)
+                    out[logical] = result[real];
+            }
+            return out;
+        },
+    };
+};
+/**
+ * Wrap a VariablesService so that the logical variable names an addon reads
+ * are remapped to the actual project variable names via the instance's overrides.
+ */
+const aliasVariablesService = (variables, overrides) => {
+    const map = (name) => overrides[name] ?? name;
+    return {
+        get: (name) => variables.get(map(name)),
+        getVariables: (names) => {
+            const result = variables.getVariables(names.map(map));
+            const remap = (r) => {
+                const out = {};
+                for (const logical of names) {
+                    const real = map(logical);
+                    if (real in r)
+                        out[logical] = r[real];
+                }
+                return out;
+            };
+            return result instanceof Promise
+                ? result.then(remap)
+                : remap(result);
+        },
+        getAll: () => variables.getAll(),
+        set: (name, value) => variables.set(map(name), value),
+        has: (name) => variables.has(map(name)),
+        delete: (name) => variables.delete(map(name)),
+    };
+};
+/**
+ * Find the consumer-defined namespace (from wireAddon) for a given addon package.
+ * Returns null if the package isn't registered as an addon.
+ */
+const findAddonNamespaceForPackage = (packageName) => {
+    const addons = pikkuState(null, 'addons', 'packages');
+    if (!addons)
+        return null;
+    for (const [namespace, cfg] of addons.entries()) {
+        if (cfg?.package === packageName)
+            return namespace;
+    }
+    return null;
+};
+/**
+ * Wrap a workflow service so that bare workflow names passed from inside an
+ * addon function are auto-prefixed with the addon's consumer-facing namespace.
+ * Without this, `runToCompletion('myWorkflow')` from inside an addon misses
+ * the workflow registered under the addon's package scope and throws
+ * WorkflowNotFoundError — forcing addons to hardcode their consumer-defined
+ * namespace, which couples the addon to its caller.
+ *
+ * Explicit `'ns:name'` and bare names that already exist in root meta are
+ * unaffected; only bare names that would otherwise miss resolution get
+ * prefixed.
+ */
+const wrapWorkflowServiceForPackage = (service, packageName, namespace) => {
+    return new Proxy(service, {
+        get(target, prop, receiver) {
+            if (prop === 'startWorkflow' || prop === 'runToCompletion') {
+                const original = Reflect.get(target, prop, receiver);
+                return function (name, ...rest) {
+                    if (typeof name === 'string' && !name.includes(':')) {
+                        // Prefer the known instance namespace; fall back to the
+                        // package's sole namespace when invoked without an instance.
+                        const ns = namespace ?? findAddonNamespaceForPackage(packageName);
+                        if (ns) {
+                            name = `${ns}:${name}`;
+                        }
+                    }
+                    return original.call(this, name, ...rest);
+                };
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+};
+/**
+ * Get or create singleton services for an addon instance.
+ * Services are cached in pikkuState to avoid recreation on each call.
+ *
+ * @param packageName - The addon package name
+ * @param parentServices - The parent/caller's singleton services (used as base)
+ * @param addonInstance - The wired instance whose overrides shape the services
+ * @returns The instance's singleton services
+ */
+export const getOrCreatePackageSingletonServices = async (packageName, parentServices, addonInstance) => {
+    // Cache per instance (namespace), not per package, so two instances of one
+    // package get separate services built with their own overrides. A bare
+    // package-scoped call (no instance) falls back to per-package caching.
+    const cacheKey = addonInstance?.namespace ?? packageName;
+    const cachedServices = pikkuState(cacheKey, 'package', 'singletonServices');
+    if (cachedServices) {
+        return cachedServices;
+    }
+    const factories = pikkuState(packageName, 'package', 'factories');
+    if (!factories || !factories.createSingletonServices) {
+        // No factories registered, use parent services
+        return parentServices;
+    }
+    // Apply this instance's secret/variable overrides by aliasing the resolver
+    // services the addon reads from, so its createSingletonServices resolves
+    // instance-specific secrets/variables.
+    let existingServices = parentServices;
+    if (addonInstance?.secretOverrides && parentServices.secrets) {
+        existingServices = {
+            ...existingServices,
+            secrets: aliasSecretService(parentServices.secrets, addonInstance.secretOverrides),
+        };
+    }
+    if (addonInstance?.variableOverrides && parentServices.variables) {
+        existingServices = {
+            ...existingServices,
+            variables: aliasVariablesService(parentServices.variables, addonInstance.variableOverrides),
+        };
+    }
+    // Create config for the package (use parent config if no factory)
+    let config = existingServices.config;
+    if (factories.createConfig) {
+        config = await factories.createConfig(existingServices.variables);
+    }
+    // Create singleton services for the package, passing parent services as existing
+    const packageServices = await factories.createSingletonServices(config, existingServices);
+    // Wrap workflowService so that bare names used inside the addon's functions
+    // resolve to workflows registered under the addon's package scope.
+    if (packageServices.workflowService &&
+        typeof packageServices.workflowService === 'object') {
+        packageServices.workflowService = wrapWorkflowServiceForPackage(packageServices.workflowService, packageName, addonInstance?.namespace ?? null);
+    }
+    pikkuState(cacheKey, 'package', 'singletonServices', packageServices);
+    return packageServices;
+};
+/**
+ * Build the addon instance descriptor (namespace + per-instance overrides) for
+ * a bare intra-addon call, using the namespace currently executing on the wire.
+ * Returns undefined unless that namespace maps to the resolved package.
+ */
+export const addonInstanceForNamespace = (namespace, expectedPackage) => {
+    if (!namespace)
+        return undefined;
+    const cfg = pikkuState(null, 'addons', 'packages').get(namespace);
+    if (!cfg || cfg.package !== expectedPackage)
+        return undefined;
+    return {
+        namespace,
+        secretOverrides: cfg.secretOverrides,
+        variableOverrides: cfg.variableOverrides,
+        credentialOverrides: cfg.credentialOverrides,
+    };
+};

package/dist/wirings/rpc/index.d.ts

@@ -1,4 +1,8 @@
-export { PikkuRPCService, rpcService, RPCNotFoundError } from './rpc-runner.js';
+export { PikkuRPCService, rpcService, RPCNotFoundError, RemoteAddonConfigError, RemoteAddonRequestError, } from './rpc-runner.js';
+export { resolveRemoteAddonToken, RemoteAddonAuthError, } from './remote-addon-auth.js';
+export type { RemoteAddonAuthBinding } from './remote-addon-auth.js';
 export type { PikkuRPC, RPCMeta } from './rpc-types.js';
 export { wireAddon } from './wire-addon.js';
 export type { WireAddonConfig } from './wire-addon.js';
+export { wireRemoteAddon } from './wire-remote-addon.js';
+export type { WireRemoteAddonConfig, RemoteAddonAuth, } from './wire-remote-addon.js';

package/dist/wirings/rpc/index.js

@@ -1,2 +1,4 @@
-export { PikkuRPCService, rpcService, RPCNotFoundError } from './rpc-runner.js';
+export { PikkuRPCService, rpcService, RPCNotFoundError, RemoteAddonConfigError, RemoteAddonRequestError, } from './rpc-runner.js';
+export { resolveRemoteAddonToken, RemoteAddonAuthError, } from './remote-addon-auth.js';
 export { wireAddon } from './wire-addon.js';
+export { wireRemoteAddon } from './wire-remote-addon.js';

package/dist/wirings/rpc/remote-addon-auth.d.ts

@@ -0,0 +1,26 @@
+import type { CoreServices, PikkuRawWire } from '../../types/core.types.js';
+import { PikkuError } 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 declare class RemoteAddonAuthError extends PikkuError {
+    readonly namespace: string;
+    constructor(namespace: string, detail: string);
+}
+/**
+ * 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 declare function resolveRemoteAddonToken(auth: RemoteAddonAuthBinding | undefined, services: CoreServices, wire: PikkuRawWire, namespace: string): Promise<string | null>;

package/dist/wirings/rpc/remote-addon-auth.js

@@ -0,0 +1,43 @@
+import { PikkuError, addError } from '../../errors/error-handler.js';
+/** The addon's auth was bound but the source produced no token — fail closed. */
+export class RemoteAddonAuthError extends PikkuError {
+    namespace;
+    constructor(namespace, detail) {
+        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, services, wire, namespace) {
+    if (!auth) {
+        // No auth bound → the addon declares its remote surface public.
+        return null;
+    }
+    let token;
+    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/dist/wirings/rpc/rpc-runner.d.ts

@@ -7,6 +7,15 @@ export declare class RPCNotFoundError extends PikkuError {
     readonly rpcName: string;
     constructor(rpcName: string);
 }
+/** A `wireRemoteAddon` namespace is missing a usable `serverUrl`. */
+export declare class RemoteAddonConfigError extends PikkuError {
+    constructor(namespace: string, detail: string);
+}
+/** The hosted addon returned a non-2xx response for a remote RPC. */
+export declare class RemoteAddonRequestError extends PikkuError {
+    readonly httpStatus: number;
+    constructor(namespace: string, fnName: string, status: number, detail: string);
+}
 import type { AIAgentInput } from '../ai-agent/ai-agent.types.js';
 import type { StreamAIAgentOptions } from '../ai-agent/ai-agent-prepare.js';
 /**
@@ -32,6 +41,15 @@ export declare class ContextAwareRPCService {
      * @private
      */
     private invokeAddonFunction;
+    /**
+     * 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 invokeRemoteAddonFunction;
     rpcWithWire<In = any, Out = any>(rpcName: string, data: In, wire: PikkuRawWire): Promise<Out>;
     startWorkflow<In = any>(workflowName: string, input: In, options?: {
         startNode?: string;
@@ -103,5 +121,6 @@ export declare const rpcService: PikkuRPCService<import("../../types/core.types.
     logLevel?: import("../../services/logger.js").LogLevel;
     secrets?: {};
     workflow?: import("../workflow/workflow.types.js").WorkflowServiceConfig;
+    webhook?: import("../../services/webhook-service.js").WebhookServiceConfig;
     postgres?: import("../../types/core.types.js").PostgresConfig;
 }>, PikkuRPC>;

package/dist/wirings/rpc/rpc-runner.js

@@ -1,7 +1,9 @@
 import { runPikkuFunc } from '../../function/function-runner.js';
+import { addonInstanceForNamespace } from './addon-runner.js';
 import { pikkuState } from '../../pikku-state.js';
 import { PikkuError, addError } from '../../errors/error-handler.js';
 import { parseVersionedId } from '../../version.js';
+import { resolveRemoteAddonToken } from './remote-addon-auth.js';
 export class RPCNotFoundError extends PikkuError {
     rpcName;
     constructor(rpcName) {
@@ -14,8 +16,31 @@ addError(RPCNotFoundError, {
     mcpCode: -32601,
     message: 'RPC function not found.',
 });
+/** A `wireRemoteAddon` namespace is missing a usable `serverUrl`. */
+export class RemoteAddonConfigError extends PikkuError {
+    constructor(namespace, detail) {
+        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 {
+    httpStatus;
+    constructor(namespace, fnName, status, detail) {
+        super(`Remote addon '${namespace}:${fnName}' returned ${status}${detail ? `: ${detail}` : ''}`);
+        this.httpStatus = status;
+    }
+}
+addError(RemoteAddonRequestError, {
+    status: 502,
+    message: 'Remote addon request failed.',
+});
 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
  * Uses pikkuState to look up the namespace -> package mapping
@@ -130,12 +155,16 @@ 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('rpc', funcName, resolved.pikkuFuncId, {
                 auth: this.options.requiresAuth,
                 singletonServices: this.services,
                 data: () => data,
                 wire: updatedWire,
                 packageName: resolved.packageName,
+                addonInstance,
             });
         }
         catch (e) {
@@ -163,6 +192,12 @@ export class ContextAwareRPCService {
         if (!resolved) {
             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(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');
@@ -176,6 +211,14 @@ export class ContextAwareRPCService {
             ...(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 = {
+            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
@@ -186,7 +229,56 @@ 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.
+     */
+    async invokeRemoteAddonFunction(namespace, fnName, data) {
+        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 = {
+            '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;
+        }
+        const text = await res.text();
+        return (text ? JSON.parse(text) : undefined);
     }
     async rpcWithWire(rpcName, data, wire) {
         const mergedWire = {
@@ -198,12 +290,16 @@ export class ContextAwareRPCService {
         }
         try {
             const resolved = resolvePikkuFunction(rpcName, this.packageName);
+            const addonInstance = resolved.packageName
+                ? addonInstanceForNamespace(this.wire.addonNamespace, resolved.packageName)
+                : undefined;
             return await runPikkuFunc('rpc', rpcName, resolved.pikkuFuncId, {
                 auth: this.options.requiresAuth,
                 singletonServices: this.services,
                 data: () => data,
                 wire: mergedWire,
                 packageName: resolved.packageName,
+                addonInstance,
             });
         }
         catch (e) {
@@ -250,16 +346,26 @@ export class ContextAwareRPCService {
                 const channel = this.wire.channel;
                 if (!channel)
                     throw new Error('No channel available for streaming');
-                await streamAIAgent(agentName, input, channel, {
+                let currentRunId;
+                await streamAIAgent(agentName, input, wrapChannelWithAGUI(channel, {
+                    threadId: input.threadId,
+                    getRunId: () => currentRunId,
+                }), {
                     sessionService: this.options.sessionService,
                     getCredential: this.wire.getCredential?.bind(this.wire),
-                }, undefined, options);
+                }, undefined, {
+                    ...options,
+                    onRunCreated: (runId) => {
+                        currentRunId = runId;
+                        options?.onRunCreated?.(runId);
+                    },
+                });
             },
             resume: async (runId, input, options) => {
                 const channel = this.wire.channel;
                 if (!channel)
                     throw new Error('No channel available for streaming');
-                await resumeAIAgent({ runId, ...input }, channel, {
+                await resumeAIAgent({ runId, ...input }, wrapChannelWithAGUI(channel, { runId }), {
                     sessionService: this.options.sessionService,
                     getCredential: this.wire.getCredential?.bind(this.wire),
                 }, options);

package/dist/wirings/rpc/rpc-types.d.ts

@@ -1,4 +1,4 @@
-export type PikkuRPC<Invoke extends Function = any, Remote extends Function = any, startWorkflow extends Function = any, AgentRun extends Function = any, AgentStream extends Function = any> = {
+export type PikkuRPC<Invoke extends (...args: any[]) => any = (...args: any[]) => any, Remote extends (...args: any[]) => any = (...args: any[]) => any, startWorkflow extends (...args: any[]) => any = (...args: any[]) => any, AgentRun extends (...args: any[]) => any = (...args: any[]) => any, AgentStream extends (...args: any[]) => any = (...args: any[]) => any> = {
     depth: number;
     global: boolean;
     invoke: Invoke;
@@ -41,5 +41,19 @@ export interface ResolvedFunction {
         auth?: boolean;
         tags?: string[];
         rpcEndpoint?: string;
+        secretOverrides?: Record<string, string>;
+        variableOverrides?: Record<string, string>;
+        credentialOverrides?: Record<string, string>;
+        /** Set by `wireRemoteAddon`: dispatch this namespace's RPCs over HTTP */
+        remote?: boolean;
+        serverUrl?: string | ((services: any) => string | Promise<string>);
+        remoteAuth?: {
+            credentialId: string;
+        } | {
+            secretId: string;
+        } | {
+            resolve: (services: any, wire: any) => string | Promise<string>;
+        };
+        remoteName?: (fn: string) => string;
     };
 }

package/dist/wirings/rpc/wire-addon.js

@@ -5,5 +5,14 @@ export const wireAddon = (config) => {
         rpcEndpoint: config.rpcEndpoint,
         auth: config.auth,
         tags: config.tags,
+        ...(config.secretOverrides
+            ? { secretOverrides: config.secretOverrides }
+            : {}),
+        ...(config.variableOverrides
+            ? { variableOverrides: config.variableOverrides }
+            : {}),
+        ...(config.credentialOverrides
+            ? { credentialOverrides: config.credentialOverrides }
+            : {}),
     });
 };

package/dist/wirings/rpc/wire-remote-addon.d.ts

@@ -0,0 +1,47 @@
+import type { CoreServices, PikkuWire } from '../../types/core.types.js';
+/**
+ * How the consumer supplies the token the hosted addon's auth expects.
+ *
+ * This is a CLIENT authenticating to a hosted library — NOT pikku's trusted
+ * machine-to-machine mesh (which uses `PIKKU_REMOTE_SECRET`). The consumer binds
+ * the addon's declared auth requirement to a local source:
+ *  - `credentialId` — per-user credential, resolved via `wire.getCredential(id)`
+ *  - `secretId`     — platform key, resolved via the secrets service
+ *  - `resolve`      — custom escape hatch
+ * Omit entirely when the addon declares its remote surface is public.
+ *
+ * The value is sent `Authorization: Bearer <token>` by default; a non-default
+ * header is declared once by the addon (its meta), never chosen here.
+ */
+export type RemoteAddonAuth = {
+    credentialId: string;
+} | {
+    secretId: string;
+} | {
+    resolve: (services: CoreServices, wire: PikkuWire) => string | Promise<string>;
+};
+export type WireRemoteAddonConfig = {
+    /** Consumer-facing namespace, e.g. `registry` → `rpc('registry:getOpenApi')` */
+    name: string;
+    /**
+     * The addon package. Installed as a **devDependency** (types only — its
+     * handlers run on the host); `pikku verify` enforces this.
+     */
+    package: string;
+    /** Base URL of the host serving the addon's remote surface. */
+    serverUrl: string | ((services: CoreServices) => string | Promise<string>);
+    /** Bind the addon's declared auth to a local source. Omit if the surface is public. */
+    auth?: RemoteAddonAuth;
+    /** Map a consumer-facing fn name → the remote fn name, when they differ (rare). */
+    remoteName?: (fn: string) => string;
+    tags?: string[];
+};
+/**
+ * Consume a hosted addon's `remote: true` RPCs transparently over HTTP.
+ *
+ * Unlike `wireAddon` (which bundles the addon's functions in-process, a
+ * production dependency), `wireRemoteAddon` dispatches `rpc('name:fn')` to the
+ * host at `serverUrl`, fully typed — the addon ships as a devDependency (types
+ * only). See {@link RemoteAddonAuth} for how auth is bound.
+ */
+export declare const wireRemoteAddon: (config: WireRemoteAddonConfig) => void;

package/dist/wirings/rpc/wire-remote-addon.js

@@ -0,0 +1,19 @@
+import { pikkuState } from '../../pikku-state.js';
+/**
+ * Consume a hosted addon's `remote: true` RPCs transparently over HTTP.
+ *
+ * Unlike `wireAddon` (which bundles the addon's functions in-process, a
+ * production dependency), `wireRemoteAddon` dispatches `rpc('name:fn')` to the
+ * host at `serverUrl`, fully typed — the addon ships as a devDependency (types
+ * only). See {@link RemoteAddonAuth} for how auth is bound.
+ */
+export const wireRemoteAddon = (config) => {
+    pikkuState(null, 'addons', 'packages').set(config.name, {
+        package: config.package,
+        tags: config.tags,
+        remote: true,
+        serverUrl: config.serverUrl,
+        ...(config.auth ? { remoteAuth: config.auth } : {}),
+        ...(config.remoteName ? { remoteName: config.remoteName } : {}),
+    });
+};

package/dist/wirings/scope/index.d.ts

@@ -0,0 +1,3 @@
+export { wireScope } from './wire-scope.js';
+export { flattenScopeDefinitions, validateAndBuildScopeDefinitionsMeta, } from './validate-scope-definitions.js';
+export type { CoreScopes, CoreScopeNode, FlatScope, ScopeDefinitionMeta, ScopeDefinitionsMeta, ScopeDefinitions, ScopeNodeMeta, } from './scope.types.js';

package/dist/wirings/scope/index.js

@@ -0,0 +1,2 @@
+export { wireScope } from './wire-scope.js';
+export { flattenScopeDefinitions, validateAndBuildScopeDefinitionsMeta, } from './validate-scope-definitions.js';

package/dist/wirings/scope/scope.types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A node within a scope tree. Every node is itself a grantable scope — given
+ * `admin` containing `invoices` containing `create`, all three of `admin`,
+ * `admin:invoices` and `admin:invoices:create` are valid scope ids.
+ */
+export type CoreScopeNode = {
+    /** Short human-readable name, e.g. "Administration". */
+    displayName?: string;
+    /** Longer-form description, surfaced in the console when granting. */
+    description?: string;
+    /** Nested scopes, keyed by their segment. */
+    scopes?: Record<string, CoreScopeNode>;
+};
+/**
+ * Scope trees to declare, keyed by their root segment. A root is just a node —
+ * it is named by its key, exactly like every node beneath it. A key must not
+ * contain `:` or be `*`.
+ */
+export type CoreScopes = Record<string, CoreScopeNode>;
+export type ScopeNodeMeta = {
+    displayName?: string;
+    description?: string;
+    scopes?: Record<string, ScopeNodeMeta>;
+};
+export type ScopeDefinitionMeta = {
+    name: string;
+    displayName?: string;
+    description?: string;
+    scopes?: Record<string, ScopeNodeMeta>;
+    sourceFile?: string;
+};
+export type ScopeDefinitions = ScopeDefinitionMeta[];
+export type ScopeDefinitionsMeta = Record<string, ScopeDefinitionMeta>;
+/** A single scope, flattened out of the declared tree. */
+export type FlatScope = {
+    /** Colon-delimited id, e.g. `admin:invoices:create`. */
+    id: string;
+    description?: string;
+};

package/dist/wirings/scope/scope.types.js

@@ -0,0 +1 @@
+export {};