@peers-app/peers-sdk 0.23.9 → 0.23.11

package/dist/context/user-context-singleton.js

@@ -135,12 +135,27 @@ function getAllTables() {
     return tableMap;
 }
 if (!rpc_types_1.isClient) {
+    /**
+     * Resolve a table for a renderer RPC call.
+     *
+     * Prefers a full (code/package-registered) instance. When no package on this
+     * device has registered `tableName`, falls back to a synced
+     * `TableDefinitions` record so a renderer whose UI bundle is ahead of the
+     * package the host loaded can still reach the table's data.
+     */
     async function getTable(dataContextId, tableName) {
         const userContext = await getUserContext();
-        const table = userContext
-            .getDataContext(dataContextId || userContext.userId)
-            .tableContainer.getTable(tableName);
-        return table;
+        const tableContainer = userContext.getDataContext(dataContextId || userContext.userId).tableContainer;
+        try {
+            return tableContainer.getTable(tableName);
+        }
+        catch (err) {
+            const fallback = await tableContainer.getFallbackTable(tableName);
+            if (fallback) {
+                return fallback;
+            }
+            throw err;
+        }
     }
     // TODO: add check that client has permission to make this call
     rpc_types_1.rpcServerCalls.tableMethodCall = async (dataContextId, tableName, methodName, ...args) => {

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;
 }