@pikku/inspector 0.12.109 → 0.12.110

package/dist/add/add-functions.js

@@ -40,6 +40,7 @@ import { findPiiPaths } from '../utils/check-pii-output.js';
 import { findClassifiedSinks } from '../utils/check-classified-sinks.js';
 import { isScenarioInstrumentationFunction } from './scenario-instrumentation.js';
 import { resolveCalleeName } from '../utils/resolve-callee-name.js';
+import { addonZodContractViolation } from '../utils/validate-addon-zod-contract.js';
 const isValidVariableName = (name) => {
     const regex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
     return regex.test(name);
@@ -887,6 +888,19 @@ export const addFunctions = (logger, node, checker, state, options) => {
     if (inputNames.length > 1) {
         logger.warn('More than one input type detected, only the first one will be used as a schema.');
     }
+    if (options.isAddon && remote && !notRpc) {
+        const violation = addonZodContractViolation(state.functions.typesMap, {
+            name,
+            usesGenerics: (typeArguments?.length ?? 0) > 0,
+            hasInputSchema: !!inputSchemaRef,
+            hasOutputSchema: !!outputSchemaRef,
+            inputNames,
+            outputNames,
+        });
+        if (violation) {
+            logger.critical(ErrorCode.ADDON_REMOTE_CONTRACT_NOT_ZOD, violation);
+        }
+    }
     // Store the input type for later use
     if (inputTypes.length > 0) {
         state.typesLookup.set(pikkuFuncId, inputTypes);

package/dist/add/add-rpc-invocations.d.ts

@@ -2,7 +2,7 @@ import * as ts from 'typescript';
 import type { InspectorState, InspectorLogger } from '../types.js';
 /**
  * The RPC names a function handler calls through `rpc.invoke(...)` /
- * `rpc.remote(...)`, read from its own body.
+ * `rpc.mesh(...)`, read from its own body.
  *
  * This is what the deploy planner uses to bind a unit to the units its
  * functions call: without it, a caller and callee split into different units

package/dist/add/add-rpc-invocations.js

@@ -44,7 +44,7 @@ function isRpcReceiver(node) {
  * is not bundled in the caller's deploy unit, cross to another unit through the
  * `DeploymentService`.
  */
-const CROSS_UNIT_RPC_METHODS = new Set(['invoke', 'remote']);
+const CROSS_UNIT_RPC_METHODS = new Set(['invoke', 'mesh']);
 /** The name argument when it is statically known: `'x'`, `"x"` or `` `x` ``. */
 function literalRpcName(arg) {
     if (ts.isStringLiteral(arg) || ts.isNoSubstitutionTemplateLiteral(arg)) {
@@ -54,7 +54,7 @@ function literalRpcName(arg) {
 }
 /**
  * The RPC names a function handler calls through `rpc.invoke(...)` /
- * `rpc.remote(...)`, read from its own body.
+ * `rpc.mesh(...)`, read from its own body.
  *
  * This is what the deploy planner uses to bind a unit to the units its
  * functions call: without it, a caller and callee split into different units

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

@@ -1,4 +1,6 @@
 import * as ts from 'typescript';
+import { ErrorCode } from '../error-codes.js';
+import { parseRemoteAddonPackage } from '../utils/remote-addon-sdk.js';
 /**
  * Detect wireRemoteAddon({ name: '...', package: '...' }) call expressions and
  * record the namespace as a **remote** addon declaration. Only name + package
@@ -17,6 +19,7 @@ export function addWireRemoteAddon(node, state, logger) {
         return;
     let name;
     let pkg;
+    let pkgNode;
     // The auth binding is a runtime closure; we only extract the statically
     // knowable slot names so `pikku verify` can check they exist in the
     // consumer's own wirings. `hasAuth` distinguishes "public" (omitted) from
@@ -31,8 +34,11 @@ export function addWireRemoteAddon(node, state, logger) {
         if (key === 'name' && ts.isStringLiteral(prop.initializer)) {
             name = prop.initializer.text;
         }
-        else if (key === 'package' && ts.isStringLiteral(prop.initializer)) {
-            pkg = prop.initializer.text;
+        else if (key === 'package') {
+            pkgNode = prop.initializer;
+            if (ts.isStringLiteralLike(prop.initializer)) {
+                pkg = prop.initializer.text;
+            }
         }
         else if (key === 'auth' &&
             ts.isObjectLiteralExpression(prop.initializer)) {
@@ -52,11 +58,26 @@ export function addWireRemoteAddon(node, state, logger) {
             }
         }
     }
+    if (pkgNode && pkg === undefined) {
+        logger.critical(ErrorCode.REMOTE_ADDON_PACKAGE_NOT_STATIC, `wireRemoteAddon(${name ? `'${name}'` : '…'}) in ${node.getSourceFile().fileName} sets package to '${pkgNode.getText()}', which is not a string literal. Write the package (and its version range) inline, e.g. package: '@scope/addon@^1.0.0', so it can be read without running the file.`);
+        return;
+    }
     if (!name || !pkg)
         return;
-    logger.debug(`• Found wireRemoteAddon: ${name} → ${pkg} (remote)`);
+    let packageName;
+    let range;
+    try {
+        ;
+        ({ name: packageName, range } = parseRemoteAddonPackage(pkg));
+    }
+    catch (e) {
+        logger.critical(ErrorCode.REMOTE_ADDON_PACKAGE_INVALID, `wireRemoteAddon('${name}'): ${e instanceof Error ? e.message : e}`);
+        return;
+    }
+    logger.debug(`• Found wireRemoteAddon: ${name} → ${packageName}${range ? `@${range}` : ''} (remote)`);
     state.rpc.wireAddonDeclarations.set(name, {
-        package: pkg,
+        package: packageName,
+        ...(range ? { range } : {}),
         file: node.getSourceFile().fileName,
         remote: true,
         hasAuth,

package/dist/error-codes.d.ts

@@ -42,6 +42,10 @@ export declare enum ErrorCode {
     ADDON_USES_NOT_WIRED = "PKU347",
     ADDON_NEEDS_NOT_MAPPED = "PKU348",
     ADDON_CONTENT_GRANT_INVALID = "PKU349",
+    REMOTE_ADDON_PACKAGE_NOT_STATIC = "PKU350",
+    REMOTE_ADDON_SDK_CORE_MISMATCH = "PKU351",
+    REMOTE_ADDON_SDK_INTEGRITY_MISMATCH = "PKU352",
+    REMOTE_ADDON_PACKAGE_INVALID = "PKU353",
     DB_COLUMN_NAME_TYPE_CONTRADICTION = "PKU480",
     DB_JSON_COLUMN_UNTYPED = "PKU481",
     DB_FORMAT_ON_NON_STRING = "PKU482",
@@ -89,6 +93,7 @@ export declare enum ErrorCode {
     PII_IN_OUTPUT = "PKU910",
     ADDON_WIRING_NOT_ALLOWED = "PKU920",
     ADDON_CONTRACT_HANDLERS_NOT_ALLOWED = "PKU921",
+    ADDON_REMOTE_CONTRACT_NOT_ZOD = "PKU922",
     RPC_INVOCATION_TYPE_CAST = "PKU940",
     KNOWLEDGE_NOTE_MISSING = "PKU960",
     SECRET_SERVICE_ALIASED = "PKU950",

package/dist/error-codes.js

@@ -45,6 +45,10 @@ export var ErrorCode;
     ErrorCode["ADDON_USES_NOT_WIRED"] = "PKU347";
     ErrorCode["ADDON_NEEDS_NOT_MAPPED"] = "PKU348";
     ErrorCode["ADDON_CONTENT_GRANT_INVALID"] = "PKU349";
+    ErrorCode["REMOTE_ADDON_PACKAGE_NOT_STATIC"] = "PKU350";
+    ErrorCode["REMOTE_ADDON_SDK_CORE_MISMATCH"] = "PKU351";
+    ErrorCode["REMOTE_ADDON_SDK_INTEGRITY_MISMATCH"] = "PKU352";
+    ErrorCode["REMOTE_ADDON_PACKAGE_INVALID"] = "PKU353";
     // Database schema codegen warnings
     ErrorCode["DB_COLUMN_NAME_TYPE_CONTRADICTION"] = "PKU480";
     ErrorCode["DB_JSON_COLUMN_UNTYPED"] = "PKU481";
@@ -114,6 +118,7 @@ export var ErrorCode;
     // Addon authoring errors
     ErrorCode["ADDON_WIRING_NOT_ALLOWED"] = "PKU920";
     ErrorCode["ADDON_CONTRACT_HANDLERS_NOT_ALLOWED"] = "PKU921";
+    ErrorCode["ADDON_REMOTE_CONTRACT_NOT_ZOD"] = "PKU922";
     ErrorCode["RPC_INVOCATION_TYPE_CAST"] = "PKU940";
     // Knowledge base errors
     ErrorCode["KNOWLEDGE_NOTE_MISSING"] = "PKU960";

package/dist/finalize.js

@@ -77,7 +77,9 @@ export const finalizeInspectorState = async (logger, analyzed, options = {}) =>
         annotateHttpRouteAuth(state);
         // Last of the validators: they read function meta and every wireAddon
         // declaration together, so they need the whole program inspected.
-        validateExposedFunctionsGated(logger, state);
+        validateExposedFunctionsGated(logger, state, {
+            isAddon: options.isAddon === true,
+        });
         validateTagsResolveToMiddleware(logger, state);
         if (options.openAPI) {
             state.openAPISpec = await generateOpenAPISpec(logger, state.functions.meta, state.http.meta, state.schemas, options.openAPI.additionalInfo, pikkuState(null, 'misc', 'errors'));

package/dist/index.d.ts

@@ -30,3 +30,7 @@ export { readModuleSpecifiers } from './utils/read-module-specifiers.js';
 export { readJsxLiteralText } from './utils/read-jsx-literal-text.js';
 export { readTsconfigOutDir } from './utils/read-tsconfig-out-dir.js';
 export { addonResolutionDirs, createAddonResolver, } from './utils/addon-resolution.js';
+export { ADDONS_LOCK_FILE, REMOTE_SDK_DIR, SDK_INTEGRITY_MARKER, parseRemoteAddonPackage, emptyAddonsLock, readAddonsLock, serializeAddonsLock, remoteSdkDir, readSdkManifest, checkLockedSdk, } from './utils/remote-addon-sdk.js';
+export { findWireRemoteAddonSpecs } from './utils/find-wire-remote-addon-specs.js';
+export type { AddonsLock, AddonsLockEntry, RemoteAddonSdkManifest, RemoteAddonPackageSpec, LockedSdk, } from './utils/remote-addon-sdk.js';
+export type { WireRemoteAddonSpec } from './utils/find-wire-remote-addon-specs.js';

package/dist/index.js

@@ -18,3 +18,5 @@ export { readModuleSpecifiers } from './utils/read-module-specifiers.js';
 export { readJsxLiteralText } from './utils/read-jsx-literal-text.js';
 export { readTsconfigOutDir } from './utils/read-tsconfig-out-dir.js';
 export { addonResolutionDirs, createAddonResolver, } from './utils/addon-resolution.js';
+export { ADDONS_LOCK_FILE, REMOTE_SDK_DIR, SDK_INTEGRITY_MARKER, parseRemoteAddonPackage, emptyAddonsLock, readAddonsLock, serializeAddonsLock, remoteSdkDir, readSdkManifest, checkLockedSdk, } from './utils/remote-addon-sdk.js';
+export { findWireRemoteAddonSpecs } from './utils/find-wire-remote-addon-specs.js';

package/dist/lite.d.ts

@@ -9,6 +9,7 @@
  * reachable from this file imports `typescript`.
  */
 export { getInitialInspectorState } from './initial-state.js';
+export { TypesMap } from './types-map.js';
 export { ErrorCode } from './error-codes.js';
 export type { DiagnosticSeverity, CodedDiagnostic } from './error-codes.js';
 export { AUTH_HANDLER_FUNC_ID } from './utils/inspector-constants.js';
@@ -18,9 +19,11 @@ export { filterInspectorState } from './utils/filter-inspector-state.js';
 export { incompatibleServicesFor, resolveDeployTarget, } from './utils/resolve-deploy-target.js';
 export { customTypeNames, generateCustomTypes, sanitizeTypeName, } from './utils/custom-types-generator.js';
 export { unresolvedSchemaReferences } from './utils/post-process.js';
-export { createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
+export { computeContractHash, createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
 export { serializeMCPJson } from './utils/serialize-mcp-json.js';
 export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/deserialize-dsl-workflow.js';
 export { resolveFunctionMeta } from './utils/resolve-function-meta.js';
 export { resolveCoreType } from './utils/resolve-core-type.js';
 export { addonResolutionDirs, createAddonResolver, } from './utils/addon-resolution.js';
+export { ADDONS_LOCK_FILE, REMOTE_SDK_DIR, SDK_INTEGRITY_MARKER, checkLockedSdk, emptyAddonsLock, parseRemoteAddonPackage, readAddonsLock, readSdkManifest, remoteSdkDir, serializeAddonsLock, } from './utils/remote-addon-sdk.js';
+export type { AddonsLock, AddonsLockEntry, RemoteAddonSdkManifest, RemoteAddonPackageSpec, LockedSdk, } from './utils/remote-addon-sdk.js';

package/dist/lite.js

@@ -9,6 +9,7 @@
  * reachable from this file imports `typescript`.
  */
 export { getInitialInspectorState } from './initial-state.js';
+export { TypesMap } from './types-map.js';
 export { ErrorCode } from './error-codes.js';
 export { AUTH_HANDLER_FUNC_ID } from './utils/inspector-constants.js';
 export { SCENARIO_INSTRUMENTATION_FUNCTIONS, isScenarioInstrumentationFunction, } from './add/scenario-instrumentation.js';
@@ -17,9 +18,10 @@ export { filterInspectorState } from './utils/filter-inspector-state.js';
 export { incompatibleServicesFor, resolveDeployTarget, } from './utils/resolve-deploy-target.js';
 export { customTypeNames, generateCustomTypes, sanitizeTypeName, } from './utils/custom-types-generator.js';
 export { unresolvedSchemaReferences } from './utils/post-process.js';
-export { createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
+export { computeContractHash, createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
 export { serializeMCPJson } from './utils/serialize-mcp-json.js';
 export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/deserialize-dsl-workflow.js';
 export { resolveFunctionMeta } from './utils/resolve-function-meta.js';
 export { resolveCoreType } from './utils/resolve-core-type.js';
 export { addonResolutionDirs, createAddonResolver, } from './utils/addon-resolution.js';
+export { ADDONS_LOCK_FILE, REMOTE_SDK_DIR, SDK_INTEGRITY_MARKER, checkLockedSdk, emptyAddonsLock, parseRemoteAddonPackage, readAddonsLock, readSdkManifest, remoteSdkDir, serializeAddonsLock, } from './utils/remote-addon-sdk.js';

package/dist/types.d.ts

@@ -23,6 +23,14 @@ import type { VirtualUserDefinitions } from '@pikku/core/virtual-user';
 import type { VariableDefinitions } from '@pikku/core/variable';
 import type { TypesMap } from './types-map.js';
 import type { FunctionsMeta } from '@pikku/core/services';
+/**
+ * A remote addon SDK's function meta: each contract function, with the
+ * versions of its name the SDK can call and the one a call without `@vN` goes to.
+ */
+export type RemoteAddonFunctionsMeta = Record<string, FunctionsMeta[string] & {
+    versions?: number[];
+    latestVersion?: number;
+}>;
 import type { FunctionServicesMeta, FunctionWiresMeta } from '@pikku/core/function';
 import type { JSONValue } from '@pikku/core/utils';
 import type { OpenAPISpecInfo } from './utils/serialize-openapi-json.js';
@@ -713,6 +721,12 @@ export interface InspectorState {
             scopes?: string[];
             /** True when declared via `wireRemoteAddon` — import the addon's `.remote.gen` map, not `.internal.gen` */
             remote?: boolean;
+            /**
+             * wireRemoteAddon: the semver range written after the package name
+             * (`@scope/name@^1.4.0`). Present means the contract comes from the
+             * SDK `pikku all` downloads, not from an installed package.
+             */
+            range?: string;
             /** wireRemoteAddon: whether an `auth` binding was supplied (vs a public surface) */
             hasAuth?: boolean;
             /** wireRemoteAddon: statically-known `auth.credentialId`, for verify */
@@ -878,6 +892,8 @@ export interface InspectorState {
     openAPISpec: Record<string, any> | null;
     diagnostics: InspectorDiagnostic[];
     addonFunctions: Record<string, FunctionsMeta>;
+    /** The function metadata of each versioned `wireRemoteAddon`'s SDK, by namespace. Kept apart from `addonFunctions`: none of it runs here. */
+    remoteAddonFunctions?: Record<string, RemoteAddonFunctionsMeta>;
     exportedContracts: InspectorExportedContractsState;
     program: ts.Program | null;
 }

package/dist/utils/contract-hashes.js

@@ -73,7 +73,7 @@ export function buildCurrentContracts(functionsMeta, allSchemas, typesMap) {
     for (const [funcId, meta] of Object.entries(functionsMeta)) {
         // A webhook receive has no callers but its own route, so there is no
         // contract for a version to protect.
-        if (meta.remote === true || meta.webhookReceive) {
+        if (meta.webhookReceive) {
             continue;
         }
         const parsed = parseVersionedId(funcId);
@@ -253,7 +253,7 @@ export function updateManifest(existing, currentContracts) {
 export function extractContractsFromMeta(functionsMeta) {
     const result = new Map();
     for (const [funcId, meta] of Object.entries(functionsMeta)) {
-        if (meta.remote === true || meta.webhookReceive || !meta.contractHash) {
+        if (meta.webhookReceive || !meta.contractHash) {
             continue;
         }
         const parsed = parseVersionedId(funcId);

package/dist/utils/find-wire-remote-addon-specs.d.ts

@@ -0,0 +1,17 @@
+/** A `wireRemoteAddon({ package })` found in source, with the line its literal sits on. */
+export type WireRemoteAddonSpec = {
+    /** The `name` option, when it is a literal. */
+    namespace?: string;
+    /** The literal as written, e.g. `@scope/name@^1.4.0`. */
+    spec: string;
+    name: string;
+    range?: string;
+    /** 1-based line of the literal. */
+    line: number;
+};
+/**
+ * Every `wireRemoteAddon({ package: '<literal>' })` in one file. A `package`
+ * that is not a literal, or that does not parse, is skipped: the inspection
+ * reports those.
+ */
+export declare const findWireRemoteAddonSpecs: (fileName: string, sourceText: string) => WireRemoteAddonSpec[];

package/dist/utils/find-wire-remote-addon-specs.js

@@ -0,0 +1,53 @@
+import * as ts from 'typescript';
+import { parseRemoteAddonPackage } from './remote-addon-sdk.js';
+/**
+ * Every `wireRemoteAddon({ package: '<literal>' })` in one file. A `package`
+ * that is not a literal, or that does not parse, is skipped: the inspection
+ * reports those.
+ */
+export const findWireRemoteAddonSpecs = (fileName, sourceText) => {
+    if (!sourceText.includes('wireRemoteAddon'))
+        return [];
+    const sourceFile = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, true);
+    const found = [];
+    const visit = (node) => {
+        if (ts.isCallExpression(node) &&
+            ts.isIdentifier(node.expression) &&
+            node.expression.text === 'wireRemoteAddon' &&
+            node.arguments[0] &&
+            ts.isObjectLiteralExpression(node.arguments[0])) {
+            let namespace;
+            let literal;
+            for (const prop of node.arguments[0].properties) {
+                if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name))
+                    continue;
+                if (prop.name.text === 'name' &&
+                    ts.isStringLiteralLike(prop.initializer)) {
+                    namespace = prop.initializer.text;
+                }
+                else if (prop.name.text === 'package' &&
+                    ts.isStringLiteralLike(prop.initializer)) {
+                    literal = prop.initializer;
+                }
+            }
+            if (literal) {
+                try {
+                    const { name, range } = parseRemoteAddonPackage(literal.text);
+                    found.push({
+                        namespace,
+                        spec: literal.text,
+                        name,
+                        range,
+                        line: sourceFile.getLineAndCharacterOfPosition(literal.getStart(sourceFile)).line + 1,
+                    });
+                }
+                catch {
+                    // reported by the inspection
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return found;
+};

package/dist/utils/load-addon-functions-meta.js

@@ -3,6 +3,7 @@ import { readFile, readdir } from 'fs/promises';
 import { join, dirname, parse, relative } from 'path';
 import { addonResolutionDirs, createAddonResolver, } from './addon-resolution.js';
 import { ErrorCode } from '../error-codes.js';
+import { checkLockedSdk } from './remote-addon-sdk.js';
 const isHTTPRouteConfig = (value) => typeof value === 'object' &&
     value !== null &&
     'method' in value &&
@@ -239,6 +240,26 @@ export const readAddonContributors = async (dirs, packageName) => {
         contributors: declared.map(({ module, export: name }) => name === undefined ? { module } : { module, export: name }),
     };
 };
+/**
+ * A versioned remote addon's function metadata comes from the SDK `pikku addon
+ * sync` extracted, and only when it matches the lock — a stale or missing SDK
+ * is reported by `validateRemoteAddonDependencies`, not loaded half-way.
+ */
+const loadRemoteAddonSdkMeta = async (state, namespace, packageName, range) => {
+    let locked;
+    try {
+        locked = checkLockedSdk(state.rootDir, packageName, range);
+    }
+    catch {
+        return;
+    }
+    if (!locked.ok)
+        return;
+    const metaPath = join(locked.dir, 'function', 'pikku-functions-meta.gen.json');
+    if (!existsSync(metaPath))
+        return;
+    (state.remoteAddonFunctions ??= {})[namespace] = JSON.parse(await readFile(metaPath, 'utf-8'));
+};
 export async function loadAddonFunctionsMeta(logger, state) {
     const { wireAddonDeclarations } = state.rpc;
     if (wireAddonDeclarations.size === 0)
@@ -247,8 +268,12 @@ export async function loadAddonFunctionsMeta(logger, state) {
         // Remote addons (wireRemoteAddon) ship as a devDependency: types only.
         // Their functions, secrets, variables, schemas and services live on the
         // HOST that runs them — never load or require any of that here.
-        if (decl.remote)
+        if (decl.remote) {
+            if (decl.range) {
+                await loadRemoteAddonSdkMeta(state, namespace, decl.package, decl.range);
+            }
             continue;
+        }
         const dirs = addonResolutionDirs(state.rootDir, decl.file);
         const require = createAddonResolver(dirs);
         try {
@@ -347,13 +372,17 @@ export async function loadAddonFunctionsMeta(logger, state) {
                     }
                 }
             }
-            // Same reasoning as mcp: a listed name the addon does not publish is a
-            // function the app believes callable and never is.
+            // Same reasoning as mcp: a listed name the addon does not publish, or
+            // does not declare `expose: true`, is a function the app believes
+            // callable and never is.
             if (Array.isArray(decl.expose)) {
                 for (const funcName of decl.expose) {
                     if (!Object.hasOwn(meta, funcName)) {
                         logger.critical(ErrorCode.ADDON_EXPOSE_FUNCTION_NOT_FOUND, `wireAddon('${namespace}') lists '${funcName}' under expose, but ${decl.package} publishes no such function.`);
                     }
+                    else if (meta[funcName]?.expose !== true) {
+                        logger.critical(ErrorCode.ADDON_EXPOSE_FUNCTION_NOT_FOUND, `wireAddon('${namespace}') lists '${funcName}' under expose, but ${decl.package} does not declare it expose: true, so it stays unexposed.`);
+                    }
                 }
             }
             // Load addon secrets meta

package/dist/utils/post-process.js

@@ -7,6 +7,7 @@ import { relative } from 'node:path';
 import { AUTH_HANDLER_FUNC_ID, DYNAMIC_SCENARIO_STEP_TARGET, } from './inspector-constants.js';
 import { flattenScopeDefinitions } from '@pikku/core/scope';
 import { addonResolutionDirs } from './addon-resolution.js';
+import { ADDONS_LOCK_FILE, checkLockedSdk, readAddonsLock, } from './remote-addon-sdk.js';
 /**
  * Stamp the inspected authorize/callbacks service set onto the generated auth
  * handler's function meta.
@@ -607,8 +608,33 @@ export function validateRemoteAddonDependencies(logger, state) {
         manifests.set(path, manifest);
         return manifest;
     };
+    // A versioned remote addon's contract is the SDK `pikku all`
+    // downloaded, so what has to hold is that the SDK on disk is the one the
+    // lock pins, not that a package is installed.
+    let lock;
     for (const [namespace, decl] of wireAddonDeclarations.entries()) {
-        if (!decl.remote)
+        if (!decl.remote || !decl.range)
+            continue;
+        if (lock === undefined) {
+            try {
+                lock = readAddonsLock(state.rootDir);
+            }
+            catch (e) {
+                lock = e instanceof Error ? e : new Error(String(e));
+            }
+        }
+        const reason = lock instanceof Error
+            ? lock.message
+            : (() => {
+                const locked = checkLockedSdk(state.rootDir, decl.package, decl.range, lock);
+                return locked.ok ? null : locked.reason;
+            })();
+        if (reason === null)
+            continue;
+        logger.critical(ErrorCode.REMOTE_ADDON_NOT_DEV_DEPENDENCY, `Remote addon '${namespace}' ('${decl.package}@${decl.range}') has no SDK matching ${ADDONS_LOCK_FILE}: ${reason}. Run 'pikku all' to download it.`);
+    }
+    for (const [namespace, decl] of wireAddonDeclarations.entries()) {
+        if (!decl.remote || decl.range)
             continue;
         const pkgJsonPath = join(addonResolutionDirs(state.rootDir, decl.file)[0], 'package.json');
         const pkgJson = readManifest(pkgJsonPath);

package/dist/utils/remote-addon-sdk.d.ts

@@ -0,0 +1,57 @@
+/** Committed beside pikku.config.json: the SDK version and integrity each versioned `wireRemoteAddon` resolved to. */
+export declare const ADDONS_LOCK_FILE = "pikku-addons.lock";
+/** Where `pikku all` extracts SDKs, relative to the project root. Gitignored with the rest of `.pikku`. */
+export declare const REMOTE_SDK_DIR: string;
+/** Written into an extracted SDK: the integrity of the tarball it came from. */
+export declare const SDK_INTEGRITY_MARKER = ".integrity";
+export type AddonsLockEntry = {
+    /** The range the spec asked for when this entry was written. */
+    range: string;
+    version: string;
+    /** `sha512-<base64>` of the SDK tarball. */
+    integrity: string;
+};
+export type AddonsLock = {
+    lockfileVersion: 1;
+    sdks: Record<string, AddonsLockEntry>;
+};
+/** `manifest.json` at the root of an SDK. */
+export type RemoteAddonSdkManifest = {
+    name: string;
+    version: string;
+    /** The @pikku/core range the SDK's types were generated against. */
+    pikkuCore?: string;
+    contractHash?: string;
+};
+export type RemoteAddonPackageSpec = {
+    name: string;
+    range?: string;
+};
+/**
+ * `@scope/name@^1.4.0` → name and range, split at the last `@` after the first
+ * character. Mirrors `parseRemoteAddonPackage` in @pikku/core, which the
+ * runtime uses on the same literal.
+ */
+export declare const parseRemoteAddonPackage: (spec: string) => RemoteAddonPackageSpec;
+export declare const emptyAddonsLock: () => AddonsLock;
+/** The project's lock, an empty one when there is none. Throws when the file is not a lock. */
+export declare const readAddonsLock: (rootDir: string) => AddonsLock;
+/** Sorted by package name, each entry's keys in a fixed order, so the same lock always writes the same bytes. */
+export declare const serializeAddonsLock: (lock: AddonsLock) => string;
+export declare const remoteSdkDir: (rootDir: string, name: string, version: string) => string;
+export declare const readSdkManifest: (dir: string) => RemoteAddonSdkManifest | null;
+export type LockedSdk = {
+    ok: true;
+    entry: AddonsLockEntry;
+    dir: string;
+    manifest: RemoteAddonSdkManifest;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Whether the SDK for `name@range` is on disk exactly as the lock pins it: the
+ * lock was written for this range, the extracted directory carries the lock's
+ * integrity, and its manifest names this package and version.
+ */
+export declare const checkLockedSdk: (rootDir: string, name: string, range: string, lock?: AddonsLock) => LockedSdk;

package/dist/utils/remote-addon-sdk.js

@@ -0,0 +1,111 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+/** Committed beside pikku.config.json: the SDK version and integrity each versioned `wireRemoteAddon` resolved to. */
+export const ADDONS_LOCK_FILE = 'pikku-addons.lock';
+/** Where `pikku all` extracts SDKs, relative to the project root. Gitignored with the rest of `.pikku`. */
+export const REMOTE_SDK_DIR = join('.pikku', 'remote');
+/** Written into an extracted SDK: the integrity of the tarball it came from. */
+export const SDK_INTEGRITY_MARKER = '.integrity';
+/**
+ * `@scope/name@^1.4.0` → name and range, split at the last `@` after the first
+ * character. Mirrors `parseRemoteAddonPackage` in @pikku/core, which the
+ * runtime uses on the same literal.
+ */
+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 };
+};
+export const emptyAddonsLock = () => ({
+    lockfileVersion: 1,
+    sdks: {},
+});
+/** The project's lock, an empty one when there is none. Throws when the file is not a lock. */
+export const readAddonsLock = (rootDir) => {
+    const path = join(rootDir, ADDONS_LOCK_FILE);
+    if (!existsSync(path))
+        return emptyAddonsLock();
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch (e) {
+        throw new Error(`${path} is not valid JSON: ${e?.message ?? e}`);
+    }
+    if (!parsed ||
+        typeof parsed !== 'object' ||
+        typeof parsed.sdks !== 'object') {
+        throw new Error(`${path} has no "sdks" object`);
+    }
+    return { lockfileVersion: 1, sdks: parsed.sdks ?? {} };
+};
+/** Sorted by package name, each entry's keys in a fixed order, so the same lock always writes the same bytes. */
+export const serializeAddonsLock = (lock) => {
+    const sdks = {};
+    for (const name of Object.keys(lock.sdks).sort()) {
+        const { range, version, integrity } = lock.sdks[name];
+        sdks[name] = { range, version, integrity };
+    }
+    return `${JSON.stringify({ lockfileVersion: 1, sdks }, null, 2)}\n`;
+};
+export const remoteSdkDir = (rootDir, name, version) => join(rootDir, REMOTE_SDK_DIR, `${name}@${version}`);
+export const readSdkManifest = (dir) => {
+    try {
+        return JSON.parse(readFileSync(join(dir, 'manifest.json'), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Whether the SDK for `name@range` is on disk exactly as the lock pins it: the
+ * lock was written for this range, the extracted directory carries the lock's
+ * integrity, and its manifest names this package and version.
+ */
+export const checkLockedSdk = (rootDir, name, range, lock = readAddonsLock(rootDir)) => {
+    const entry = lock.sdks[name];
+    if (!entry) {
+        return { ok: false, reason: `${ADDONS_LOCK_FILE} has no entry for it` };
+    }
+    if (entry.range !== range) {
+        return {
+            ok: false,
+            reason: `${ADDONS_LOCK_FILE} was resolved for '${entry.range}', not '${range}'`,
+        };
+    }
+    const dir = remoteSdkDir(rootDir, name, entry.version);
+    let integrity = null;
+    try {
+        integrity = readFileSync(join(dir, SDK_INTEGRITY_MARKER), 'utf-8').trim();
+    }
+    catch {
+        return { ok: false, reason: `${dir} is missing` };
+    }
+    if (integrity !== entry.integrity) {
+        return {
+            ok: false,
+            reason: `${dir} was extracted from a different tarball than ${ADDONS_LOCK_FILE} pins`,
+        };
+    }
+    const manifest = readSdkManifest(dir);
+    if (!manifest ||
+        manifest.name !== name ||
+        manifest.version !== entry.version) {
+        return {
+            ok: false,
+            reason: `${dir}/manifest.json does not name ${name}@${entry.version}`,
+        };
+    }
+    return { ok: true, entry, dir, manifest };
+};

package/dist/utils/resolve-addon-package.d.ts

@@ -1,5 +1,6 @@
 import type { CredentialOverrideMeta } from '../types.js';
 import * as ts from 'typescript';
+export declare const findPackageNameForFile: (filePath: string) => string | null;
 /**
  * Resolve the addon package name from an imported identifier.
  * Checks if the identifier's import module specifier matches any

package/dist/utils/resolve-addon-package.js

@@ -2,7 +2,7 @@ import * as ts from 'typescript';
 import { existsSync, readFileSync } from 'fs';
 import { dirname, join, parse } from 'path';
 const packageNameCache = new Map();
-const findPackageNameForFile = (filePath) => {
+export const findPackageNameForFile = (filePath) => {
     if (packageNameCache.has(filePath)) {
         return packageNameCache.get(filePath);
     }

package/dist/utils/resolve-versions.js

@@ -90,6 +90,24 @@ export function resolveLatestVersions(state, logger) {
                 }
             }
         }
+        // A remote caller names a version the same way: `fn` is the latest remote
+        // version, and every remote `fn@vN` stays callable by its own id.
+        const remote = [
+            ...group.explicit,
+            ...(group.unversioned
+                ? [{ id: state.rpc.internalMeta[baseName], version: maxVersion + 1 }]
+                : []),
+        ].filter(({ id }) => functionsMeta[id]?.remote === true);
+        if (remote.length > 0) {
+            state.rpc.remoteMeta[baseName] = remote.reduce((a, b) => a.version > b.version ? a : b).id;
+            for (const { id } of remote) {
+                state.rpc.remoteMeta[id] = id;
+                const fileEntry = state.rpc.internalFiles.get(id);
+                if (fileEntry) {
+                    state.rpc.remoteFiles.set(id, fileEntry);
+                }
+            }
+        }
         for (const entry of group.explicit) {
             state.rpc.invokedFunctions.add(entry.id);
         }

package/dist/utils/serialize-inspector-state.d.ts

@@ -194,6 +194,7 @@ export interface SerializableInspectorState {
             string,
             {
                 package: string;
+                range?: string;
                 file?: string;
                 rpcEndpoint?: string;
                 remote?: boolean;
@@ -326,6 +327,7 @@ export interface SerializableInspectorState {
     openAPISpec: Record<string, any> | null;
     diagnostics: InspectorDiagnostic[];
     addonFunctions: InspectorState['addonFunctions'];
+    remoteAddonFunctions?: InspectorState['remoteAddonFunctions'];
     screensManifest?: InspectorState['screensManifest'];
     addonScreens?: InspectorState['addonScreens'];
     addonContributors?: InspectorState['addonContributors'];

package/dist/utils/serialize-inspector-state.js

@@ -190,6 +190,7 @@ export function serializeInspectorState(state) {
         openAPISpec: state.openAPISpec,
         diagnostics: state.diagnostics,
         addonFunctions: state.addonFunctions,
+        remoteAddonFunctions: state.remoteAddonFunctions,
         screensManifest: state.screensManifest,
         addonScreens: state.addonScreens,
         addonContributors: state.addonContributors,
@@ -396,6 +397,9 @@ export function deserializeInspectorState(data) {
         openAPISpec: data.openAPISpec || null,
         diagnostics: data.diagnostics || [],
         addonFunctions: data.addonFunctions || {},
+        ...(data.remoteAddonFunctions
+            ? { remoteAddonFunctions: data.remoteAddonFunctions }
+            : {}),
         screensManifest: data.screensManifest,
         addonScreens: data.addonScreens,
         addonContributors: data.addonContributors,

package/dist/utils/validate-addon-zod-contract.d.ts

@@ -0,0 +1,23 @@
+import type { TypesMap } from '../types-map.js';
+/**
+ * The named, source-declared types a function's input or output resolves to:
+ * every name the typed maps would have to import rather than declare inline.
+ * A custom alias (a union, an array of rows) is followed through to the names
+ * it references.
+ */
+export declare const namedSourceTypes: (typesMap: TypesMap, names: string[]) => string[];
+export interface AddonContractTypeSource {
+    name: string;
+    usesGenerics: boolean;
+    hasInputSchema: boolean;
+    hasOutputSchema: boolean;
+    inputNames: string[];
+    outputNames: string[];
+}
+/**
+ * Why a `remote: true` addon function cannot ship in an SDK, or null when it
+ * can. Its input and output have to be zod schemas: a TS generic or a named
+ * source type makes codegen emit `import type { X } from '../../../src/...'`
+ * into the remote map, a path that does not exist on the consumer's machine.
+ */
+export declare const addonZodContractViolation: (typesMap: TypesMap, fn: AddonContractTypeSource) => string | null;

package/dist/utils/validate-addon-zod-contract.js

@@ -0,0 +1,70 @@
+import { findPackageNameForFile } from './resolve-addon-package.js';
+/**
+ * A type declared in `@pikku/core` is part of the SDK's allowed import set, so
+ * naming one (an MCP response, say) does not drag the addon's source along.
+ * Core is recognised by its install path or by the name in the nearest
+ * package.json, never by a directory name an addon could also use.
+ */
+const isPikkuCorePath = (path) => /[\\/]node_modules[\\/]@pikku[\\/]core[\\/]/.test(path) ||
+    findPackageNameForFile(path) === '@pikku/core';
+/**
+ * The named, source-declared types a function's input or output resolves to:
+ * every name the typed maps would have to import rather than declare inline.
+ * A custom alias (a union, an array of rows) is followed through to the names
+ * it references.
+ */
+export const namedSourceTypes = (typesMap, names) => {
+    const found = new Set();
+    const visit = (name, seen) => {
+        if (seen.has(name))
+            return;
+        seen.add(name);
+        const custom = typesMap.customTypes.get(name);
+        if (custom) {
+            for (const ref of custom.references)
+                visit(ref, seen);
+            return;
+        }
+        let path = null;
+        let originalName = name;
+        try {
+            const meta = typesMap.getTypeMeta(name);
+            path = meta.path;
+            originalName = meta.originalName;
+        }
+        catch {
+            return;
+        }
+        if (path && !isPikkuCorePath(path))
+            found.add(originalName);
+    };
+    for (const name of names)
+        visit(name, new Set());
+    return [...found].sort();
+};
+/**
+ * Why a `remote: true` addon function cannot ship in an SDK, or null when it
+ * can. Its input and output have to be zod schemas: a TS generic or a named
+ * source type makes codegen emit `import type { X } from '../../../src/...'`
+ * into the remote map, a path that does not exist on the consumer's machine.
+ */
+export const addonZodContractViolation = (typesMap, fn) => {
+    const problems = [];
+    if (fn.usesGenerics) {
+        problems.push('declares its input/output with TypeScript generics');
+    }
+    const named = [
+        ...(fn.hasInputSchema ? [] : namedSourceTypes(typesMap, fn.inputNames)),
+        ...(fn.hasOutputSchema ? [] : namedSourceTypes(typesMap, fn.outputNames)),
+    ];
+    if (named.length > 0) {
+        problems.push(`types its input/output with named source types (${[...new Set(named)].join(', ')})`);
+    }
+    if (problems.length === 0)
+        return null;
+    return (`Addon function '${fn.name}' is remote: true but ${problems.join(' and ')}. ` +
+        `A remote addon's contract ships as a types-only SDK, so its input and output must be zod schemas: ` +
+        `export each schema as a zod variable from a file that does not import #pikku (a sibling <fn>.schemas.ts), ` +
+        `reference it as \`input:\` / \`output:\` on the function, and drop the generics. ` +
+        `TypeScript types would make the SDK import from the addon's src/, which the consumer does not have.`);
+};

package/dist/utils/validate-exposed-functions-gated.d.ts

@@ -11,4 +11,6 @@ import type { InspectorLogger, InspectorState } from '../types.js';
  *
  * knowledge: decisions/security/console-addon-privileged-functions-gate-themselves.md
  */
-export declare function validateExposedFunctionsGated(logger: InspectorLogger, state: InspectorState): void;
+export declare function validateExposedFunctionsGated(logger: InspectorLogger, state: InspectorState, { isAddon }?: {
+    isAddon?: boolean;
+}): void;

package/dist/utils/validate-exposed-functions-gated.js

@@ -11,9 +11,13 @@ import { ErrorCode } from '../error-codes.js';
  *
  * knowledge: decisions/security/console-addon-privileged-functions-gate-themselves.md
  */
-export function validateExposedFunctionsGated(logger, state) {
+export function validateExposedFunctionsGated(logger, state, { isAddon = false } = {}) {
     const ungated = [];
-    for (const [funcName, meta] of Object.entries(state.functions.meta)) {
+    // An addon's own `expose: true` only makes a function eligible: nothing is
+    // reachable until a host's `wireAddon` opts in, and that host is warned below.
+    for (const [funcName, meta] of isAddon
+        ? []
+        : Object.entries(state.functions.meta)) {
         if (!meta.expose)
             continue;
         if (gatesItself(meta))
@@ -22,23 +26,26 @@ export function validateExposedFunctionsGated(logger, state) {
             continue;
         ungated.push(funcName);
     }
-    // A `wireAddon` expose list can open an addon function its author never
-    // exposed, so the app that listed it is the one to tell. The namespaced call
-    // is governed by that instance's config alone.
+    // An addon function is exposed only when the app's `wireAddon` opts in, so
+    // the app that opted in is the one to tell. The namespaced call is governed
+    // by that instance's config alone.
     //
     // knowledge: decisions/security/wire-addon-expose-selects-the-rpc-surface.md
     for (const [namespace, declaration] of state.rpc?.wireAddonDeclarations ??
         []) {
-        if (!Array.isArray(declaration.expose))
+        if (!declaration.expose)
             continue;
         if (declaration.auth === true)
             continue;
         if (declaration.scopes && declaration.scopes.length > 0)
             continue;
         const addonMeta = state.addonFunctions?.[namespace] ?? {};
-        for (const funcName of declaration.expose) {
+        const selected = Array.isArray(declaration.expose)
+            ? declaration.expose
+            : Object.keys(addonMeta);
+        for (const funcName of selected) {
             const meta = addonMeta[funcName];
-            if (!meta || gatesItself(meta))
+            if (!meta?.expose || gatesItself(meta))
                 continue;
             ungated.push(`${namespace}:${funcName}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.109",
+  "version": "0.12.110",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -70,10 +70,10 @@
     "zod": "^4.6.7"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.145"
+    "@pikku/core": "^0.12.146"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.145",
+    "@pikku/core": "^0.12.146",
     "@types/node": "^26.6.5"
   },
   "engines": {