@pikku/core 0.12.144 → 0.12.146

package/dist/crypto-utils.d.ts

@@ -24,10 +24,10 @@ export declare const encryptJSON: (secret: string, value: unknown) => Promise<st
  */
 export declare const decryptJSON: <T>(secret: string, token: string) => Promise<T>;
 /**
- * Namespaces the remote-RPC session key so the same deployment secret used for
+ * Namespaces the mesh-RPC session key so the same deployment secret used for
  * another purpose derives a different key. See knowledge/crypto.md.
  */
-export declare const REMOTE_SESSION_INFO = "pikku:remote-session";
+export declare const MESH_SESSION_INFO = "pikku:mesh-session";
 /** Shortest key material, in characters, that the `*WithKeyMaterial` helpers accept. */
 export declare const MIN_KEY_MATERIAL_LENGTH = 32;
 /**
@@ -44,7 +44,7 @@ export declare const assertStrongKeyMaterial: (name: string, keyMaterial: string
  * high-entropy key material by HKDF-SHA256, with a fresh random salt per call.
  *
  * `info` domain-separates the derived key, so the same deployment secret used for
- * two purposes (e.g. {@link REMOTE_SESSION_INFO}) yields two unrelated keys.
+ * two purposes (e.g. {@link MESH_SESSION_INFO}) yields two unrelated keys.
  *
  * @param name - The key material's name, for the weak-key error.
  * @param keyMaterial - At least {@link MIN_KEY_MATERIAL_LENGTH} characters.

package/dist/crypto-utils.js

@@ -109,10 +109,10 @@ export const decryptJSON = async (secret, token) => {
     return JSON.parse(decoder.decode(new Uint8Array(decrypted)));
 };
 /**
- * Namespaces the remote-RPC session key so the same deployment secret used for
+ * Namespaces the mesh-RPC session key so the same deployment secret used for
  * another purpose derives a different key. See knowledge/crypto.md.
  */
-export const REMOTE_SESSION_INFO = 'pikku:remote-session';
+export const MESH_SESSION_INFO = 'pikku:mesh-session';
 /** Shortest key material, in characters, that the `*WithKeyMaterial` helpers accept. */
 export const MIN_KEY_MATERIAL_LENGTH = 32;
 /**
@@ -143,7 +143,7 @@ const expandKeyMaterial = async (keyMaterial, info, salt) => {
  * high-entropy key material by HKDF-SHA256, with a fresh random salt per call.
  *
  * `info` domain-separates the derived key, so the same deployment secret used for
- * two purposes (e.g. {@link REMOTE_SESSION_INFO}) yields two unrelated keys.
+ * two purposes (e.g. {@link MESH_SESSION_INFO}) yields two unrelated keys.
  *
  * @param name - The key material's name, for the weak-key error.
  * @param keyMaterial - At least {@link MIN_KEY_MATERIAL_LENGTH} characters.

package/dist/function/function-meta.types.d.ts

@@ -165,7 +165,7 @@ export type FunctionMeta = FunctionRuntimeMeta & Partial<{
     exportedName: string;
     /**
      * RPC names this function's own body calls by literal name through
-     * `rpc.invoke(...)` / `rpc.remote(...)`. The deploy planner binds the
+     * `rpc.invoke(...)` / `rpc.mesh(...)`. The deploy planner binds the
      * function's unit to each callee's unit from this; a call with a computed
      * name is not listed, and is warned about instead.
      */

package/dist/{remote.d.ts → mesh.d.ts}

@@ -2,7 +2,7 @@ import type { JWTService } from './services/jwt-service.js';
 import type { SecretService } from './services/secret-service.js';
 /**
  * Authorization headers carrying a JWT-signed session and traceId for
- * `pikkuRemoteAuthMiddleware` on the receiving end. Used by every deployment
+ * `pikkuMeshAuthMiddleware` on the receiving end. Used by every deployment
  * service regardless of transport (HTTP, Lambda Invoke, service bindings).
  */
-export declare function buildRemoteHeaders(jwt: JWTService | undefined, secrets: SecretService | undefined, funcName: string, session?: unknown, traceId?: string): Promise<Record<string, string>>;
+export declare function buildMeshHeaders(jwt: JWTService | undefined, secrets: SecretService | undefined, funcName: string, session?: unknown, traceId?: string): Promise<Record<string, string>>;

package/dist/{remote.js → mesh.js}

@@ -1,43 +1,43 @@
-import { assertStrongKeyMaterial, encryptWithKeyMaterial, REMOTE_SESSION_INFO, } from './crypto-utils.js';
+import { assertStrongKeyMaterial, encryptWithKeyMaterial, MESH_SESSION_INFO, } from './crypto-utils.js';
 /**
- * An unset secret means remote auth is not configured, so the call goes out
+ * An unset secret means mesh auth is not configured, so the call goes out
  * unauthenticated. A secrets backend that fails is a different thing: sending
  * the call anyway would only earn a 401 from the peer with no hint why.
  */
-const readRemoteSecret = async (secrets) => {
+const readMeshSecret = async (secrets) => {
     if (!secrets) {
         return undefined;
     }
     try {
-        if (!(await secrets.hasSecret('PIKKU_REMOTE_SECRET'))) {
+        if (!(await secrets.hasSecret('PIKKU_MESH_SECRET'))) {
             return undefined;
         }
-        return (await secrets.getSecret('PIKKU_REMOTE_SECRET')).reveal();
+        return (await secrets.getSecret('PIKKU_MESH_SECRET')).reveal();
     }
     catch (cause) {
-        throw new Error('Could not read PIKKU_REMOTE_SECRET from the secrets service; refusing to send an unauthenticated remote call', { cause });
+        throw new Error('Could not read PIKKU_MESH_SECRET from the secrets service; refusing to send an unauthenticated mesh call', { cause });
     }
 };
 /**
  * Authorization headers carrying a JWT-signed session and traceId for
- * `pikkuRemoteAuthMiddleware` on the receiving end. Used by every deployment
+ * `pikkuMeshAuthMiddleware` on the receiving end. Used by every deployment
  * service regardless of transport (HTTP, Lambda Invoke, service bindings).
  */
-export async function buildRemoteHeaders(jwt, secrets, funcName, session, traceId) {
+export async function buildMeshHeaders(jwt, secrets, funcName, session, traceId) {
     const headers = {
         'content-type': 'application/json',
         ...(traceId && { 'x-request-id': traceId }),
     };
-    const secret = await readRemoteSecret(secrets);
+    const secret = await readMeshSecret(secrets);
     if (secret && jwt) {
-        assertStrongKeyMaterial('PIKKU_REMOTE_SECRET', secret);
+        assertStrongKeyMaterial('PIKKU_MESH_SECRET', secret);
         const sessionEnc = session
-            ? await encryptWithKeyMaterial('PIKKU_REMOTE_SECRET', secret, REMOTE_SESSION_INFO, {
+            ? await encryptWithKeyMaterial('PIKKU_MESH_SECRET', secret, MESH_SESSION_INFO, {
                 session,
             })
             : undefined;
         const token = await jwt.encode({ value: 5, unit: 'minute' }, {
-            aud: 'pikku-remote',
+            aud: 'pikku-mesh',
             fn: funcName,
             iat: Math.floor(Date.now() / 1000),
             session: sessionEnc,

package/dist/middleware/index.d.ts

@@ -1,9 +1,9 @@
 export { authAPIKey } from './auth-apikey.js';
 export { authCookie } from './auth-cookie.js';
 export { authBearer } from './auth-bearer.js';
-export { addonScopeCap, ADDON_HEADER, } from './addon-scope-cap.js';
+export { addonScopeCap, ADDON_HEADER } from './addon-scope-cap.js';
 export { remoteJobsSecret } from './remote-jobs-secret.js';
-export { pikkuRemoteAuthMiddleware } from './remote-auth.js';
+export { pikkuMeshAuthMiddleware } from './mesh-auth.js';
 export { cors } from './cors.js';
 export { requireOrigin, isAllowedOrigin, toOrigin } from './require-origin.js';
 export { telemetryOuter, telemetryInner } from './telemetry.js';

package/dist/middleware/index.js

@@ -1,9 +1,9 @@
 export { authAPIKey } from './auth-apikey.js';
 export { authCookie } from './auth-cookie.js';
 export { authBearer } from './auth-bearer.js';
-export { addonScopeCap, ADDON_HEADER, } from './addon-scope-cap.js';
+export { addonScopeCap, ADDON_HEADER } from './addon-scope-cap.js';
 export { remoteJobsSecret } from './remote-jobs-secret.js';
-export { pikkuRemoteAuthMiddleware } from './remote-auth.js';
+export { pikkuMeshAuthMiddleware } from './mesh-auth.js';
 export { cors } from './cors.js';
 export { requireOrigin, isAllowedOrigin, toOrigin } from './require-origin.js';
 export { telemetryOuter, telemetryInner } from './telemetry.js';

package/dist/middleware/{remote-auth.d.ts → mesh-auth.d.ts}

@@ -1,19 +1,19 @@
 /**
  * Authenticates calls between deployments of the same app, on the generated
- * remote-RPC route. Once `PIKKU_REMOTE_SECRET` is set it requires a
- * `Bearer` JWT with audience `pikku-remote`; a token bound to a function (`fn`)
- * is only accepted on that function's `/remote/rpc/<fn>` path, and any session
+ * mesh-RPC route. Once `PIKKU_MESH_SECRET` is set it requires a
+ * `Bearer` JWT with audience `pikku-mesh`; a token bound to a function (`fn`)
+ * is only accepted on that function's `/mesh/rpc/<fn>` path, and any session
  * it carries is decrypted with the secret and set on the wire.
  *
- * Without the secret it lets non-remote paths through and refuses
- * `/remote/rpc/*`, so the remote surface fails closed.
+ * Without the secret it lets non-mesh paths through and refuses
+ * `/mesh/rpc/*`, so the mesh surface fails closed.
  *
  * @throws {UnauthorizedError} On a missing, malformed, mis-addressed or
  * undecryptable token.
  * @throws {WeakKeyMaterialError} When the secret is too short to use.
  * @throws {Error} When the secret is set but no JWT service is configured.
  */
-export declare const pikkuRemoteAuthMiddleware: import("./middleware.types.js").CorePikkuMiddleware<import("../types/core.types.js").CoreSingletonServices<{
+export declare const pikkuMeshAuthMiddleware: import("./middleware.types.js").CorePikkuMiddleware<import("../types/core.types.js").CoreSingletonServices<{
     logLevel?: import("../services/logger.js").LogLevel;
     secrets?: {
         requireAllowedHosts?: boolean;

package/dist/middleware/{remote-auth.js → mesh-auth.js}

@@ -1,47 +1,47 @@
 import { UnauthorizedError } from '../errors/errors.js';
 import { pikkuMiddleware } from './middleware-factories.js';
-import { assertStrongKeyMaterial, decryptWithKeyMaterial, REMOTE_SESSION_INFO, } from '../crypto-utils.js';
-const REMOTE_RPC_PREFIX = '/remote/rpc/';
+import { assertStrongKeyMaterial, decryptWithKeyMaterial, MESH_SESSION_INFO, } from '../crypto-utils.js';
+const MESH_RPC_PREFIX = '/mesh/rpc/';
 /**
- * Whether this request targets the remote-RPC surface. Compared case-insensitively
+ * Whether this request targets the mesh-RPC surface. Compared case-insensitively
  * because the router matches routes that way (path-to-regexp defaults to
- * `sensitive: false`), so `/Remote/RPC/fn` reaches the same handler as
- * `/remote/rpc/fn`. A case-sensitive check here let a case-varied path slip
+ * `sensitive: false`), so `/Mesh/RPC/fn` reaches the same handler as
+ * `/mesh/rpc/fn`. A case-sensitive check here let a case-varied path slip
  * past the trust gate and the token's `fn` binding while still being dispatched.
  */
-const isRemoteRpcPath = (path) => path.toLowerCase().startsWith(REMOTE_RPC_PREFIX);
+const isMeshRpcPath = (path) => path.toLowerCase().startsWith(MESH_RPC_PREFIX);
 /**
  * Authenticates calls between deployments of the same app, on the generated
- * remote-RPC route. Once `PIKKU_REMOTE_SECRET` is set it requires a
- * `Bearer` JWT with audience `pikku-remote`; a token bound to a function (`fn`)
- * is only accepted on that function's `/remote/rpc/<fn>` path, and any session
+ * mesh-RPC route. Once `PIKKU_MESH_SECRET` is set it requires a
+ * `Bearer` JWT with audience `pikku-mesh`; a token bound to a function (`fn`)
+ * is only accepted on that function's `/mesh/rpc/<fn>` path, and any session
  * it carries is decrypted with the secret and set on the wire.
  *
- * Without the secret it lets non-remote paths through and refuses
- * `/remote/rpc/*`, so the remote surface fails closed.
+ * Without the secret it lets non-mesh paths through and refuses
+ * `/mesh/rpc/*`, so the mesh surface fails closed.
  *
  * @throws {UnauthorizedError} On a missing, malformed, mis-addressed or
  * undecryptable token.
  * @throws {WeakKeyMaterialError} When the secret is too short to use.
  * @throws {Error} When the secret is set but no JWT service is configured.
  */
-export const pikkuRemoteAuthMiddleware = pikkuMiddleware(async ({ secrets, jwt }, { http, setInitialSession }, next) => {
+export const pikkuMeshAuthMiddleware = pikkuMiddleware(async ({ secrets, jwt }, { http, setInitialSession }, next) => {
     if (!http?.request || !secrets) {
         return next();
     }
     let secret;
     try {
-        secret = (await secrets.getSecret('PIKKU_REMOTE_SECRET')).reveal();
+        secret = (await secrets.getSecret('PIKKU_MESH_SECRET')).reveal();
     }
     catch {
-        if (isRemoteRpcPath(http.request.path())) {
+        if (isMeshRpcPath(http.request.path())) {
             throw new UnauthorizedError();
         }
         return next();
     }
-    assertStrongKeyMaterial('PIKKU_REMOTE_SECRET', secret);
+    assertStrongKeyMaterial('PIKKU_MESH_SECRET', secret);
     if (!jwt) {
-        throw new Error('PIKKU_REMOTE_SECRET set but JWT service missing');
+        throw new Error('PIKKU_MESH_SECRET set but JWT service missing');
     }
     const authHeader = http.request.header('authorization') ||
         http.request.header('Authorization');
@@ -59,20 +59,20 @@ export const pikkuRemoteAuthMiddleware = pikkuMiddleware(async ({ secrets, jwt }
     catch {
         throw new UnauthorizedError();
     }
-    if (payload?.aud !== 'pikku-remote') {
+    if (payload?.aud !== 'pikku-mesh') {
         throw new UnauthorizedError();
     }
-    if (payload?.fn && isRemoteRpcPath(http.request.path())) {
+    if (payload?.fn && isMeshRpcPath(http.request.path())) {
         // The prefix length is the same in any case, so slicing the raw path
         // keeps the requested function name in its original case for the compare.
-        const fn = decodeURIComponent(http.request.path().slice(REMOTE_RPC_PREFIX.length));
+        const fn = decodeURIComponent(http.request.path().slice(MESH_RPC_PREFIX.length));
         if (fn && payload.fn !== fn) {
             throw new UnauthorizedError();
         }
     }
     if (payload?.session) {
         try {
-            const decrypted = await decryptWithKeyMaterial('PIKKU_REMOTE_SECRET', secret, REMOTE_SESSION_INFO, payload.session);
+            const decrypted = await decryptWithKeyMaterial('PIKKU_MESH_SECRET', secret, MESH_SESSION_INFO, payload.session);
             if (decrypted?.session && setInitialSession) {
                 setInitialSession(decrypted.session);
             }

package/dist/types/core.types.d.ts

@@ -255,16 +255,16 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
      * sets it; services that log fall back to the singleton logger.
      */
     logger: Logger;
-    /** Trace ID for distributed tracing — propagated across remote RPC calls via the x-request-id header */
+    /** Trace ID for distributed tracing — propagated across mesh RPC calls via the x-request-id header */
     traceId: string;
     functionId: string;
     addonNamespace: string;
     http: PikkuHTTP<In>;
     mcp: PikkuMCP<MCPTools>;
-    channel: [IsChannel] extends [null] ? PikkuChannel<unknown, Out, TypedRPC['remote']> : PikkuChannel<unknown, Out, TypedRPC['remote']> | undefined;
+    channel: [IsChannel] extends [null] ? PikkuChannel<unknown, Out, TypedRPC['mesh']> : PikkuChannel<unknown, Out, TypedRPC['mesh']> | undefined;
     scheduledTask: PikkuScheduledTask;
     queue: PikkuQueue;
-    cli: PikkuCLI<TypedRPC['remote']>;
+    cli: PikkuCLI<TypedRPC['mesh']>;
     workflow: TypedWorkflow;
     scenario: TypedScenario;
     virtualUsers: TScenarioVirtualUsers;

package/dist/types/state.types.d.ts

@@ -42,7 +42,7 @@ export interface PikkuPackageState {
             rpcEndpoint?: string;
             auth?: boolean;
             tags?: string[];
-            /** Which functions `rpc.exposed` may call: unset/`true` keeps the addon's own `expose`, `false` none, a list exactly those */
+            /** Which functions `rpc.exposed` may call, from those the addon declared `expose: true`: `true` all of them, a list those named, unset/`false` none */
             expose?: boolean | string[];
             /** Required of every function in this package, on top of the function's own */
             scopes?: string[];
@@ -78,10 +78,14 @@ export interface PikkuPackageState {
             } | {
                 secretId: string;
             } | {
-                resolve: (services: any, wire: any) => string | Promise<string>;
+                resolve: (services: any, wire: any) => string | null | Promise<string | null>;
             };
-            /** Map consumer-facing fn name → remote fn name (wireRemoteAddon) */
+            /** Map consumer-facing base fn name → remote fn name (wireRemoteAddon); `@vN` is appended after */
             remoteName?: (fn: string) => string;
+            /** Milliseconds a remote addon call may take before it is aborted (wireRemoteAddon) */
+            remoteTimeoutMs?: number;
+            /** Extra headers sent on every call to the hosted addon (wireRemoteAddon) */
+            remoteHeaders?: (services: any, wire: any) => Record<string, string> | Promise<Record<string, string>>;
         }>;
     };
     http: {

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

@@ -10,7 +10,12 @@ export type RemoteAddonAuthBinding = {
 } | {
     secretId: string;
 } | {
-    resolve: (services: CoreServices, wire: PikkuRawWire) => string | SecretValue<string> | Promise<string | SecretValue<string>>;
+    /**
+     * `null` says this call carries no credential, for a host whose surface
+     * is public to anonymous callers. An empty or undefined token still
+     * throws, so a resolver that lost its token does not go out anonymous.
+     */
+    resolve: (services: CoreServices, wire: PikkuRawWire) => string | SecretValue<string> | null | Promise<string | SecretValue<string> | null>;
 };
 /**
  * Thrown (401) when a remote addon's token cannot be resolved: the binding needs credential
@@ -21,5 +26,8 @@ export declare class RemoteAddonAuthError extends PikkuError {
     readonly namespace: string;
     constructor(namespace: string, detail: string);
 }
-/** Returns `null` only when no auth is bound; an empty resolved token throws. */
+/**
+ * Returns `null` when no auth is bound or `resolve` answers `null`; any other
+ * empty token throws.
+ */
 export declare function resolveRemoteAddonToken(auth: RemoteAddonAuthBinding | undefined, services: CoreServices, wire: PikkuRawWire, namespace: string): Promise<string | null>;

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

@@ -16,7 +16,10 @@ addError(RemoteAddonAuthError, {
     status: 401,
     message: 'Remote addon authentication could not be resolved.',
 });
-/** Returns `null` only when no auth is bound; an empty resolved token throws. */
+/**
+ * Returns `null` when no auth is bound or `resolve` answers `null`; any other
+ * empty token throws.
+ */
 export async function resolveRemoteAddonToken(auth, services, wire, namespace) {
     if (!auth) {
         return null;
@@ -33,6 +36,8 @@ export async function resolveRemoteAddonToken(auth, services, wire, namespace) {
     }
     else if (typeof auth.resolve === 'function') {
         token = await auth.resolve(services, wire);
+        if (token === null)
+            return null;
     }
     // The wire is where a secret is meant to end up, so unwrap it here rather
     // than at each branch — `resolve` and `getCredential` may hand one back too.

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

@@ -0,0 +1,13 @@
+/** A `wireRemoteAddon` `package` value split into the package name and the optional semver range after it. */
+export type RemoteAddonPackageSpec = {
+    /** The package name, e.g. `@pikkustudio/addon-cloud-api`. */
+    name: string;
+    /** The semver range, e.g. `^1.4.0`. Absent when the spec names only the package. */
+    range?: string;
+};
+/**
+ * Splits `@scope/name@^1.4.0` into its name and range at the last `@` after
+ * the first character, so a scope's leading `@` is never taken for the
+ * separator. Throws when either half is empty.
+ */
+export declare const parseRemoteAddonPackage: (spec: string) => RemoteAddonPackageSpec;

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

@@ -0,0 +1,21 @@
+/**
+ * Splits `@scope/name@^1.4.0` into its name and range at the last `@` after
+ * the first character, so a scope's leading `@` is never taken for the
+ * separator. Throws when either half is empty.
+ */
+export const parseRemoteAddonPackage = (spec) => {
+    const trimmed = spec.trim();
+    const at = trimmed.lastIndexOf('@');
+    if (at <= 0) {
+        if (!trimmed || trimmed === '@') {
+            throw new Error(`'${spec}' is not a package name`);
+        }
+        return { name: trimmed };
+    }
+    const name = trimmed.slice(0, at);
+    const range = trimmed.slice(at + 1).trim();
+    if (!range) {
+        throw new Error(`'${spec}' ends in '@' with no version range after it. Write '${name}@^1.0.0', or drop the '@'.`);
+    }
+    return { name, range };
+};

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

@@ -23,10 +23,10 @@ export type WireAddonConfig = {
     mcp?: boolean | string[];
     /**
      * Which of the addon's functions `rpc.exposed` may call, under
-     * `<name>:<function>`. Unset or `true` keeps the functions the addon itself
-     * declared `expose: true`; `false` exposes none of them; a list names exactly
-     * the functions to expose, whether or not the addon declared them, and is
-     * typed against the addon's function names.
+     * `<name>:<function>`. Only functions the addon itself declared
+     * `expose: true` can ever be exposed: `true` exposes all of them, a list
+     * only those it names, and unset or `false` none. A listed function the
+     * addon did not declare stays unexposed.
      *
      * knowledge: decisions/security/wire-addon-expose-selects-the-rpc-surface.md
      */
@@ -106,8 +106,8 @@ export type WireAddonConfig = {
 export declare const wireAddon: (config: WireAddonConfig) => void;
 /**
  * Whether `rpc.exposed` may reach an addon function through the instance that
- * resolved it. The wiring's `expose` decides when it is `false` or a list;
- * otherwise the addon's own `expose: true` does.
+ * resolved it. Both sides must agree: the addon declares the function
+ * `expose: true`, and the wiring opts in with `true` or a list naming it.
  *
  * knowledge: decisions/security/wire-addon-expose-selects-the-rpc-surface.md
  */

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

@@ -39,19 +39,19 @@ export const wireAddon = (config) => {
 };
 /**
  * Whether `rpc.exposed` may reach an addon function through the instance that
- * resolved it. The wiring's `expose` decides when it is `false` or a list;
- * otherwise the addon's own `expose: true` does.
+ * resolved it. Both sides must agree: the addon declares the function
+ * `expose: true`, and the wiring opts in with `true` or a list naming it.
  *
  * knowledge: decisions/security/wire-addon-expose-selects-the-rpc-surface.md
  */
 export const isAddonFunctionExposed = (expose, functionName, declaredExpose) => {
+    if (declaredExpose !== true) {
+        return false;
+    }
     if (Array.isArray(expose)) {
         return expose.includes(functionName);
     }
-    if (expose === false) {
-        return false;
-    }
-    return declaredExpose === true;
+    return expose === true;
 };
 /**
  * The addon configs a running function is governed by: the named instance when

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

@@ -5,22 +5,56 @@ export type RemoteAddonAuth = {
 } | {
     secretId: string;
 } | {
-    resolve: (services: CoreServices, wire: PikkuWire) => string | Promise<string>;
+    /** `null` sends this call without a credential, for a public surface. */
+    resolve: (services: CoreServices, wire: PikkuWire) => string | null | Promise<string | null>;
 };
+/**
+ * Sent on every call to a hosted addon. The host's `rpc.exposed` then answers
+ * only functions in the addon's remote contract (`remote: true`), so a consumer
+ * holding a token cannot reach the host's other exposed functions through it.
+ * It can only narrow what the host answers, never widen it.
+ *
+ * knowledge: decisions/security/wire-addon-expose-selects-the-rpc-surface.md
+ */
+export declare const REMOTE_CONTRACT_HEADER = "x-pikku-remote-contract";
+/** How long a call to a hosted addon may take when `timeoutMs` is not set. */
+export declare const DEFAULT_REMOTE_ADDON_TIMEOUT_MS = 30000;
 /** Options for `wireRemoteAddon`: the namespace, the contract package, where the addon is deployed and how calls authenticate. */
 export type WireRemoteAddonConfig = {
     /** Consumer-facing namespace, e.g. `registry` → `rpc('registry:getOpenApi')` */
     name: string;
-    /** Must be installed as a devDependency — `pikku verify` enforces this. */
+    /**
+     * The contract package, as a string literal. `@scope/name@^1.4.0` pins a
+     * range: `pikku all` downloads the addon's SDK from the registry and
+     * records it in `pikku-addons.lock`. A bare `@scope/name` must be installed
+     * as a devDependency instead — `pikku verify` enforces both.
+     */
     package: string;
     /** Where the addon is deployed, e.g. `https://registry.example.com`. A function when it varies per environment. */
     serverUrl: string | ((services: CoreServices) => string | Promise<string>);
     /** Omit when the addon declares its remote surface public. */
     auth?: RemoteAddonAuth;
-    /** Map a consumer-facing fn name → the remote fn name, when they differ (rare). */
+    /**
+     * Map a consumer-facing fn name → the remote fn name, when they differ (rare).
+     * It gets the base name; a versioned call appends `@vN` to what it returns.
+     */
     remoteName?: (fn: string) => string;
     /** Applied to every function the addon contributes, so tag middleware and permissions reach them. */
     tags?: string[];
+    /**
+     * Which of the addon's contract functions this app's `rpc.exposed` — and so
+     * its public `POST /rpc/:rpcName` — forwards to the host, under
+     * `<name>:<function>`. `true` forwards every contract function, a list only
+     * those named, and unset or `false` none: server-side `rpc('<name>:fn')`
+     * calls are unaffected.
+     *
+     * knowledge: decisions/security/wire-addon-expose-selects-the-rpc-surface.md
+     */
+    expose?: boolean | string[];
+    /** Milliseconds a call may take before it is aborted. Defaults to {@link DEFAULT_REMOTE_ADDON_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    /** Extra headers for every call to the host. Cannot replace the auth, trace or contract headers. */
+    headers?: (services: CoreServices, wire: PikkuWire) => Record<string, string> | Promise<Record<string, string>>;
 };
 /**
  * Installs an addon that runs as its own deployed service: the contract is

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

@@ -1,15 +1,32 @@
 import { pikkuState } from '../../pikku-state.js';
+import { parseRemoteAddonPackage } from './remote-addon-package.js';
+/**
+ * Sent on every call to a hosted addon. The host's `rpc.exposed` then answers
+ * only functions in the addon's remote contract (`remote: true`), so a consumer
+ * holding a token cannot reach the host's other exposed functions through it.
+ * It can only narrow what the host answers, never widen it.
+ *
+ * knowledge: decisions/security/wire-addon-expose-selects-the-rpc-surface.md
+ */
+export const REMOTE_CONTRACT_HEADER = 'x-pikku-remote-contract';
+/** How long a call to a hosted addon may take when `timeoutMs` is not set. */
+export const DEFAULT_REMOTE_ADDON_TIMEOUT_MS = 30_000;
 /**
  * Installs an addon that runs as its own deployed service: the contract is
  * local, the calls go over the wire to the addon's own host.
  */
 export const wireRemoteAddon = (config) => {
     pikkuState(null, 'addons', 'packages').set(config.name, {
-        package: config.package,
+        package: parseRemoteAddonPackage(config.package).name,
         tags: config.tags,
         remote: true,
         serverUrl: config.serverUrl,
+        ...(config.expose !== undefined ? { expose: config.expose } : {}),
         ...(config.auth ? { remoteAuth: config.auth } : {}),
         ...(config.remoteName ? { remoteName: config.remoteName } : {}),
+        ...(config.timeoutMs !== undefined
+            ? { remoteTimeoutMs: config.timeoutMs }
+            : {}),
+        ...(config.headers ? { remoteHeaders: config.headers } : {}),
     });
 };

package/dist/wirings/channel/channel-rpc-service.d.ts

@@ -7,7 +7,7 @@ import { type ChannelRPCValidator } from './channel-rpc.types.js';
  * inbound route of its own.
  *
  * It slots into the existing `services.deploymentService` hole, leaving
- * `rpc.remote` resolution, session propagation and traceId plumbing unchanged.
+ * `rpc.mesh` resolution, session propagation and traceId plumbing unchanged.
  */
 export declare class ChannelDeploymentService implements DeploymentService {
     private readonly send;

package/dist/wirings/channel/channel-rpc-service.js

@@ -6,7 +6,7 @@ import { CHANNEL_RPC_REQUEST, CHANNEL_RPC_RESPONSE, ChannelRPCError, isChannelRP
  * inbound route of its own.
  *
  * It slots into the existing `services.deploymentService` hole, leaving
- * `rpc.remote` resolution, session propagation and traceId plumbing unchanged.
+ * `rpc.mesh` resolution, session propagation and traceId plumbing unchanged.
  */
 export class ChannelDeploymentService {
     send;

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

@@ -75,6 +75,7 @@ export interface CLICommandMeta {
     subcommands?: Record<string, CLICommandMeta>;
     middleware?: MiddlewareMetadata[];
     isDefault?: boolean;
+    hidden?: boolean;
 }
 /**
  * CLI metadata collection (per program)
@@ -209,6 +210,8 @@ export type CoreCLICommandConfig<FuncConfig, PikkuMiddleware extends CorePikkuMi
     permissions?: any[];
     /** Runs when the parent is invoked with no subcommand named. */
     isDefault?: boolean;
+    /** Still runs, but is left out of `--help`: for commands a program invokes, not a person. */
+    hidden?: boolean;
 };
 /**
  * CLI command definition
@@ -227,6 +230,7 @@ export interface CoreCLICommand<In, Out, PikkuFunctionConfig extends CorePikkuFu
     tags?: string[];
     subcommands?: Subcommands;
     isDefault?: boolean;
+    hidden?: boolean;
 }
 /**
  * Shorthand command definition (just a function)

package/dist/wirings/cli/command-parser.js

@@ -494,6 +494,8 @@ export function generateCommandHelp(programName, allMeta, commandPath = []) {
         lines.push('');
         lines.push('Commands:');
         for (const [name, cmd] of Object.entries(meta.commands)) {
+            if (cmd.hidden)
+                continue;
             const desc = cmd.description || '';
             const defaultMarker = cmd.isDefault ? ' (default)' : '';
             lines.push(`  ${name.padEnd(20)} ${desc}${defaultMarker}`);
@@ -532,6 +534,8 @@ export function generateCommandHelp(programName, allMeta, commandPath = []) {
             lines.push('');
             lines.push('Subcommands:');
             for (const [name, sub] of Object.entries(commandMeta.subcommands)) {
+                if (sub.hidden)
+                    continue;
                 const desc = sub.description || '';
                 lines.push(`  ${name.padEnd(20)} ${desc}`);
             }

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

@@ -1,2 +1,2 @@
-export { PikkuRPCService, rpcService, RPCNotFoundError, RemoteAddonConfigError, RemoteAddonRequestError, } from './rpc-runner.js';
+export { PikkuRPCService, rpcService, RPCNotFoundError, RemoteAddonConfigError, RemoteAddonFailedError, RemoteAddonTimeoutError, } from './rpc-runner.js';
 export type { PikkuRPC, RPCMeta } from './rpc-types.js';

package/dist/wirings/rpc/index.js

@@ -1 +1 @@
-export { PikkuRPCService, rpcService, RPCNotFoundError, RemoteAddonConfigError, RemoteAddonRequestError, } from './rpc-runner.js';
+export { PikkuRPCService, rpcService, RPCNotFoundError, RemoteAddonConfigError, RemoteAddonFailedError, RemoteAddonTimeoutError, } from './rpc-runner.js';

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

@@ -11,16 +11,23 @@ import type { PikkuRPC, ResolvedFunction } from './rpc-types.js';
  */
 export declare class RPCNotFoundError extends PikkuError {
     readonly rpcName: string;
-    constructor(rpcName: string);
+    constructor(rpcName: string, message?: string);
 }
 /** Thrown when a remote addon's configuration cannot be used, for example when its `serverUrl` resolves empty. Maps to HTTP 500. */
 export declare class RemoteAddonConfigError extends PikkuError {
     constructor(namespace: string, detail: string);
 }
-/** Thrown when a remote addon answers an RPC with a non-2xx status. Maps to HTTP 502; the upstream status is kept on `httpStatus` and the first 300 characters of its body in the message. */
-export declare class RemoteAddonRequestError extends PikkuError {
-    readonly httpStatus: number;
-    constructor(namespace: string, fnName: string, status: number, detail: string);
+/**
+ * Thrown when a remote addon fails on its own side — a 5xx, an unreachable
+ * host, or a response that is not JSON. Maps to HTTP 502. What went wrong is
+ * logged on this host; none of it reaches the caller.
+ */
+export declare class RemoteAddonFailedError extends PikkuError {
+    constructor(namespace: string, fnName: string);
+}
+/** Thrown when a remote addon does not answer within the wiring's `timeoutMs`. Maps to HTTP 504. */
+export declare class RemoteAddonTimeoutError extends PikkuError {
+    constructor(namespace: string, fnName: string, timeoutMs: number);
 }
 export declare class AddonNotUsedError extends PikkuError {
     constructor(caller: string, target: string);
@@ -72,7 +79,7 @@ export declare class ContextAwareRPCService {
      * the tree behind it.
      */
     get agent(): PikkuRPC['agent'];
-    remote<In = any, Out = any>(funcName: string, data: In): Promise<Out>;
+    mesh<In = any, Out = any>(funcName: string, data: In): Promise<Out>;
 }
 /**
  * Builds the `rpc` object handed to every function on its wire.
@@ -81,7 +88,7 @@ export declare class ContextAwareRPCService {
  * `DeploymentService` when the function lives in another deployment unit.
  * `rpc.exposed` does the same but only reaches functions marked `expose: true`
  * (and, for addons, those the consuming app exposes), which is what the public
- * RPC endpoint uses. `rpc.remote` always goes through the `DeploymentService`.
+ * RPC endpoint uses. `rpc.mesh` always goes through the `DeploymentService`.
  * Calls carry the caller's wire, so the session and trace ID propagate. An addon
  * can only call the addons it lists in `uses`.
  *

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

@@ -6,6 +6,8 @@ import { pikkuState } from '../../pikku-state.js';
 import { PikkuError, addError } from '../../errors/error-handler.js';
 import { parseVersionedId } from '../../version.js';
 import { resolveRemoteAddonToken } from '../addon/remote-addon-auth.js';
+import { DEFAULT_REMOTE_ADDON_TIMEOUT_MS, REMOTE_CONTRACT_HEADER, } from '../addon/wire-remote-addon.js';
+import { BadRequestError, ConflictError, ForbiddenError, GoneError, LockedError, NotFoundError, PayloadTooLargeError, PaymentRequiredError, PreconditionFailedError, TooManyRequestsError, UnauthorizedError, UnprocessableContentError, UnsupportedMediaTypeError, } from '../../errors/errors.js';
 /**
  * The function runner, reached lazily. `function-runner` builds every
  * invocation's `wire.rpc` from this module, so a static import back would be a
@@ -31,8 +33,8 @@ const resolveWireSession = async (wire) => typeof wire.getSession === 'function'
  */
 export class RPCNotFoundError extends PikkuError {
     rpcName;
-    constructor(rpcName) {
-        super(`RPC function not found: ${rpcName}`);
+    constructor(rpcName, message = `RPC function not found: ${rpcName}`) {
+        super(message);
         this.rpcName = rpcName;
     }
 }
@@ -51,18 +53,119 @@ addError(RemoteAddonConfigError, {
     status: 500,
     message: 'Remote addon is misconfigured.',
 });
-/** Thrown when a remote addon answers an RPC with a non-2xx status. Maps to HTTP 502; the upstream status is kept on `httpStatus` and the first 300 characters of its body in the message. */
-export class RemoteAddonRequestError extends PikkuError {
-    httpStatus;
-    constructor(namespace, fnName, status, detail) {
-        super(`Remote addon '${namespace}:${fnName}' returned ${status}${detail ? `: ${detail}` : ''}`);
-        this.httpStatus = status;
+/**
+ * Thrown when a remote addon fails on its own side — a 5xx, an unreachable
+ * host, or a response that is not JSON. Maps to HTTP 502. What went wrong is
+ * logged on this host; none of it reaches the caller.
+ */
+export class RemoteAddonFailedError extends PikkuError {
+    constructor(namespace, fnName) {
+        super(`Remote addon '${namespace}:${fnName}' failed`);
     }
 }
-addError(RemoteAddonRequestError, {
+addError(RemoteAddonFailedError, {
     status: 502,
-    message: 'Remote addon request failed.',
+    message: 'Remote addon failed.',
 });
+/** Thrown when a remote addon does not answer within the wiring's `timeoutMs`. Maps to HTTP 504. */
+export class RemoteAddonTimeoutError extends PikkuError {
+    constructor(namespace, fnName, timeoutMs) {
+        super(`Remote addon '${namespace}:${fnName}' did not answer within ${timeoutMs}ms`);
+    }
+}
+addError(RemoteAddonTimeoutError, {
+    status: 504,
+    message: 'Remote addon timed out.',
+});
+/** Headers a wiring's `headers` hook cannot set: the call's auth, trace and contract. */
+const RESERVED_REMOTE_HEADERS = new Set([
+    'authorization',
+    'x-request-id',
+    REMOTE_CONTRACT_HEADER,
+    'content-type',
+    'accept',
+]);
+/**
+ * The plain error for each 4xx a remote addon may answer with, used when its
+ * body names no error this host knows. Constructed without a message, so the
+ * caller gets the registered generic one.
+ */
+const GENERIC_CLIENT_ERRORS = {
+    400: BadRequestError,
+    401: UnauthorizedError,
+    402: PaymentRequiredError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    409: ConflictError,
+    410: GoneError,
+    412: PreconditionFailedError,
+    413: PayloadTooLargeError,
+    415: UnsupportedMediaTypeError,
+    422: UnprocessableContentError,
+    423: LockedError,
+    429: TooManyRequestsError,
+};
+/**
+ * The registered error class named `name` whose status is `status`, rebuilt
+ * without running its constructor — a constructor's arguments are not on the
+ * wire, and running one with the wrong ones could throw or mislabel the error.
+ */
+const rebuildRegisteredError = (name, status, message) => {
+    if (typeof name !== 'string' || !name) {
+        return undefined;
+    }
+    for (const [ErrorClass, details] of pikkuState(null, 'misc', 'errors')) {
+        if (ErrorClass.name !== name || details.status !== status) {
+            continue;
+        }
+        const error = Object.create(ErrorClass.prototype);
+        Object.defineProperty(error, 'name', {
+            value: name,
+            writable: true,
+            configurable: true,
+        });
+        Object.defineProperty(error, 'message', {
+            value: typeof message === 'string' && message ? message : details.message,
+            writable: true,
+            configurable: true,
+        });
+        Error.captureStackTrace?.(error, rebuildRegisteredError);
+        return error;
+    }
+    return undefined;
+};
+/**
+ * The error a non-2xx response from a remote addon becomes on this host.
+ *
+ * A 4xx naming an error registered here with the same status is rebuilt as
+ * that error, message included — the addon already chose to show it to its
+ * caller. Any other 4xx becomes the generic error for its status. A 5xx, or a
+ * status with no generic error, becomes {@link RemoteAddonFailedError}. The
+ * response body is never passed through: anything beyond the rebuilt message
+ * is logged here and goes no further.
+ *
+ * knowledge: decisions/security/remote-addon-errors-are-rebuilt-not-passed-through.md
+ */
+const remoteAddonResponseError = async (res, namespace, fnName, logger) => {
+    const body = await res.text().catch(() => '');
+    if (res.status >= 400 && res.status < 500) {
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch { }
+        const rebuilt = rebuildRegisteredError(parsed?.name, res.status, parsed?.message);
+        if (rebuilt) {
+            return rebuilt;
+        }
+        const GenericError = GENERIC_CLIENT_ERRORS[res.status];
+        if (GenericError) {
+            return new GenericError();
+        }
+    }
+    logger.error(`Remote addon '${namespace}:${fnName}' answered ${res.status}: ${body.slice(0, 1000)}`);
+    return new RemoteAddonFailedError(namespace, fnName);
+};
 export class AddonNotUsedError extends PikkuError {
     constructor(caller, target) {
         super(`Addon '${caller}' called '${target}' but does not list it in its wireAddon 'uses'.`);
@@ -131,6 +234,27 @@ const resolvePikkuFunction = (rpcName, packageName = null) => {
     }
     return { pikkuFuncId: rpcMeta, packageName: null };
 };
+/**
+ * A caller from outside names `fn@vN` because it was built against that
+ * version. Serving it the latest instead would hand it a contract it does not
+ * know, so a version this host no longer has is refused, not resolved to the
+ * base name the way an internal caller's is. An unversioned function is its
+ * own v1.
+ */
+const refuseUnknownVersion = (rpcName) => {
+    const { baseName, version } = parseVersionedId(rpcName);
+    if (version === null)
+        return;
+    const rpc = pikkuState(null, 'rpc', 'meta');
+    if (rpc[rpcName])
+        return;
+    const current = rpc[baseName];
+    if (!current)
+        return;
+    if (version === 1 && parseVersionedId(current).version === null)
+        return;
+    throw new RPCNotFoundError(rpcName, `RPC function not found: ${rpcName}. Version ${version} of '${baseName}' is no longer served here; update the SDK this call was built against.`);
+};
 /**
  * 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
@@ -157,22 +281,36 @@ export class ContextAwareRPCService {
         let resolvedAddon = null;
         if (funcName.includes(':')) {
             resolvedAddon = resolveNamespace(funcName);
+            if (resolvedAddon?.addonConfig.remote) {
+                // A remote addon's functions have no meta on this host. Its contract
+                // stands in for the addon's own `expose`, and the host enforces it:
+                // every forwarded call carries REMOTE_CONTRACT_HEADER.
+                if (!isAddonFunctionExposed(resolvedAddon.addonConfig.expose, parseVersionedId(resolvedAddon.function).baseName, true)) {
+                    throw new RPCNotFoundError(funcName);
+                }
+                return await this.rpc(funcName, data);
+            }
             if (resolvedAddon) {
                 functionMeta = pikkuState(resolvedAddon.package, 'function', 'meta')[resolvedAddon.function];
             }
         }
         else {
+            if (!this.packageName)
+                refuseUnknownVersion(funcName);
             const resolved = resolvePikkuFunction(funcName, this.packageName);
             functionMeta = pikkuState(resolved.packageName, 'function', 'meta')[resolved.pikkuFuncId];
         }
         if (!functionMeta) {
+            // Whether a function is in the remote contract is only known where its
+            // meta is, so a contract call never leaves this unit.
+            if (this.wire.http?.request?.header(REMOTE_CONTRACT_HEADER)) {
+                throw new RPCNotFoundError(funcName);
+            }
             // The addon runs in another deploy unit, which only carries the
-            // functions the analyzer found exposed. A wiring present here still
-            // gets to narrow what is forwarded.
+            // functions the analyzer found exposed. The wiring present here must
+            // still opt in to the function before it is forwarded.
             const refusedHere = resolvedAddon &&
-                (resolvedAddon.addonConfig.expose === false ||
-                    (Array.isArray(resolvedAddon.addonConfig.expose) &&
-                        !resolvedAddon.addonConfig.expose.includes(resolvedAddon.function)));
+                !isAddonFunctionExposed(resolvedAddon.addonConfig.expose, resolvedAddon.function, true);
             if (funcName.includes(':') &&
                 this.services.deploymentService &&
                 !refusedHere) {
@@ -186,6 +324,10 @@ export class ContextAwareRPCService {
         if (!exposed || functionMeta.scenarioStep) {
             throw new RPCNotFoundError(funcName);
         }
+        if (this.wire.http?.request?.header(REMOTE_CONTRACT_HEADER) &&
+            functionMeta.remote !== true) {
+            throw new RPCNotFoundError(funcName);
+        }
         return await this.rpc(funcName, data);
     }
     async rpc(funcName, data) {
@@ -323,33 +465,76 @@ export class ContextAwareRPCService {
         if (!serverUrl) {
             throw new RemoteAddonConfigError(namespace, 'serverUrl resolved empty');
         }
-        const remoteFn = cfg.remoteName ? cfg.remoteName(fnName) : fnName;
+        // The host serves `fn` as its own latest, which may be newer than the
+        // contract this consumer was built against, so a call always names a
+        // version: the caller's, or the newest in the SDK (registered by codegen).
+        const versionedFn = parseVersionedId(fnName).version !== null
+            ? fnName
+            : (pikkuState(cfg.package, 'rpc', 'meta')[fnName] ?? fnName);
+        // `remoteName` maps the base name; the version rides on the mapped name,
+        // so a lookup-table mapping still matches a versioned call.
+        const { baseName, version } = parseVersionedId(versionedFn);
+        const remoteFn = cfg.remoteName
+            ? `${cfg.remoteName(baseName)}${version !== null ? `@v${version}` : ''}`
+            : versionedFn;
         const token = await resolveRemoteAddonToken(cfg.remoteAuth, this.services, this.wire, namespace);
         const headers = {
             'content-type': 'application/json',
             accept: 'application/json',
         };
+        if (cfg.remoteHeaders) {
+            for (const [name, value] of Object.entries(await cfg.remoteHeaders(this.services, this.wire))) {
+                // Matched case-insensitively: `Authorization` next to `authorization`
+                // would reach the host as one combined value.
+                if (!RESERVED_REMOTE_HEADERS.has(name.toLowerCase())) {
+                    headers[name] = value;
+                }
+            }
+        }
+        headers[REMOTE_CONTRACT_HEADER] = '1';
         if (token) {
             headers.authorization = `Bearer ${token}`;
         }
         if (this.wire.traceId) {
             headers['x-request-id'] = this.wire.traceId;
         }
+        const timeoutMs = cfg.remoteTimeoutMs ?? DEFAULT_REMOTE_ADDON_TIMEOUT_MS;
         const base = serverUrl.replace(/\/+$/, '');
-        const res = await fetch(`${base}/remote/rpc/${encodeURIComponent(remoteFn)}`, {
-            method: 'POST',
-            headers,
-            body: JSON.stringify({ rpcName: remoteFn, data }),
-        });
+        let res;
+        try {
+            // The body the generated `POST /rpc/:rpcName` route reads, the same one
+            // the generated fetch client sends.
+            res = await fetch(`${base}/rpc/${encodeURIComponent(remoteFn)}`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({ rpcName: remoteFn, data }),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (e) {
+            if (e?.name === 'TimeoutError') {
+                throw new RemoteAddonTimeoutError(namespace, remoteFn, timeoutMs);
+            }
+            this.services.logger.error(`Remote addon '${namespace}:${remoteFn}' could not be reached: ${e instanceof Error ? e.message : e}`);
+            throw new RemoteAddonFailedError(namespace, remoteFn);
+        }
         if (!res.ok) {
-            const detail = (await res.text().catch(() => '')).slice(0, 300);
-            throw new RemoteAddonRequestError(namespace, remoteFn, res.status, detail);
+            throw await remoteAddonResponseError(res, namespace, remoteFn, this.services.logger);
         }
         if (res.status === 204) {
             return undefined;
         }
         const text = await res.text();
-        return (text ? JSON.parse(text) : undefined);
+        if (!text) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            this.services.logger.error(`Remote addon '${namespace}:${remoteFn}' answered ${res.status} with a body that is not JSON`);
+            throw new RemoteAddonFailedError(namespace, remoteFn);
+        }
     }
     async rpcWithWire(rpcName, data, wire) {
         const mergedWire = {
@@ -421,10 +606,10 @@ export class ContextAwareRPCService {
         }
         return createAgentRPC(this.wire, this.options);
     }
-    async remote(funcName, data) {
+    async mesh(funcName, data) {
         if (!this.services.deploymentService) {
-            throw new Error(`No DeploymentService configured for remote RPC: ${funcName}. ` +
-                `Set up a DeploymentService to enable remote function calls.`);
+            throw new Error(`No DeploymentService configured for mesh RPC: ${funcName}. ` +
+                `Set up a DeploymentService to enable mesh function calls.`);
         }
         const session = await resolveWireSession(this.wire);
         return this.services.deploymentService.invoke(funcName, data, session, this.wire.traceId);
@@ -437,7 +622,7 @@ export class ContextAwareRPCService {
  * `DeploymentService` when the function lives in another deployment unit.
  * `rpc.exposed` does the same but only reaches functions marked `expose: true`
  * (and, for addons, those the consuming app exposes), which is what the public
- * RPC endpoint uses. `rpc.remote` always goes through the `DeploymentService`.
+ * RPC endpoint uses. `rpc.mesh` always goes through the `DeploymentService`.
  * Calls carry the caller's wire, so the session and trace ID propagate. An addon
  * can only call the addons it lists in `uses`.
  *
@@ -473,7 +658,7 @@ class ContextRPCView {
     depth;
     global = false;
     invoke;
-    remote;
+    mesh;
     exposed;
     startWorkflow;
     rpcWithWire;
@@ -481,7 +666,7 @@ class ContextRPCView {
         this.serviceRPC = serviceRPC;
         this.depth = depth;
         this.invoke = serviceRPC.rpc.bind(serviceRPC);
-        this.remote = serviceRPC.remote.bind(serviceRPC);
+        this.mesh = serviceRPC.mesh.bind(serviceRPC);
         this.exposed = serviceRPC.rpcExposed.bind(serviceRPC);
         this.startWorkflow = serviceRPC.startWorkflow.bind(serviceRPC);
         this.rpcWithWire = serviceRPC.rpcWithWire.bind(serviceRPC);

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

@@ -1,12 +1,12 @@
 import type { CredentialOverrides } from '../credential/credential-overrides.js';
 import type { PikkuRawWire } from '../../types/core.types.js';
 import type { AgentInterruptResult } from '../agent/agent-interrupt.js';
-/** The `rpc` object on a function's wire. An app's generated types narrow `invoke`, `remote`, `startWorkflow` and `agent` to its own functions, workflows and agents; see {@link PikkuRPCService} for how each call is routed. */
-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> = {
+/** The `rpc` object on a function's wire. An app's generated types narrow `invoke`, `mesh`, `startWorkflow` and `agent` to its own functions, workflows and agents; see {@link PikkuRPCService} for how each call is routed. */
+export type PikkuRPC<Invoke extends (...args: any[]) => any = (...args: any[]) => any, Mesh 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;
-    remote: Remote;
+    mesh: Mesh;
     exposed: (name: string, data: any) => Promise<any>;
     /** Invoke an RPC with explicit wire fields merged over the caller's. */
     rpcWithWire: <In = any, Out = any>(rpcName: string, data: In, wire: PikkuRawWire) => Promise<Out>;
@@ -47,7 +47,7 @@ export interface ResolvedFunction {
         package: string;
         auth?: boolean;
         tags?: string[];
-        /** Set by the consuming app: which functions `rpc.exposed` may call */
+        /** Set by the consuming app: which of the addon's declared-exposed functions `rpc.exposed` may call */
         expose?: boolean | string[];
         rpcEndpoint?: string;
         secretOverrides?: Record<string, string>;
@@ -75,8 +75,11 @@ export interface ResolvedFunction {
         } | {
             secretId: string;
         } | {
-            resolve: (services: any, wire: any) => string | Promise<string>;
+            resolve: (services: any, wire: any) => string | null | Promise<string | null>;
         };
+        /** Maps the base fn name; a versioned call appends `@vN` after it. */
         remoteName?: (fn: string) => string;
+        remoteTimeoutMs?: number;
+        remoteHeaders?: (services: any, wire: any) => Record<string, string> | Promise<Record<string, string>>;
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.144",
+  "version": "0.12.146",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -49,7 +49,7 @@
     "./channel/local": "./dist/wirings/channel/local/index.js",
     "./channel/serverless": "./dist/wirings/channel/serverless/index.js",
     "./http": "./dist/wirings/http/index.js",
-    "./remote": "./dist/remote.js",
+    "./mesh": "./dist/mesh.js",
     "./queue": "./dist/wirings/queue/index.js",
     "./scheduler": "./dist/wirings/scheduler/index.js",
     "./trigger": "./dist/wirings/trigger/index.js",
@@ -118,7 +118,7 @@
   },
   "devDependencies": {
     "@ag-ui/core": "0.0.59",
-    "@pikku/deploy": "^0.12.16",
+    "@pikku/deploy": "^0.12.17",
     "@types/node": "^26.6.5",
     "esbuild": "~0.28.2",
     "tsx": "^4.23.15"