@pikku/core 0.12.145 → 0.12.147

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
      */
@@ -46,18 +46,22 @@ export type WireAddonConfig = {
     /** Filters this addon in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
     /**
-     * Mounts the screens the addon ships (see `defineScreens`) in the host under
-     * `/addons/<name>`. Without it the addon's screens are ignored. The package
-     * must declare at least one, or `pikku all` rejects the wiring.
+     * Mounts the screens the addon ships (see `pikkuStudio`) in the host, each at
+     * the path its `scope` gives it. Without it the addon's screens are ignored.
+     * The package must declare at least one, or `pikku all` rejects the wiring.
      */
     ui?: boolean;
     /** Required of every function in the addon, on top of the function's own. */
     scopes?: string[];
     /**
-     * The other addons this one may call, as `{ '<package>': '<name>' }`: the
-     * package it was written against, and the name that package is wired under
-     * in this app. The addon calls `'<package>:<function>'`; anything it did not
-     * list is refused, whatever else the app has wired.
+     * The other addons this one may call, as `{ '<alias>': '<name>' }`: the name
+     * the addon calls another by, and the name that addon is wired under in this
+     * app — by `wireAddon` or `wireRemoteAddon`, either serves. The alias is the
+     * one the addon's package.json declares under `pikku.uses`
+     * (`{ "stripe": "@acme/addon-stripe@^1.0.0" }`), or, for an addon that lists
+     * plain names, the package name itself. The addon calls
+     * `'<alias>:<function>'`; anything it did not declare, or this app did not
+     * map, is refused, whatever else the app has wired.
      */
     uses?: Record<string, string>;
     /** Points a secret the addon reads at a different key in this deployment, so two instances can hold different credentials. */
@@ -106,8 +110,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/agent/agent-rpc.js

@@ -1,4 +1,5 @@
 import { pikkuState } from '../../pikku-state.js';
+import { mapAddonCall } from '../addon/addon-reach.js';
 import { runAgent, resumeAgentSync } from './agent-runner.js';
 import { streamAgent, resumeAgent, interruptAgent } from './agent-stream.js';
 import { wrapChannelWithAGUI } from './agent-agui.js';
@@ -31,10 +32,10 @@ export const createAgentRPC = (wire, options) => {
         }),
     });
     return {
-        run: async (agentName, input) => asRunResult(await runAgent(agentName, input, params())),
+        run: async (agentName, input) => asRunResult(await runAgent(mapAddonCall(wire.addonNamespace, agentName), input, params())),
         stream: async (agentName, input, streamOptions) => {
             let currentRunId;
-            await streamAgent(agentName, input, wrapChannelWithAGUI(streamingChannel(), {
+            await streamAgent(mapAddonCall(wire.addonNamespace, agentName), input, wrapChannelWithAGUI(streamingChannel(), {
                 threadId: input.threadId,
                 getRunId: () => currentRunId,
             }), params(), undefined, {
@@ -49,7 +50,9 @@ export const createAgentRPC = (wire, options) => {
             await resumeAgent({ runId, ...input }, wrapChannelWithAGUI(streamingChannel(), { runId }), params(), streamOptions);
         },
         interrupt: async (runId, reason) => interruptAgent({ runId, ...(reason ? { reason } : {}) }, { sessionService: options.sessionService }),
-        approve: async (runId, approvals, expectedAgentName) => asRunResult(await resumeAgentSync(runId, approvals, { sessionService: options.sessionService }, expectedAgentName)),
+        approve: async (runId, approvals, expectedAgentName) => asRunResult(await resumeAgentSync(runId, approvals, { sessionService: options.sessionService }, expectedAgentName === undefined
+            ? undefined
+            : mapAddonCall(wire.addonNamespace, expectedAgentName))),
     };
 };
 /**

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/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

@@ -1,3 +1,4 @@
+import { AddonNotUsedError } from '../addon/addon-reach.js';
 import type { CoreServices, PikkuRawWire } from '../../types/core.types.js';
 import type { SessionService } from '../../services/user-session-service.js';
 import type { CoreUserSession } from '../../types/core.types.js';
@@ -11,20 +12,25 @@ 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);
 }
-export declare class AddonNotUsedError extends PikkuError {
-    constructor(caller: string, target: 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 { AddonNotUsedError };
 export declare const resolveNamespace: (namespacedFunction: string) => ResolvedFunction | null;
 export declare class ContextAwareRPCService {
     private services;
@@ -72,7 +78,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 +87,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`.
  *