@peers-app/peers-sdk 0.23.10 → 0.23.11

package/dist/contracts/index.d.ts

@@ -1,8 +1,8 @@
 export { ContractBuilder, definePackage, PackageBuilder } from "./builder";
 export { type ContractCallAuthorizer, type ContractProviderEndpointResolver, type ContractProviderPackageResolver, createContractProviderRouter, type IAuthorizedContractRoute, type IContractProviderEndpointRequest, type IContractProviderRouter, type IContractProviderRouterOptions, } from "./contract-provider-router";
 export { ContractProviders, ContractProvidersTable, contractProvidersMetaData, contractProvidersSchema, type IContractProviderRecord, } from "./contract-providers.table";
-export { CONTRACT_CALL_RPC, type ContractMemberType, type ContractNotificationSink, type ContractPermissionCheck, createContractConsumer, createContractProvider, createContractProviderEndpoint, createContractProviderSession, type IContractCall, type IContractCallContext, type IContractConsumer, type IContractConsumerBase, type IContractNotification, type IContractProviderEndpoint, type IContractProviderEndpointOptions, type IContractProviderSession, type IContractProviderSessionOptions, type IContractResolution, type IContractTableProxy, type IContractToolContext, type ITableProxy, sameUserContractPermissionCheck, } from "./contract-proxy";
-export { type ContractRemoteIdentity, type ContractResolver, createLocalUserContextContractProviderRouter, createUserContextContractProviderRouter, getContractResolver, handleContractCall, type IContractResolverRegistrationOptions, type ILocalContractVariableRequest, isSelfTrustedContractCaller, type LocalContractVariableResolver, registerContractResolver, } from "./contract-resolvers";
+export { CONTRACT_CALL_RPC, type ContractMemberType, type ContractNotificationSink, type ContractPermissionCheck, createContractConsumer, createContractProvider, createContractProviderEndpoint, createContractProviderSession, createRemoteContractConsumer, type IContractCall, type IContractCallContext, type IContractConsumer, type IContractConsumerBase, type IContractNotification, type IContractProviderEndpoint, type IContractProviderEndpointOptions, type IContractProviderSession, type IContractProviderSessionOptions, type IContractResolution, type IContractTableProxy, type IContractToolContext, type ITableProxy, sameUserContractPermissionCheck, } from "./contract-proxy";
+export { authorizeRemoteContractCall, type ContractRemoteIdentity, type ContractResolver, createLocalUserContextContractProviderRouter, createUserContextContractProviderRouter, getContractResolver, handleContractCall, type IContractResolverRegistrationOptions, type ILocalContractVariableRequest, isSelfTrustedContractCaller, type LocalContractVariableResolver, registerContractResolver, verifyRemoteContractIdentity, } from "./contract-resolvers";
 export { CONTRACT_NOTIFY_CHANNEL, CONTRACT_REQUEST_CHANNEL, connectionContractTransport, type IContractTransport, type IDuplexEmitter, inProcessTransportPair, } from "./contract-transport";
 export { Contracts, ContractsTable, contractsMetaData, contractsSchema, type IContractRecord, } from "./contracts.table";
 export { createLocalContractConsumer } from "./create-local-consumer";
@@ -10,11 +10,12 @@ export { extractTableShape, extractToolShape, type IExtractableTableDef, type IE
 export { getHostContractTransport, type HostContractTransportListener, registerHostContractTransport, subscribeHostContractTransport, waitForHostContractTransport, } from "./host-contract-transport";
 export { PersistentContractRegistry } from "./persistent-registry";
 export { ContractRegistry, type IContractProviderRegistration } from "./registry";
+export { createRemoteContractEndpoint, getRemoteContractTransportFactory, type IRemoteContractHost, type IRemoteContractTarget, type RemoteContractTransportFactory, resolveRemoteTargetEndpoint, setRemoteContractTransportFactory, } from "./remote-contract-transport";
 export { DEVICE_OPERATIONS_CONTRACT_VERSION, DEVICE_OPERATIONS_MAX_QUERY_LENGTH, DEVICE_OPERATIONS_MAX_RESULT_BYTES, DEVICE_OPERATIONS_MAX_ROWS, DEVICE_OPERATIONS_MAX_TOOLS, type DeviceOperationCapability, deviceOperationsProviderPackageId, deviceOperationsToolIds, getDeviceOperationsContractDefinition, type IDeviceDatabaseQueryInput, type IDeviceDatabaseQueryResult, type IDeviceOperationStatus, type IDeviceToolListInput, type IDeviceToolLookupInput, type IDeviceToolLookupResult, type IDeviceToolRunInput, } from "./system/device-operations-contract";
 export { getLogsContractDefinition, type ILogsConsumer, LOGS_CONTRACT_VERSION, resolveLogsContract, } from "./system/logs-contract";
 export * from "./system/network-contracts";
 export { getToolAccessControlContractDefinition, type IToolAccessControlConsumer, TOOL_ACCESS_CONTROL_CONTRACT_VERSION, } from "./system/tool-access-control-contract";
 export { type ISystemContractRegistration, installSystemContracts, listSystemContracts, registerSystemContract, } from "./system-contracts";
-export type { IAlsoImplementsDeclaration, IConsumedContract, IConsumedContractHandle, IConsumedContractOptions, IContractDefinition, IContractEvent, IContractObservable, IContractTable, IContractTool, IPackageDefinitionResult, IResolvedContract, IValidationError, IValidationResult, } from "./types";
+export type { IAlsoImplementsDeclaration, IConsumedContract, IConsumedContractHandle, IConsumedContractOptions, IContractDefinition, IContractEvent, IContractObservable, IContractTable, IContractTool, IPackageDefinitionResult, IRemoteContract, IRemoteContractConsumer, IRemoteContractHandle, IResolvedContract, IValidationError, IValidationResult, } from "./types";
 export { contractKey } from "./types";
 export { validateAlsoImplements, validateImmutability, validateProviderSatisfiesContract, } from "./validate";

package/dist/contracts/index.js

@@ -14,8 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getToolAccessControlContractDefinition = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = exports.DEVICE_OPERATIONS_MAX_TOOLS = exports.DEVICE_OPERATIONS_MAX_ROWS = exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = exports.DEVICE_OPERATIONS_CONTRACT_VERSION = exports.ContractRegistry = exports.PersistentContractRegistry = exports.waitForHostContractTransport = exports.subscribeHostContractTransport = exports.registerHostContractTransport = exports.getHostContractTransport = exports.setSchemaToFieldsFn = exports.extractToolShape = exports.extractTableShape = exports.createLocalContractConsumer = exports.contractsSchema = exports.contractsMetaData = exports.ContractsTable = exports.Contracts = exports.inProcessTransportPair = exports.connectionContractTransport = exports.CONTRACT_REQUEST_CHANNEL = exports.CONTRACT_NOTIFY_CHANNEL = exports.registerContractResolver = exports.isSelfTrustedContractCaller = exports.handleContractCall = exports.getContractResolver = exports.createUserContextContractProviderRouter = exports.createLocalUserContextContractProviderRouter = exports.sameUserContractPermissionCheck = exports.createContractProviderSession = exports.createContractProviderEndpoint = exports.createContractProvider = exports.createContractConsumer = exports.CONTRACT_CALL_RPC = exports.contractProvidersSchema = exports.contractProvidersMetaData = exports.ContractProvidersTable = exports.ContractProviders = exports.createContractProviderRouter = exports.PackageBuilder = exports.definePackage = exports.ContractBuilder = void 0;
-exports.validateProviderSatisfiesContract = exports.validateImmutability = exports.validateAlsoImplements = exports.contractKey = exports.registerSystemContract = exports.listSystemContracts = exports.installSystemContracts = exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = void 0;
+exports.DEVICE_OPERATIONS_MAX_TOOLS = exports.DEVICE_OPERATIONS_MAX_ROWS = exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = exports.DEVICE_OPERATIONS_CONTRACT_VERSION = exports.setRemoteContractTransportFactory = exports.resolveRemoteTargetEndpoint = exports.getRemoteContractTransportFactory = exports.createRemoteContractEndpoint = exports.ContractRegistry = exports.PersistentContractRegistry = exports.waitForHostContractTransport = exports.subscribeHostContractTransport = exports.registerHostContractTransport = exports.getHostContractTransport = exports.setSchemaToFieldsFn = exports.extractToolShape = exports.extractTableShape = exports.createLocalContractConsumer = exports.contractsSchema = exports.contractsMetaData = exports.ContractsTable = exports.Contracts = exports.inProcessTransportPair = exports.connectionContractTransport = exports.CONTRACT_REQUEST_CHANNEL = exports.CONTRACT_NOTIFY_CHANNEL = exports.verifyRemoteContractIdentity = exports.registerContractResolver = exports.isSelfTrustedContractCaller = exports.handleContractCall = exports.getContractResolver = exports.createUserContextContractProviderRouter = exports.createLocalUserContextContractProviderRouter = exports.authorizeRemoteContractCall = exports.sameUserContractPermissionCheck = exports.createRemoteContractConsumer = exports.createContractProviderSession = exports.createContractProviderEndpoint = exports.createContractProvider = exports.createContractConsumer = exports.CONTRACT_CALL_RPC = exports.contractProvidersSchema = exports.contractProvidersMetaData = exports.ContractProvidersTable = exports.ContractProviders = exports.createContractProviderRouter = exports.PackageBuilder = exports.definePackage = exports.ContractBuilder = void 0;
+exports.validateProviderSatisfiesContract = exports.validateImmutability = exports.validateAlsoImplements = exports.contractKey = exports.registerSystemContract = exports.listSystemContracts = exports.installSystemContracts = exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = exports.getToolAccessControlContractDefinition = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = void 0;
 var builder_1 = require("./builder");
 Object.defineProperty(exports, "ContractBuilder", { enumerable: true, get: function () { return builder_1.ContractBuilder; } });
 Object.defineProperty(exports, "definePackage", { enumerable: true, get: function () { return builder_1.definePackage; } });
@@ -33,14 +33,17 @@ Object.defineProperty(exports, "createContractConsumer", { enumerable: true, get
 Object.defineProperty(exports, "createContractProvider", { enumerable: true, get: function () { return contract_proxy_1.createContractProvider; } });
 Object.defineProperty(exports, "createContractProviderEndpoint", { enumerable: true, get: function () { return contract_proxy_1.createContractProviderEndpoint; } });
 Object.defineProperty(exports, "createContractProviderSession", { enumerable: true, get: function () { return contract_proxy_1.createContractProviderSession; } });
+Object.defineProperty(exports, "createRemoteContractConsumer", { enumerable: true, get: function () { return contract_proxy_1.createRemoteContractConsumer; } });
 Object.defineProperty(exports, "sameUserContractPermissionCheck", { enumerable: true, get: function () { return contract_proxy_1.sameUserContractPermissionCheck; } });
 var contract_resolvers_1 = require("./contract-resolvers");
+Object.defineProperty(exports, "authorizeRemoteContractCall", { enumerable: true, get: function () { return contract_resolvers_1.authorizeRemoteContractCall; } });
 Object.defineProperty(exports, "createLocalUserContextContractProviderRouter", { enumerable: true, get: function () { return contract_resolvers_1.createLocalUserContextContractProviderRouter; } });
 Object.defineProperty(exports, "createUserContextContractProviderRouter", { enumerable: true, get: function () { return contract_resolvers_1.createUserContextContractProviderRouter; } });
 Object.defineProperty(exports, "getContractResolver", { enumerable: true, get: function () { return contract_resolvers_1.getContractResolver; } });
 Object.defineProperty(exports, "handleContractCall", { enumerable: true, get: function () { return contract_resolvers_1.handleContractCall; } });
 Object.defineProperty(exports, "isSelfTrustedContractCaller", { enumerable: true, get: function () { return contract_resolvers_1.isSelfTrustedContractCaller; } });
 Object.defineProperty(exports, "registerContractResolver", { enumerable: true, get: function () { return contract_resolvers_1.registerContractResolver; } });
+Object.defineProperty(exports, "verifyRemoteContractIdentity", { enumerable: true, get: function () { return contract_resolvers_1.verifyRemoteContractIdentity; } });
 var contract_transport_1 = require("./contract-transport");
 Object.defineProperty(exports, "CONTRACT_NOTIFY_CHANNEL", { enumerable: true, get: function () { return contract_transport_1.CONTRACT_NOTIFY_CHANNEL; } });
 Object.defineProperty(exports, "CONTRACT_REQUEST_CHANNEL", { enumerable: true, get: function () { return contract_transport_1.CONTRACT_REQUEST_CHANNEL; } });
@@ -66,6 +69,11 @@ var persistent_registry_1 = require("./persistent-registry");
 Object.defineProperty(exports, "PersistentContractRegistry", { enumerable: true, get: function () { return persistent_registry_1.PersistentContractRegistry; } });
 var registry_1 = require("./registry");
 Object.defineProperty(exports, "ContractRegistry", { enumerable: true, get: function () { return registry_1.ContractRegistry; } });
+var remote_contract_transport_1 = require("./remote-contract-transport");
+Object.defineProperty(exports, "createRemoteContractEndpoint", { enumerable: true, get: function () { return remote_contract_transport_1.createRemoteContractEndpoint; } });
+Object.defineProperty(exports, "getRemoteContractTransportFactory", { enumerable: true, get: function () { return remote_contract_transport_1.getRemoteContractTransportFactory; } });
+Object.defineProperty(exports, "resolveRemoteTargetEndpoint", { enumerable: true, get: function () { return remote_contract_transport_1.resolveRemoteTargetEndpoint; } });
+Object.defineProperty(exports, "setRemoteContractTransportFactory", { enumerable: true, get: function () { return remote_contract_transport_1.setRemoteContractTransportFactory; } });
 var device_operations_contract_1 = require("./system/device-operations-contract");
 Object.defineProperty(exports, "DEVICE_OPERATIONS_CONTRACT_VERSION", { enumerable: true, get: function () { return device_operations_contract_1.DEVICE_OPERATIONS_CONTRACT_VERSION; } });
 Object.defineProperty(exports, "DEVICE_OPERATIONS_MAX_QUERY_LENGTH", { enumerable: true, get: function () { return device_operations_contract_1.DEVICE_OPERATIONS_MAX_QUERY_LENGTH; } });

package/dist/contracts/remote-contract-transport.d.ts

@@ -0,0 +1,69 @@
+import type { UserContext } from "../context/user-context";
+import type { IContractProviderEndpointRequest } from "./contract-provider-router";
+import type { IContractProviderEndpoint } from "./contract-proxy";
+import { type IContractTransport } from "./contract-transport";
+/** Destination of a device-targeted contract call. */
+export interface IRemoteContractTarget {
+    /** Device that should execute the call. */
+    deviceId: string;
+    /**
+     * Data context the call is scoped to. Required so the transport can seal the message
+     * to the right group or personal keys and the remote device can authorize membership.
+     */
+    dataContextId: string;
+}
+/**
+ * Host-registered factory that produces an outbound {@link IContractTransport} to one
+ * remote device. `peers-device` registers a `sendDeviceMessage`-backed implementation;
+ * the SDK stays transport-agnostic and only knows how to ask for one.
+ */
+export type RemoteContractTransportFactory = (target: IRemoteContractTarget) => IContractTransport;
+/** Trusted host state used to decide whether and how to forward a route. */
+export interface IRemoteContractHost {
+    /** This device's id (`userContext.deviceId()`); a matching target resolves locally. */
+    localDeviceId?: string;
+    /** Owning user context, used to pick a per-context transport factory. */
+    userContext?: UserContext;
+}
+/**
+ * Register (or clear, with `undefined`) the factory used to reach other devices for
+ * contract tool calls. A connection manager registers one for its own `UserContext`;
+ * omitting `opts.userContext` sets the process-wide fallback. Call before any package
+ * invokes a `pkg.remote(...)` device consumer.
+ *
+ * @param factory Factory returning an outbound transport, or `undefined` to unregister.
+ * @param opts.userContext Scope the registration to one user context.
+ */
+export declare function setRemoteContractTransportFactory(factory: RemoteContractTransportFactory | undefined, opts?: {
+    userContext?: UserContext;
+}): void;
+/**
+ * Return the transport factory for a user context, falling back to the process default.
+ *
+ * @param userContext Optional owning user context.
+ */
+export declare function getRemoteContractTransportFactory(userContext?: UserContext): RemoteContractTransportFactory | undefined;
+/**
+ * Shared chokepoint for trusted local hosts: when an authorized route names a device
+ * other than this one, return a forwarding endpoint; otherwise return `undefined` so the
+ * caller resolves the provider locally. A target equal to the local device is treated as
+ * local so `remote.device(myOwnDeviceId)` behaves like a plain consumer.
+ *
+ * @param request Authorized route from a router serving a *local* principal.
+ * @param host This device's id and owning user context.
+ */
+export declare function resolveRemoteTargetEndpoint(request: IContractProviderEndpointRequest, host: IRemoteContractHost): IContractProviderEndpoint | undefined;
+/**
+ * Build a provider endpoint that forwards authorized calls to another device.
+ *
+ * The endpoint is created only by a trusted local host after it has authorized the
+ * *local* caller for the route. It strips {@link IContractCall.targetDeviceId} before
+ * emitting so the receiving device sees an ordinary call addressed to itself and the
+ * message is signed with this device's own identity. Only tool runs are forwarded; the
+ * router rejects other members before reaching this endpoint.
+ *
+ * @param request Authorized route whose `targetDeviceId` and `dataContextId` are set.
+ * @param factory Transport factory; defaults to the process-wide registration.
+ * @throws If no factory is available or the route lacks a target device or data context.
+ */
+export declare function createRemoteContractEndpoint(request: IContractProviderEndpointRequest, factory?: RemoteContractTransportFactory | undefined): IContractProviderEndpoint;

package/dist/contracts/remote-contract-transport.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setRemoteContractTransportFactory = setRemoteContractTransportFactory;
+exports.getRemoteContractTransportFactory = getRemoteContractTransportFactory;
+exports.resolveRemoteTargetEndpoint = resolveRemoteTargetEndpoint;
+exports.createRemoteContractEndpoint = createRemoteContractEndpoint;
+const contract_transport_1 = require("./contract-transport");
+const factoriesByUserContext = new WeakMap();
+let defaultFactory;
+/**
+ * Register (or clear, with `undefined`) the factory used to reach other devices for
+ * contract tool calls. A connection manager registers one for its own `UserContext`;
+ * omitting `opts.userContext` sets the process-wide fallback. Call before any package
+ * invokes a `pkg.remote(...)` device consumer.
+ *
+ * @param factory Factory returning an outbound transport, or `undefined` to unregister.
+ * @param opts.userContext Scope the registration to one user context.
+ */
+function setRemoteContractTransportFactory(factory, opts = {}) {
+    if (opts.userContext) {
+        if (factory) {
+            factoriesByUserContext.set(opts.userContext, factory);
+        }
+        else {
+            factoriesByUserContext.delete(opts.userContext);
+        }
+        return;
+    }
+    defaultFactory = factory;
+}
+/**
+ * Return the transport factory for a user context, falling back to the process default.
+ *
+ * @param userContext Optional owning user context.
+ */
+function getRemoteContractTransportFactory(userContext) {
+    return (userContext && factoriesByUserContext.get(userContext)) ?? defaultFactory;
+}
+/**
+ * Shared chokepoint for trusted local hosts: when an authorized route names a device
+ * other than this one, return a forwarding endpoint; otherwise return `undefined` so the
+ * caller resolves the provider locally. A target equal to the local device is treated as
+ * local so `remote.device(myOwnDeviceId)` behaves like a plain consumer.
+ *
+ * @param request Authorized route from a router serving a *local* principal.
+ * @param host This device's id and owning user context.
+ */
+function resolveRemoteTargetEndpoint(request, host) {
+    if (!request.targetDeviceId || request.targetDeviceId === host.localDeviceId) {
+        return undefined;
+    }
+    return createRemoteContractEndpoint(request, getRemoteContractTransportFactory(host.userContext));
+}
+/**
+ * Build a provider endpoint that forwards authorized calls to another device.
+ *
+ * The endpoint is created only by a trusted local host after it has authorized the
+ * *local* caller for the route. It strips {@link IContractCall.targetDeviceId} before
+ * emitting so the receiving device sees an ordinary call addressed to itself and the
+ * message is signed with this device's own identity. Only tool runs are forwarded; the
+ * router rejects other members before reaching this endpoint.
+ *
+ * @param request Authorized route whose `targetDeviceId` and `dataContextId` are set.
+ * @param factory Transport factory; defaults to the process-wide registration.
+ * @throws If no factory is available or the route lacks a target device or data context.
+ */
+function createRemoteContractEndpoint(request, factory = getRemoteContractTransportFactory()) {
+    const { targetDeviceId, dataContextId } = request;
+    if (!targetDeviceId) {
+        throw new Error("Remote contract endpoint requires a target device id");
+    }
+    if (!dataContextId) {
+        throw new Error("Remote contract endpoint requires an authorized data context id");
+    }
+    if (!factory) {
+        throw new Error(`Cannot reach device ${targetDeviceId}: no remote contract transport is registered on this host`);
+    }
+    const transport = factory({ deviceId: targetDeviceId, dataContextId });
+    let disposed = false;
+    return {
+        handleCall(call) {
+            if (disposed) {
+                return Promise.reject(new Error(`Remote contract endpoint for ${targetDeviceId} is disposed`));
+            }
+            if (call.member !== "tool" || call.operation !== "run") {
+                return Promise.reject(new Error(`Contract ${call.member} '${call.name}'.${call.operation} cannot be forwarded to a remote device`));
+            }
+            const { targetDeviceId: _stripped, ...outbound } = call;
+            return transport.emit(contract_transport_1.CONTRACT_REQUEST_CHANNEL, { ...outbound, dataContextId });
+        },
+        dispose() {
+            disposed = true;
+        },
+    };
+}

package/dist/contracts/types.d.ts

@@ -39,6 +39,13 @@ export interface IContractTool {
     usageDescription: string;
     inputFields: IField[];
     outputFields: IField[];
+    /**
+     * Minimum group access level (0–100) a caller on **another device** needs to run
+     * this tool. Absent means the tool is local-only: consumers on the same device can
+     * call it, but remote devices are denied. Self-trusted callers (the provider's own
+     * account) are never gated by this value. Policy only — not part of shape validation.
+     */
+    remoteAccessLevel?: number;
 }
 /** Observable value exposed by a contract. */
 export interface IContractObservable {
@@ -111,6 +118,51 @@ export interface IConsumedContract {
     /** Deferred handle returned by `consumes()` for this dependency. */
     handle?: IConsumedContractHandle<IContractConsumerBase | undefined>;
 }
+/**
+ * Resolved value of a {@link PackageBuilder.remote} handle: a factory of tools-only
+ * consumers whose calls execute on other devices.
+ *
+ * Unlike a consumed contract, no local provider is required — the executing device
+ * selects its own provider and authorizes the call against the caller's group role and
+ * the tool's {@link IContractTool.remoteAccessLevel}. Only `tools` are reachable on the
+ * returned consumers today; `tables`, `observables`, and `events` throw on access.
+ *
+ * @typeParam T - Consumer proxy type (defaults to {@link IContractConsumer}).
+ */
+export interface IRemoteContractConsumer<T extends IContractConsumerBase = IContractConsumer> {
+    contractId: string;
+    version: number;
+    /**
+     * Consumer whose tool calls run on `deviceId`. Instances are cached per device; passing
+     * this device's own id behaves like a plain local consumer.
+     *
+     * @param deviceId Device that should run the calls.
+     */
+    device(deviceId: string): T;
+    /** Idempotently dispose every per-device consumer created by this factory. */
+    dispose(): void;
+}
+/**
+ * Deferred handle returned by {@link PackageBuilder.remote}.
+ *
+ * Like {@link IConsumedContractHandle}, the handle is not thenable — await
+ * {@link consumer} from runtime code after `definePackage` finishes. The
+ * package-loader settles it once the contract definition is known locally.
+ */
+export interface IRemoteContractHandle<T extends IContractConsumerBase = IContractConsumer> {
+    /** Resolves to the per-device consumer factory. */
+    readonly consumer: Promise<IRemoteContractConsumer<T>>;
+}
+/**
+ * A contract a package calls on other devices. Recorded during `definePackage`;
+ * the loader settles the handle without requiring a local provider.
+ */
+export interface IRemoteContract {
+    contractId: string;
+    version: number;
+    /** Deferred handle returned by `remote()` for this declaration. */
+    handle?: IRemoteContractHandle<IContractConsumerBase>;
+}
 /**
  * Declares that the owning contract's implementation also satisfies another
  * contract (single version or inclusive range).
@@ -132,6 +184,11 @@ export interface IPackageDefinitionResult {
     contracts: IContractDefinition[];
     /** Contracts this package depends on. */
     consumes: IConsumedContract[];
+    /**
+     * Contracts this package calls on other devices via `pkg.remote()`. Optional so
+     * bundles built with an older SDK still load.
+     */
+    remotes?: IRemoteContract[];
     /** `alsoImplements` declarations keyed by the owning contractId+version. */
     alsoImplements: Map<string, IAlsoImplementsDeclaration[]>;
     /** Package-level items not part of any contract. */

package/dist/data/tools.d.ts

@@ -220,6 +220,7 @@ export declare const toolSchema: z.ZodObject<{
     isAssistantRunner: z.ZodOptional<z.ZodBoolean>;
     packageId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     accessLevel: z.ZodDefault<z.ZodNumber>;
+    remoteAccessLevel: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     code: string;
     name: string;
@@ -266,6 +267,7 @@ export declare const toolSchema: z.ZodObject<{
     codeRepository?: string | undefined;
     isAssistantRunner?: boolean | undefined;
     packageId?: string | undefined;
+    remoteAccessLevel?: number | undefined;
 }, {
     name: string;
     toolId: string;
@@ -312,6 +314,7 @@ export declare const toolSchema: z.ZodObject<{
     isAssistantRunner?: boolean | undefined;
     packageId?: string | undefined;
     accessLevel?: number | undefined;
+    remoteAccessLevel?: number | undefined;
 }>;
 /** A tool definition stored in the Tools table. */
 export type ITool = z.infer<typeof toolSchema>;
@@ -373,4 +376,5 @@ export declare function Tools(dataContext?: DataContext): import("..").Table<{
     codeRepository?: string | undefined;
     isAssistantRunner?: boolean | undefined;
     packageId?: string | undefined;
+    remoteAccessLevel?: number | undefined;
 }>;

package/dist/data/tools.js

@@ -49,6 +49,13 @@ exports.toolSchema = zod_1.z.object({
         .describe("Whether this tool is a model that can be used to run an assistant"),
     packageId: zod_types_1.zodPeerId.optional().describe("The package that installed this tool, if any"),
     accessLevel: access_level_1.accessLevelSchema.describe("Required access level (0-100) to run this tool. Unclassified tools default to 100 (Self)."),
+    remoteAccessLevel: zod_1.z
+        .number()
+        .int()
+        .min(access_level_1.MIN_ACCESS_LEVEL)
+        .max(access_level_1.MAX_ACCESS_LEVEL)
+        .optional()
+        .describe("Minimum group access level (0-100) a caller on another device needs to run this tool. Omit to keep the tool local-only."),
 });
 const metaData = {
     name: "Tools",

package/dist/package-loader/isolated-artifact.js

@@ -228,7 +228,14 @@ function validateProvidedContract(contract, index, packageTables) {
         if (!tool || typeof tool !== "object" || Array.isArray(tool)) {
             throw new Error(`${toolLabel} must be an object`);
         }
-        assertOnlyKeys(tool, ["name", "usageDescription", "inputFields", "outputFields", "suggestedAccessLevel"], toolLabel);
+        assertOnlyKeys(tool, [
+            "name",
+            "usageDescription",
+            "inputFields",
+            "outputFields",
+            "suggestedAccessLevel",
+            "remoteAccessLevel",
+        ], toolLabel);
         if (typeof tool.name !== "string" || tool.name.trim() === "") {
             throw new Error(`${toolLabel}.name is required`);
         }
@@ -248,6 +255,13 @@ function validateProvidedContract(contract, index, packageTables) {
                 throw new Error(`${toolLabel}.suggestedAccessLevel must be an integer 0–100`);
             }
         }
+        if (tool.remoteAccessLevel !== undefined) {
+            if (!Number.isInteger(tool.remoteAccessLevel) ||
+                tool.remoteAccessLevel < access_level_1.MIN_ACCESS_LEVEL ||
+                tool.remoteAccessLevel > access_level_1.MAX_ACCESS_LEVEL) {
+                throw new Error(`${toolLabel}.remoteAccessLevel must be an integer 0–100`);
+            }
+        }
     }
     if (contract.tables === undefined) {
         contract.tables = [];
@@ -530,6 +544,7 @@ function isolatedContractToDefinition(contract, packageTables) {
         usageDescription: tool.usageDescription,
         inputFields: tool.inputFields ?? [],
         outputFields: tool.outputFields ?? [],
+        ...(tool.remoteAccessLevel !== undefined ? { remoteAccessLevel: tool.remoteAccessLevel } : {}),
     }));
     const tables = (contract.tables ?? []).map((tableRef) => {
         const table = findPackageTable(packageTables, tableRef.name);

package/dist/package-loader/isolated-runtime.d.ts

@@ -168,8 +168,11 @@ export interface IIsolatedPackagePersistentVarGateway {
 export interface IIsolatedContractProviderEndpointRequest extends IContractProviderEndpointRequest {
     /** Installed isolated package making the consumed-contract call. */
     consumerPackageId: string;
-    /** Registry-selected provider package. */
-    providerPackageId: string;
+    /**
+     * Registry-selected provider package. Omitted for a device-targeted route
+     * (`targetDeviceId` set), where the executing device selects the provider.
+     */
+    providerPackageId?: string;
     /** Optional deadline the gateway should enforce for provider setup/calls. */
     timeoutMs?: number;
 }

package/dist/package-loader/package-loader.d.ts

@@ -2,7 +2,7 @@ import type { DataContext } from "../context/data-context";
 import { type IContractProviderEndpointRequest } from "../contracts/contract-provider-router";
 import { type IContractConsumer, type IContractProviderEndpoint } from "../contracts/contract-proxy";
 import { ContractRegistry } from "../contracts/registry";
-import type { IConsumedContract } from "../contracts/types";
+import type { IConsumedContract, IRemoteContract, IRemoteContractConsumer } from "../contracts/types";
 import { type IPackage } from "../data/packages";
 import type { IPeersPackage } from "../types/peers-package";
 import { type IIsolatedPackageRuntime } from "./isolated-runtime";
@@ -96,6 +96,20 @@ export declare class PackageLoader {
      * @returns A live consumer proxy, or `undefined` when no provider matches.
      */
     resolveConsumedContract(dependency: IConsumedContract): Promise<IContractConsumer | undefined>;
+    /**
+     * Bind a legacy package's `remote()` declaration to a per-device consumer factory.
+     *
+     * No local provider is selected: every device consumer stamps `targetDeviceId` and
+     * this loader's own router forwards the call through
+     * {@link resolveContractEndpoint}, which hands remote targets to the mesh transport
+     * and resolves this device's id locally. The contract definition must already be
+     * registered in this context (from the package's own `provides` or another
+     * installed package) so the proxy knows the tool names.
+     *
+     * @param declaration - Validated package remote declaration.
+     * @returns A per-device consumer factory, or `undefined` when the contract is unknown.
+     */
+    resolveRemoteContract(declaration: IRemoteContract): Promise<IRemoteContractConsumer<IContractConsumer> | undefined>;
     /**
      * Resolve a sandbox-backed provider endpoint when this context owns an
      * isolated provider for the requested contract.

package/dist/package-loader/package-loader.js

@@ -7,6 +7,7 @@ const contract_proxy_1 = require("../contracts/contract-proxy");
 const contract_resolvers_1 = require("../contracts/contract-resolvers");
 const contract_transport_1 = require("../contracts/contract-transport");
 const registry_1 = require("../contracts/registry");
+const remote_contract_transport_1 = require("../contracts/remote-contract-transport");
 const system_contracts_1 = require("../contracts/system-contracts");
 const files_1 = require("../data/files");
 const package_version_resolver_1 = require("../data/package-version-resolver");
@@ -132,6 +133,16 @@ class PackageLoader {
      * @throws If no provider or matching endpoint implementation is available.
      */
     async resolveContractEndpoint(request, opts = {}) {
+        // A route that names another device is forwarded over the mesh instead of being
+        // resolved against a local provider. Only routers serving local principals set
+        // targetDeviceId; remote-caller routers reject it before reaching this point.
+        const remoteEndpoint = (0, remote_contract_transport_1.resolveRemoteTargetEndpoint)(request, {
+            localDeviceId: this.dataContext.userContext?.deviceId(),
+            userContext: this.dataContext.userContext,
+        });
+        if (remoteEndpoint) {
+            return remoteEndpoint;
+        }
         const providerPackageId = opts.providerPackageId ??
             request.providerPackageId ??
             this.contractRegistry.getProviderPackageId(request.contractId, request.version);
@@ -244,6 +255,43 @@ class PackageLoader {
         };
         return consumer;
     }
+    /**
+     * Bind a legacy package's `remote()` declaration to a per-device consumer factory.
+     *
+     * No local provider is selected: every device consumer stamps `targetDeviceId` and
+     * this loader's own router forwards the call through
+     * {@link resolveContractEndpoint}, which hands remote targets to the mesh transport
+     * and resolves this device's id locally. The contract definition must already be
+     * registered in this context (from the package's own `provides` or another
+     * installed package) so the proxy knows the tool names.
+     *
+     * @param declaration - Validated package remote declaration.
+     * @returns A per-device consumer factory, or `undefined` when the contract is unknown.
+     */
+    async resolveRemoteContract(declaration) {
+        const definition = this.contractRegistry.getDefinition(declaration.contractId, declaration.version);
+        if (!definition) {
+            return undefined;
+        }
+        const [consumerTransport, hostTransport] = (0, contract_transport_1.inProcessTransportPair)();
+        const router = (0, contract_provider_router_1.createContractProviderRouter)(hostTransport, {
+            authorizeCall: () => ({
+                dataContextId: this.dataContext.dataContextId,
+                context: { dataContext: this.dataContext },
+            }),
+            resolveProviderPackageId: (request) => this.contractRegistry.getProviderPackageId(request.contractId, request.version),
+            resolveEndpoint: (request) => this.resolveContractEndpoint(request),
+        });
+        const remote = (0, contract_proxy_1.createRemoteContractConsumer)(definition, consumerTransport, {
+            dataContextId: this.dataContext.dataContextId,
+        });
+        const dispose = remote.dispose.bind(remote);
+        remote.dispose = () => {
+            dispose();
+            router.dispose();
+        };
+        return remote;
+    }
     /**
      * Resolve a sandbox-backed provider endpoint when this context owns an
      * isolated provider for the requested contract.

package/dist/package-loader/resolve-consumed-contracts.d.ts

@@ -2,12 +2,16 @@ import type { DataContext } from "../context/data-context";
 import type { ContractRegistry } from "../contracts/registry";
 import type { IPackageDefinitionResult } from "../contracts/types";
 /**
- * Settle each deferred `consumes` handle on a package definition after its
- * providers have been registered.
+ * Settle each deferred `consumes` and `remote` handle on a package definition
+ * after its providers have been registered.
  *
  * A consume succeeds only when {@link ContractRegistry.selectProvider} finds a
  * matching provider and the owning PackageLoader can bind an endpoint. The
  * endpoint may be resolver-backed or isolated. Missing optional deps settle to
  * `undefined`; missing required deps reject the handle.
+ *
+ * A remote declaration needs no local provider: it settles to a per-device
+ * consumer factory as long as the contract definition is registered locally and
+ * a PackageLoader owns the context; otherwise the handle rejects.
  */
 export declare function resolveConsumedContracts(dataContext: DataContext, registry: ContractRegistry, packageDefinition: IPackageDefinitionResult): Promise<void>;

package/dist/package-loader/resolve-consumed-contracts.js

@@ -5,15 +5,20 @@ const builder_1 = require("../contracts/builder");
 const contract_resolvers_1 = require("../contracts/contract-resolvers");
 const create_local_consumer_1 = require("../contracts/create-local-consumer");
 /**
- * Settle each deferred `consumes` handle on a package definition after its
- * providers have been registered.
+ * Settle each deferred `consumes` and `remote` handle on a package definition
+ * after its providers have been registered.
  *
  * A consume succeeds only when {@link ContractRegistry.selectProvider} finds a
  * matching provider and the owning PackageLoader can bind an endpoint. The
  * endpoint may be resolver-backed or isolated. Missing optional deps settle to
  * `undefined`; missing required deps reject the handle.
+ *
+ * A remote declaration needs no local provider: it settles to a per-device
+ * consumer factory as long as the contract definition is registered locally and
+ * a PackageLoader owns the context; otherwise the handle rejects.
  */
 async function resolveConsumedContracts(dataContext, registry, packageDefinition) {
+    await resolveRemoteContracts(dataContext, packageDefinition);
     for (const dep of packageDefinition.consumes) {
         const handle = dep.handle;
         if (!handle) {
@@ -44,6 +49,29 @@ async function resolveConsumedContracts(dataContext, registry, packageDefinition
         }
     }
 }
+async function resolveRemoteContracts(dataContext, packageDefinition) {
+    for (const declaration of packageDefinition.remotes ?? []) {
+        const handle = declaration.handle;
+        if (!handle) {
+            continue;
+        }
+        const key = `${declaration.contractId}@${declaration.version}`;
+        try {
+            const loader = dataContext.packageLoader;
+            if (!loader?.resolveRemoteContract) {
+                throw new Error(`Remote contract ${key} requires a package loader on the data context`);
+            }
+            const remote = await loader.resolveRemoteContract(declaration);
+            if (!remote) {
+                throw new Error(`Remote contract ${key} could not be resolved: its definition is not registered on this device`);
+            }
+            (0, builder_1.settleContractHandle)(handle, remote);
+        }
+        catch (err) {
+            (0, builder_1.rejectContractHandle)(handle, err);
+        }
+    }
+}
 async function resolveLegacyLocalConsumer(dataContext, selected, contractId, version) {
     const resolver = (0, contract_resolvers_1.getContractResolver)(contractId, version, selected.providerPackageId);
     if (!resolver) {

package/dist/package-loader/resolve-consumed-contracts.test.js

@@ -120,4 +120,47 @@ describe("resolveConsumedContracts", () => {
         }
         await expect(consumeHandle.consumer).resolves.toBeUndefined();
     });
+    describe("remote declarations", () => {
+        it("settles a remote handle through the package loader without a local provider", async () => {
+            const remote = { contractId, version: 1, device: jest.fn(), dispose: jest.fn() };
+            const resolveRemoteContract = jest.fn().mockResolvedValue(remote);
+            const dataContext = {
+                dataContextId: "test-ctx",
+                packageLoader: { resolveRemoteContract },
+            };
+            let remoteHandle;
+            const packageDefinition = (0, builder_1.definePackage)((pkg) => {
+                pkg.packageId = (0, utils_1.newid)();
+                pkg.version = "1.0.0";
+                remoteHandle = pkg.remote(contractId, 1);
+            });
+            await (0, resolve_consumed_contracts_1.resolveConsumedContracts)(dataContext, new registry_1.ContractRegistry(), packageDefinition);
+            expect(resolveRemoteContract).toHaveBeenCalledWith(expect.objectContaining({ contractId, version: 1 }));
+            await expect(remoteHandle?.consumer).resolves.toBe(remote);
+        });
+        it("rejects a remote handle when the contract definition is unknown locally", async () => {
+            const dataContext = {
+                dataContextId: "test-ctx",
+                packageLoader: { resolveRemoteContract: jest.fn().mockResolvedValue(undefined) },
+            };
+            let remoteHandle;
+            const packageDefinition = (0, builder_1.definePackage)((pkg) => {
+                pkg.packageId = (0, utils_1.newid)();
+                pkg.version = "1.0.0";
+                remoteHandle = pkg.remote(contractId, 1);
+            });
+            await (0, resolve_consumed_contracts_1.resolveConsumedContracts)(dataContext, new registry_1.ContractRegistry(), packageDefinition);
+            await expect(remoteHandle?.consumer).rejects.toThrow(/not registered on this device/);
+        });
+        it("rejects a remote handle when no package loader owns the context", async () => {
+            let remoteHandle;
+            const packageDefinition = (0, builder_1.definePackage)((pkg) => {
+                pkg.packageId = (0, utils_1.newid)();
+                pkg.version = "1.0.0";
+                remoteHandle = pkg.remote(contractId, 1);
+            });
+            await (0, resolve_consumed_contracts_1.resolveConsumedContracts)(mockDataContext(), new registry_1.ContractRegistry(), packageDefinition);
+            await expect(remoteHandle?.consumer).rejects.toThrow(/requires a package loader/);
+        });
+    });
 });