@peers-app/peers-sdk 0.23.10 → 0.23.12

package/dist/contracts/__tests__/builder.test.js

@@ -123,6 +123,31 @@ describe("definePackage", () => {
         expect(result.consumes[1].version).toBe(2);
         expect(result.consumes[1].handle).toBe(authHandle);
     });
+    it("records remote contracts as deferred handles without requiring a consume", () => {
+        let remoteHandle;
+        const result = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            // A package may target its own contract on other devices.
+            const projects = pkg.contract(PROJECTS_ID, 1, "Projects");
+            projects.tools = [];
+            remoteHandle = pkg.remote(PROJECTS_ID, 1);
+        });
+        expect(result.consumes).toHaveLength(0);
+        expect(result.remotes).toHaveLength(1);
+        expect(result.remotes?.[0]).toMatchObject({ contractId: PROJECTS_ID, version: 1 });
+        expect(result.remotes?.[0].handle).toBe(remoteHandle);
+        expect(remoteHandle?.consumer).toBeInstanceOf(Promise);
+    });
+    it("validates remote declarations", () => {
+        expect(() => (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            pkg.remote("not-an-id", 1);
+        })).toThrow("remote contractId must be a valid peer ID");
+        expect(() => (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            pkg.remote(TASKS_ID, 0);
+        })).toThrow("remote version must be a positive integer");
+    });
     it("preserves consume options and returns a deferred handle", () => {
         const preferredProviderId = (0, utils_1.newid)();
         const result = (0, builder_1.definePackage)((pkg) => {

package/dist/contracts/__tests__/contract-provider-router.test.js

@@ -216,4 +216,49 @@ describe("contract provider router", () => {
         expect(endpoint.dispose).toHaveBeenCalledTimes(1);
         expect(await consumerTransport.emit(index_1.CONTRACT_REQUEST_CHANNEL, makeCall())).toBeUndefined();
     });
+    it("routes device-targeted tool calls by target without selecting a local provider", async () => {
+        const [consumerTransport, providerTransport] = (0, index_1.inProcessTransportPair)();
+        const resolveProviderPackageId = jest.fn(async () => "local-provider");
+        const resolveEndpoint = jest.fn((request) => makeEndpoint(`${request.providerPackageId ?? "none"}@${request.targetDeviceId ?? "local"}`));
+        const router = (0, index_1.createContractProviderRouter)(providerTransport, {
+            authorizeCall: () => ({ dataContextId: "group-context" }),
+            resolveProviderPackageId,
+            resolveEndpoint,
+        });
+        const toolCall = makeCall({ member: "tool", name: "ping", operation: "run", args: [{}] });
+        await expect(consumerTransport.emit(index_1.CONTRACT_REQUEST_CHANNEL, { ...toolCall, targetDeviceId: "device-b" })).resolves.toBe("none@device-b:run");
+        await consumerTransport.emit(index_1.CONTRACT_REQUEST_CHANNEL, {
+            ...toolCall,
+            targetDeviceId: "device-b",
+        });
+        await expect(consumerTransport.emit(index_1.CONTRACT_REQUEST_CHANNEL, { ...toolCall, targetDeviceId: "device-c" })).resolves.toBe("none@device-c:run");
+        await expect(consumerTransport.emit(index_1.CONTRACT_REQUEST_CHANNEL, toolCall)).resolves.toBe("local-provider@local:run");
+        // One endpoint per target device plus one local; provider selection only ran locally.
+        expect(resolveEndpoint).toHaveBeenCalledTimes(3);
+        expect(resolveProviderPackageId).toHaveBeenCalledTimes(1);
+        expect(resolveEndpoint.mock.calls[0][0]).toMatchObject({
+            targetDeviceId: "device-b",
+            dataContextId: "group-context",
+            providerPackageId: undefined,
+        });
+        router.dispose();
+    });
+    it("rejects device-targeted calls that are not tool runs", async () => {
+        const [consumerTransport, providerTransport] = (0, index_1.inProcessTransportPair)();
+        const resolveEndpoint = jest.fn(() => makeEndpoint("never"));
+        const router = (0, index_1.createContractProviderRouter)(providerTransport, {
+            authorizeCall: () => ({ dataContextId: "group-context" }),
+            resolveEndpoint,
+        });
+        await expect(consumerTransport.emit(index_1.CONTRACT_REQUEST_CHANNEL, makeCall({ targetDeviceId: "device-b" }))).rejects.toThrow("only tool runs are remotely callable");
+        await expect(consumerTransport.emit(index_1.CONTRACT_REQUEST_CHANNEL, makeCall({
+            member: "event",
+            name: "changed",
+            operation: "subscribe",
+            subscriptionId: (0, utils_1.newid)(),
+            targetDeviceId: "device-b",
+        }))).rejects.toThrow("only tool runs are remotely callable");
+        expect(resolveEndpoint).not.toHaveBeenCalled();
+        router.dispose();
+    });
 });

package/dist/contracts/__tests__/contract-proxy.test.js

@@ -306,6 +306,73 @@ describe("contract proxy — consumer/provider round-trip", () => {
         expect(proxied).not.toHaveBeenCalled();
     });
 });
+describe("contract proxy — remote (device-targeted) consumers", () => {
+    /** Wire a remote factory to a request handler that echoes the target device. */
+    function wireRemote(contract = makeContract({ observable: true })) {
+        const seen = [];
+        const [consumerTransport, providerTransport] = (0, contract_transport_1.inProcessTransportPair)();
+        const offRequest = providerTransport.on(contract_transport_1.CONTRACT_REQUEST_CHANNEL, async (call) => {
+            seen.push(call);
+            return { ok: call.targetDeviceId };
+        });
+        const remote = (0, contract_proxy_1.createRemoteContractConsumer)(contract, consumerTransport, {
+            dataContextId: "group-1",
+        });
+        cleanups.push(() => {
+            remote.dispose();
+            offRequest();
+        });
+        return { remote, seen, contract };
+    }
+    it("stamps targetDeviceId and the data context on every tool call", async () => {
+        const { remote, seen, contract } = wireRemote();
+        const deviceB = remote.device("device-b");
+        await expect(deviceB.tools["make-widget"]({ color: "red" })).resolves.toEqual({
+            ok: "device-b",
+        });
+        expect(seen).toHaveLength(1);
+        expect(seen[0]).toMatchObject({
+            member: "tool",
+            name: "make-widget",
+            operation: "run",
+            targetDeviceId: "device-b",
+            dataContextId: "group-1",
+            args: [{ color: "red" }],
+        });
+        // Nothing implicit hits the wire: no observable subscribe/get for remote consumers.
+        expect(seen.filter((call) => call.member === "observable")).toHaveLength(0);
+        expect(deviceB.contractId).toBe(contract.contractId);
+        expect(remote.contractId).toBe(contract.contractId);
+        await expect(deviceB.loadingPromise).resolves.toBeUndefined();
+    });
+    it("exposes only tools on a device consumer", () => {
+        const { remote } = wireRemote();
+        const deviceB = remote.device("device-b");
+        expect(() => deviceB.tables.Widgets).toThrow("not remotely accessible");
+        expect(() => deviceB.observables.widgetCount).toThrow("not remotely accessible");
+        expect(() => deviceB.events.anything).toThrow("not remotely accessible");
+        expect(Object.keys(deviceB.tools)).toEqual(["make-widget"]);
+    });
+    it("caches one consumer per device and rejects empty device ids", () => {
+        const { remote } = wireRemote();
+        expect(remote.device("device-b")).toBe(remote.device("device-b"));
+        expect(remote.device("device-b")).not.toBe(remote.device("device-c"));
+        expect(() => remote.device("")).toThrow("non-empty device id");
+    });
+    it("disposes device consumers with the factory and independently", async () => {
+        const { remote } = wireRemote();
+        const deviceA = remote.device("device-a");
+        const deviceB = remote.device("device-b");
+        deviceA.dispose();
+        await expect(deviceA.tools["make-widget"]({ color: "x" })).rejects.toThrow("disposed");
+        await expect(deviceB.tools["make-widget"]({ color: "x" })).resolves.toBeDefined();
+        // A disposed device consumer is evicted so the next lookup gets a fresh one.
+        expect(remote.device("device-a")).not.toBe(deviceA);
+        remote.dispose();
+        await expect(deviceB.tools["make-widget"]({ color: "x" })).rejects.toThrow("disposed");
+        expect(() => remote.device("device-c")).toThrow("disposed");
+    });
+});
 describe("contract proxy — error handling", () => {
     it("rejects an unknown table method", async () => {
         const { consumer } = wire();

package/dist/contracts/__tests__/contract-resolvers.test.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const access_level_1 = require("../../data/access-level");
 const user_permissions_1 = require("../../data/user-permissions");
 const user_trust_levels_1 = require("../../data/user-trust-levels");
 const users_1 = require("../../data/users");
@@ -13,8 +14,18 @@ jest.mock("../../data/group-permissions", () => {
     return {
         ...actual,
         getUserRole: jest.fn(async () => actual.GroupMemberRole.Founder),
+        // The real module is loaded inside this factory (via ../context), which re-enters the
+        // mock and can yield two jest.fn instances. Shared global state keeps every instance
+        // in sync so tests can drive and observe the level the resolvers actually see.
+        getUserAccessLevel: jest.fn(async (dataContext, userId) => {
+            const state = globalThis.__remoteAccessLevelMock;
+            state?.calls.push([dataContext, userId]);
+            return state?.level ?? 80;
+        }),
     };
 });
+const accessLevelMock = { level: 80, calls: [] };
+globalThis.__remoteAccessLevelMock = accessLevelMock;
 jest.mock("../../data/user-trust-levels", () => ({
     UserTrustLevels: jest.fn(),
 }));
@@ -174,6 +185,128 @@ describe("Self-trusted contract caller authorization", () => {
         router.dispose();
     });
 });
+describe("remote contract call authorization (group members)", () => {
+    const groupId = "group";
+    const contractId = (0, utils_1.newid)();
+    const toolCall = {
+        contractId,
+        version: 1,
+        member: "tool",
+        name: "ping",
+        operation: "run",
+        args: [{}],
+        dataContextId: groupId,
+    };
+    function setupGroupMember(opts) {
+        const { remoteIdentity, user } = makeIdentity();
+        const records = new Map();
+        const { groupContext, userContext } = setupUserContext((0, utils_1.newid)(), records);
+        records.set(groupContext, user);
+        mockTrustGet.mockResolvedValue({ trustLevel: socket_type_1.TrustLevel.Trusted });
+        accessLevelMock.level = opts.callerLevel;
+        accessLevelMock.calls = [];
+        const definition = {
+            contractId,
+            version: 1,
+            name: "Ping",
+            description: "",
+            tables: [],
+            tools: [
+                {
+                    name: "ping",
+                    usageDescription: "",
+                    inputFields: [],
+                    outputFields: [],
+                    ...(opts.remoteAccessLevel !== undefined
+                        ? { remoteAccessLevel: opts.remoteAccessLevel }
+                        : {}),
+                },
+                { name: "localOnly", usageDescription: "", inputFields: [], outputFields: [] },
+            ],
+            observables: [],
+            events: [],
+        };
+        const groupDataContext = {
+            groupId,
+            packageLoader: {
+                contractRegistry: {
+                    getDefinition: jest.fn((id, version) => id === contractId && version === 1 ? definition : undefined),
+                },
+            },
+        };
+        userContext.groupIds = jest.fn(() => [groupId]);
+        userContext.getDataContext = jest.fn((id) => id === groupId ? groupDataContext : { groupId: undefined });
+        return { remoteIdentity, userContext, groupDataContext };
+    }
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+    it("allows a verified group member whose role meets the tool's remoteAccessLevel", async () => {
+        const { remoteIdentity, userContext, groupDataContext } = setupGroupMember({
+            remoteAccessLevel: access_level_1.AccessLevel.Writer,
+            callerLevel: access_level_1.AccessLevel.Writer,
+        });
+        const route = await (0, index_1.authorizeRemoteContractCall)(toolCall, userContext, remoteIdentity);
+        expect(route.dataContextId).toBe(groupId);
+        expect(route.context?.callerUserId).toBe(remoteIdentity.userId);
+        expect(route.context?.callerDeviceId).toBe(remoteIdentity.deviceId);
+        expect(route.context?.dataContext).toBe(groupDataContext);
+        expect(accessLevelMock.calls).toEqual([[groupDataContext, remoteIdentity.userId]]);
+    });
+    it("denies a group member below the tool's remoteAccessLevel", async () => {
+        const { remoteIdentity, userContext } = setupGroupMember({
+            remoteAccessLevel: access_level_1.AccessLevel.Admin,
+            callerLevel: access_level_1.AccessLevel.Writer,
+        });
+        await expect((0, index_1.authorizeRemoteContractCall)(toolCall, userContext, remoteIdentity)).rejects.toThrow("requires Admin (60)");
+    });
+    it("denies a remoteAccessLevel of 0 to callers with no role", async () => {
+        const { remoteIdentity, userContext } = setupGroupMember({
+            remoteAccessLevel: access_level_1.AccessLevel.None,
+            callerLevel: access_level_1.AccessLevel.None,
+        });
+        await expect((0, index_1.authorizeRemoteContractCall)(toolCall, userContext, remoteIdentity)).rejects.toThrow("Permission denied");
+    });
+    it("denies tools that are not marked remotely callable", async () => {
+        const { remoteIdentity, userContext } = setupGroupMember({ callerLevel: access_level_1.AccessLevel.Owner });
+        await expect((0, index_1.authorizeRemoteContractCall)({ ...toolCall, name: "localOnly" }, userContext, remoteIdentity)).rejects.toThrow("not remotely callable");
+        await expect((0, index_1.authorizeRemoteContractCall)(toolCall, userContext, remoteIdentity)).rejects.toThrow("not remotely callable");
+    });
+    it("denies tools missing from the registered contract definition", async () => {
+        const { remoteIdentity, userContext } = setupGroupMember({ callerLevel: access_level_1.AccessLevel.Owner });
+        await expect((0, index_1.authorizeRemoteContractCall)({ ...toolCall, name: "missing" }, userContext, remoteIdentity)).rejects.toThrow("not provided in this data context");
+    });
+    it("denies non-tool members and subscriptions for group callers", async () => {
+        const { remoteIdentity, userContext } = setupGroupMember({
+            remoteAccessLevel: access_level_1.AccessLevel.Reader,
+            callerLevel: access_level_1.AccessLevel.Owner,
+        });
+        await expect((0, index_1.authorizeRemoteContractCall)({ ...toolCall, member: "table", name: "Items", operation: "list" }, userContext, remoteIdentity)).rejects.toThrow("only tool runs are remotely callable");
+        await expect((0, index_1.authorizeRemoteContractCall)({ ...toolCall, member: "event", operation: "subscribe", subscriptionId: (0, utils_1.newid)() }, userContext, remoteIdentity)).rejects.toThrow("only tool runs are remotely callable");
+    });
+    it("requires an explicit shared-group data context", async () => {
+        const { remoteIdentity, userContext } = setupGroupMember({
+            remoteAccessLevel: access_level_1.AccessLevel.Reader,
+            callerLevel: access_level_1.AccessLevel.Owner,
+        });
+        await expect((0, index_1.authorizeRemoteContractCall)({ ...toolCall, dataContextId: undefined }, userContext, remoteIdentity)).rejects.toThrow("shared group data context is required");
+        await expect((0, index_1.authorizeRemoteContractCall)({ ...toolCall, dataContextId: "unknown-group" }, userContext, remoteIdentity)).rejects.toThrow("shared group data context is required");
+    });
+    it("rejects relayed calls that still carry a targetDeviceId", async () => {
+        const { remoteIdentity, userContext } = setupGroupMember({
+            remoteAccessLevel: access_level_1.AccessLevel.Reader,
+            callerLevel: access_level_1.AccessLevel.Owner,
+        });
+        await expect((0, index_1.authorizeRemoteContractCall)({ ...toolCall, targetDeviceId: (0, utils_1.newid)() }, userContext, remoteIdentity)).rejects.toThrow("cannot relay");
+    });
+    it("keeps full access for Self-trusted callers without consulting remoteAccessLevel", async () => {
+        const { remoteIdentity, userContext } = setupGroupMember({ callerLevel: access_level_1.AccessLevel.None });
+        mockTrustGet.mockResolvedValue({ trustLevel: socket_type_1.TrustLevel.Self });
+        const route = await (0, index_1.authorizeRemoteContractCall)({ ...toolCall, name: "localOnly" }, userContext, remoteIdentity);
+        expect(route.dataContextId).toBe(groupId);
+        expect(accessLevelMock.calls).toEqual([]);
+    });
+});
 describe("local user-context contract routing", () => {
     function setupLocalRouter() {
         const userId = (0, utils_1.newid)();

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

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

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

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../index");
+const makeRequest = (overrides = {}) => ({
+    contractId: "contract-a",
+    version: 1,
+    dataContextId: "group-1",
+    targetDeviceId: "device-b",
+    context: {},
+    notify: async () => undefined,
+    ...overrides,
+});
+const toolCall = {
+    contractId: "contract-a",
+    version: 1,
+    member: "tool",
+    name: "ping",
+    operation: "run",
+    args: [{ n: 1 }],
+    dataContextId: "group-1",
+    targetDeviceId: "device-b",
+};
+function makeTransport() {
+    const emit = jest.fn(async (_channel, ..._args) => "pong");
+    const transport = { emit, on: () => () => undefined };
+    return { transport, emit };
+}
+afterEach(() => {
+    (0, index_1.setRemoteContractTransportFactory)(undefined);
+});
+describe("remote contract endpoint", () => {
+    it("strips targetDeviceId and pins the authorized data context before emitting", async () => {
+        const { transport, emit } = makeTransport();
+        const factory = jest.fn(() => transport);
+        const endpoint = (0, index_1.createRemoteContractEndpoint)(makeRequest(), factory);
+        await expect(endpoint.handleCall(toolCall, {})).resolves.toBe("pong");
+        expect(factory).toHaveBeenCalledWith({ deviceId: "device-b", dataContextId: "group-1" });
+        expect(emit).toHaveBeenCalledTimes(1);
+        const [channel, sent] = emit.mock.calls[0];
+        expect(channel).toBe(index_1.CONTRACT_REQUEST_CHANNEL);
+        expect(sent).not.toHaveProperty("targetDeviceId");
+        expect(sent).toMatchObject({ name: "ping", dataContextId: "group-1", args: [{ n: 1 }] });
+    });
+    it("refuses to forward anything but tool runs and rejects after dispose", async () => {
+        const { transport, emit } = makeTransport();
+        const endpoint = (0, index_1.createRemoteContractEndpoint)(makeRequest(), () => transport);
+        await expect(endpoint.handleCall({ ...toolCall, member: "table", name: "Items", operation: "list" }, {})).rejects.toThrow("cannot be forwarded");
+        endpoint.dispose();
+        await expect(endpoint.handleCall(toolCall, {})).rejects.toThrow("disposed");
+        expect(emit).not.toHaveBeenCalled();
+    });
+    it("fails clearly when no transport factory is registered or the route is incomplete", () => {
+        expect(() => (0, index_1.createRemoteContractEndpoint)(makeRequest())).toThrow("no remote contract transport is registered");
+        expect(() => (0, index_1.createRemoteContractEndpoint)(makeRequest({ dataContextId: undefined }), () => makeTransport().transport)).toThrow("data context");
+        expect(() => (0, index_1.createRemoteContractEndpoint)(makeRequest({ targetDeviceId: undefined }), () => makeTransport().transport)).toThrow("target device");
+    });
+});
+describe("resolveRemoteTargetEndpoint", () => {
+    it("returns undefined for local routes and for the local device itself", () => {
+        (0, index_1.setRemoteContractTransportFactory)(() => makeTransport().transport);
+        expect((0, index_1.resolveRemoteTargetEndpoint)(makeRequest({ targetDeviceId: undefined }), {
+            localDeviceId: "device-a",
+        })).toBeUndefined();
+        expect((0, index_1.resolveRemoteTargetEndpoint)(makeRequest({ targetDeviceId: "device-a" }), {
+            localDeviceId: "device-a",
+        })).toBeUndefined();
+    });
+    it("prefers a factory scoped to the owning user context over the process default", async () => {
+        const scoped = makeTransport();
+        const fallback = makeTransport();
+        const userContext = {};
+        (0, index_1.setRemoteContractTransportFactory)(() => fallback.transport);
+        (0, index_1.setRemoteContractTransportFactory)(() => scoped.transport, { userContext });
+        const scopedEndpoint = (0, index_1.resolveRemoteTargetEndpoint)(makeRequest(), {
+            localDeviceId: "device-a",
+            userContext,
+        });
+        const fallbackEndpoint = (0, index_1.resolveRemoteTargetEndpoint)(makeRequest(), {
+            localDeviceId: "device-a",
+        });
+        await scopedEndpoint?.handleCall(toolCall, {});
+        await fallbackEndpoint?.handleCall(toolCall, {});
+        expect(scoped.emit).toHaveBeenCalledTimes(1);
+        expect(fallback.emit).toHaveBeenCalledTimes(1);
+        (0, index_1.setRemoteContractTransportFactory)(undefined, { userContext });
+        (0, index_1.setRemoteContractTransportFactory)(undefined);
+        expect(() => (0, index_1.resolveRemoteTargetEndpoint)(makeRequest(), { userContext })).toThrow("no remote contract transport is registered");
+    });
+});

package/dist/contracts/builder.d.ts

@@ -2,7 +2,7 @@ import type { ITableDefinition } from "../data/orm/table-definitions.type";
 import type { IToolInstance } from "../data/tools";
 import type { IContractConsumer, IContractConsumerBase } from "./contract-proxy";
 import type { IExtractableTableDef, IExtractableToolInstance } from "./extract";
-import type { IAlsoImplementsDeclaration, IConsumedContractHandle, IConsumedContractOptions, IContractDefinition, IContractEvent, IContractObservable, IPackageDefinitionResult } from "./types";
+import type { IAlsoImplementsDeclaration, IConsumedContractHandle, IConsumedContractOptions, IContractDefinition, IContractEvent, IContractObservable, IPackageDefinitionResult, IRemoteContractHandle } from "./types";
 /**
  * Scoped builder for a single contract within a package. Returned by
  * `PackageBuilder.contract()`.
@@ -57,6 +57,20 @@ export declare class ContractBuilder {
         tableDefinitions: ITableDefinition[];
     };
 }
+/**
+ * Shape shared by {@link IConsumedContractHandle} and {@link IRemoteContractHandle}:
+ * a non-thenable object whose `consumer` promise the SDK settles after load.
+ */
+export interface IDeferredContractHandle<V> {
+    readonly consumer: Promise<V>;
+}
+/**
+ * Create a deferred contract handle. Settlement is SDK-owned via
+ * {@link settleContractHandle} / {@link rejectContractHandle}.
+ *
+ * @internal
+ */
+export declare function createDeferredContractHandle<V>(): IDeferredContractHandle<V>;
 /**
  * Create a deferred consumed-contract handle. Settlement is SDK-owned via
  * {@link settleConsumedContractHandle} / {@link rejectConsumedContractHandle}.
@@ -64,6 +78,18 @@ export declare class ContractBuilder {
  * @internal
  */
 export declare function createConsumedContractHandle<T extends IContractConsumerBase | undefined = IContractConsumerBase | undefined>(): IConsumedContractHandle<T>;
+/**
+ * Resolve a deferred contract handle. One-shot — throws if already settled.
+ *
+ * @internal Used by the package-loader when settling `consumes` / `remote` handles.
+ */
+export declare function settleContractHandle<V>(handle: IDeferredContractHandle<V>, value: V): void;
+/**
+ * Reject a deferred contract handle. One-shot — throws if already settled.
+ *
+ * @internal Used by the package-loader when settling `consumes` / `remote` handles.
+ */
+export declare function rejectContractHandle(handle: IDeferredContractHandle<unknown>, reason: unknown): void;
 /**
  * Resolve a consumed-contract handle with a live proxy, or `undefined` for an
  * unmatched optional dependency. One-shot — throws if already settled.
@@ -92,6 +118,7 @@ export declare class PackageBuilder {
     private _version?;
     private _contracts;
     private _consumes;
+    private _remotes;
     /** Package-level assistants (not part of any contract). */
     assistants: unknown[];
     /** Package-level app navigation items (not part of any contract). */
@@ -138,6 +165,25 @@ export declare class PackageBuilder {
     consumes<T extends IContractConsumerBase = IContractConsumer>(contractId: string, version: number, opts?: Omit<IConsumedContractOptions, "optional"> & {
         optional?: false;
     }): IConsumedContractHandle<T>;
+    /**
+     * Declare that this package calls a contract's tools on **other devices**.
+     *
+     * A sibling of {@link consumes} for the mesh: the resolved
+     * {@link IRemoteContractConsumer} hands out a tools-only consumer per target device
+     * (`remote.device(deviceId).tools.x(...)`). No local provider is needed — a package
+     * commonly targets its *own* contract on a peer's device — and there is no `optional`
+     * flag because whether the remote device can serve the call is only known per call.
+     * The loader settles the handle once the contract definition is registered locally
+     * (from this package's `provides` or any installed package) and rejects it otherwise.
+     *
+     * Await `handle.consumer` from runtime code after package definition, not inside
+     * this callback.
+     *
+     * @typeParam T - Consumer proxy type (defaults to {@link IContractConsumer}).
+     * @param contractId - Must be a valid peer ID (25-char alphanumeric from `newid()`).
+     * @param version - Positive integer version number.
+     */
+    remote<T extends IContractConsumerBase = IContractConsumer>(contractId: string, version: number): IRemoteContractHandle<T>;
     /** @internal Finalize and return the package definition result. */
     _build(): IPackageDefinitionResult;
 }

package/dist/contracts/builder.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PackageBuilder = exports.ContractBuilder = void 0;
+exports.createDeferredContractHandle = createDeferredContractHandle;
 exports.createConsumedContractHandle = createConsumedContractHandle;
+exports.settleContractHandle = settleContractHandle;
+exports.rejectContractHandle = rejectContractHandle;
 exports.settleConsumedContractHandle = settleConsumedContractHandle;
 exports.rejectConsumedContractHandle = rejectConsumedContractHandle;
 exports.definePackage = definePackage;
@@ -106,14 +109,14 @@ class ContractBuilder {
     }
 }
 exports.ContractBuilder = ContractBuilder;
-const consumedContractDeferreds = new WeakMap();
+const contractHandleDeferreds = new WeakMap();
 /**
- * Create a deferred consumed-contract handle. Settlement is SDK-owned via
- * {@link settleConsumedContractHandle} / {@link rejectConsumedContractHandle}.
+ * Create a deferred contract handle. Settlement is SDK-owned via
+ * {@link settleContractHandle} / {@link rejectContractHandle}.
  *
  * @internal
  */
-function createConsumedContractHandle() {
+function createDeferredContractHandle() {
     let resolve;
     let reject;
     const consumer = new Promise((res, rej) => {
@@ -124,25 +127,53 @@ function createConsumedContractHandle() {
     // error before any package code awaits the handle.
     consumer.catch(() => { });
     const handle = { consumer };
-    consumedContractDeferreds.set(handle, { resolve, reject, settled: false });
+    contractHandleDeferreds.set(handle, { resolve, reject, settled: false });
     return handle;
 }
 /**
- * Resolve a consumed-contract handle with a live proxy, or `undefined` for an
- * unmatched optional dependency. One-shot — throws if already settled.
+ * Create a deferred consumed-contract handle. Settlement is SDK-owned via
+ * {@link settleConsumedContractHandle} / {@link rejectConsumedContractHandle}.
  *
- * @internal Used by the package-loader when settling `consumes` handles.
+ * @internal
  */
-function settleConsumedContractHandle(handle, consumer) {
-    const deferred = consumedContractDeferreds.get(handle);
+function createConsumedContractHandle() {
+    return createDeferredContractHandle();
+}
+function takeDeferred(handle) {
+    const deferred = contractHandleDeferreds.get(handle);
     if (!deferred) {
-        throw new Error("Unknown consumed-contract handle");
+        throw new Error("Unknown contract handle");
     }
     if (deferred.settled) {
-        throw new Error("Consumed-contract handle has already been settled");
+        throw new Error("Contract handle has already been settled");
     }
     deferred.settled = true;
-    deferred.resolve(consumer);
+    return deferred;
+}
+/**
+ * Resolve a deferred contract handle. One-shot — throws if already settled.
+ *
+ * @internal Used by the package-loader when settling `consumes` / `remote` handles.
+ */
+function settleContractHandle(handle, value) {
+    takeDeferred(handle).resolve(value);
+}
+/**
+ * Reject a deferred contract handle. One-shot — throws if already settled.
+ *
+ * @internal Used by the package-loader when settling `consumes` / `remote` handles.
+ */
+function rejectContractHandle(handle, reason) {
+    takeDeferred(handle).reject(reason);
+}
+/**
+ * Resolve a consumed-contract handle with a live proxy, or `undefined` for an
+ * unmatched optional dependency. One-shot — throws if already settled.
+ *
+ * @internal Used by the package-loader when settling `consumes` handles.
+ */
+function settleConsumedContractHandle(handle, consumer) {
+    settleContractHandle(handle, consumer);
 }
 /**
  * Reject a consumed-contract handle (e.g. required dependency missing).
@@ -151,15 +182,7 @@ function settleConsumedContractHandle(handle, consumer) {
  * @internal Used by the package-loader when settling `consumes` handles.
  */
 function rejectConsumedContractHandle(handle, reason) {
-    const deferred = consumedContractDeferreds.get(handle);
-    if (!deferred) {
-        throw new Error("Unknown consumed-contract handle");
-    }
-    if (deferred.settled) {
-        throw new Error("Consumed-contract handle has already been settled");
-    }
-    deferred.settled = true;
-    deferred.reject(reason);
+    rejectContractHandle(handle, reason);
 }
 /**
  * Top-level builder passed to the `definePackage` callback.
@@ -175,6 +198,7 @@ class PackageBuilder {
     _version;
     _contracts = [];
     _consumes = [];
+    _remotes = [];
     /** Package-level assistants (not part of any contract). */
     assistants = [];
     /** Package-level app navigation items (not part of any contract). */
@@ -248,6 +272,39 @@ class PackageBuilder {
         });
         return handle;
     }
+    /**
+     * Declare that this package calls a contract's tools on **other devices**.
+     *
+     * A sibling of {@link consumes} for the mesh: the resolved
+     * {@link IRemoteContractConsumer} hands out a tools-only consumer per target device
+     * (`remote.device(deviceId).tools.x(...)`). No local provider is needed — a package
+     * commonly targets its *own* contract on a peer's device — and there is no `optional`
+     * flag because whether the remote device can serve the call is only known per call.
+     * The loader settles the handle once the contract definition is registered locally
+     * (from this package's `provides` or any installed package) and rejects it otherwise.
+     *
+     * Await `handle.consumer` from runtime code after package definition, not inside
+     * this callback.
+     *
+     * @typeParam T - Consumer proxy type (defaults to {@link IContractConsumer}).
+     * @param contractId - Must be a valid peer ID (25-char alphanumeric from `newid()`).
+     * @param version - Positive integer version number.
+     */
+    remote(contractId, version) {
+        if (!(0, utils_1.isid)(contractId)) {
+            throw new Error(`remote contractId must be a valid peer ID (25-char alphanumeric), got "${contractId}"`);
+        }
+        if (version < 1 || !Number.isInteger(version)) {
+            throw new Error(`remote version must be a positive integer, got ${version}`);
+        }
+        const handle = createDeferredContractHandle();
+        this._remotes.push({
+            contractId,
+            version,
+            handle: handle,
+        });
+        return handle;
+    }
     /** @internal Finalize and return the package definition result. */
     _build() {
         if (!this._packageId) {
@@ -274,6 +331,7 @@ class PackageBuilder {
             version: this._version,
             contracts,
             consumes: [...this._consumes],
+            remotes: [...this._remotes],
             alsoImplements: alsoImplementsMap,
             assistants: [...this.assistants],
             appNavs: [...this.appNavs],

package/dist/contracts/contract-provider-router.d.ts

@@ -33,6 +33,12 @@ export interface IContractProviderEndpointRequest {
     providerPackageId?: string;
     /** Canonical data context returned by the authorization hook. */
     dataContextId?: string;
+    /**
+     * Device that should execute calls on this route when it differs from the local
+     * device. Copied from {@link IContractCall.targetDeviceId} by the router; the endpoint
+     * resolver decides whether forwarding is permitted for this router's principal.
+     */
+    targetDeviceId?: string;
     /** Authorized caller context for this route. */
     context: IContractCallContext;
     /** Sink for provider-to-consumer subscription notifications. */