@peers-app/peers-sdk 0.23.9 → 0.23.11

package/dist/data/persistent-vars.js

@@ -277,26 +277,71 @@ function persistentVarFactory(name, opts) {
         void (async () => {
             try {
                 const userContext = opts?.userContext || (await (0, user_context_singleton_1.getUserContext)());
-                function getDataContext() {
-                    if (opts?.dataContext) {
-                        return opts.dataContext;
-                    }
+                /**
+                 * The data context whose `PersistentVars` table stores this variable.
+                 *
+                 * Only `group` scope lives in a group DB. Every other scope lives in the
+                 * user's personal DB; for `groupDevice` / `groupUser` the route context
+                 * (`opts.dataContext` or the current default group) only disambiguates
+                 * the stored name (see {@link getVarNameInDb}). Storing the record in
+                 * the personal DB regardless of whether a caller pinned a `dataContext`
+                 * keeps server-side callers (which pin) and renderer callers (which
+                 * don't) reading and writing the same row.
+                 */
+                function getStorageDataContext() {
                     if (scope === "group") {
-                        return userContext.defaultDataContext();
+                        return opts?.dataContext ?? userContext.defaultDataContext();
+                    }
+                    return userContext.userDataContext;
+                }
+                /**
+                 * Before storage was unified in the personal DB, a `groupDevice` /
+                 * `groupUser` var created with an explicit group `dataContext` was
+                 * written to that group's DB. Return that legacy location so an
+                 * existing value can be migrated forward, or `undefined` when there is
+                 * no distinct legacy location for this variable.
+                 */
+                function getLegacyStorageDataContext() {
+                    if (scope !== "groupDevice" && scope !== "groupUser") {
+                        return undefined;
                     }
-                    else {
-                        return userContext.userDataContext;
+                    const pinned = opts?.dataContext;
+                    if (!pinned || pinned.dataContextId === userContext.userDataContext.dataContextId) {
+                        return undefined;
                     }
+                    return pinned;
                 }
                 function getVarNameInDb() {
                     const dc = opts?.dataContext || userContext.defaultDataContext();
                     return (0, persistent_var_identity_1.persistentVarStorageName)(name, scope, dc?.dataContextId);
                 }
+                /**
+                 * Copy a record left in a group DB by the pre-unification storage rule
+                 * into the personal DB. Secrets are skipped because their ciphertext is
+                 * bound to the group key and cannot be moved verbatim. The legacy row is
+                 * left in place: older builds on other devices may still read it, and
+                 * the personal copy is authoritative from here on.
+                 */
+                async function migrateLegacyRec(table, name) {
+                    const legacyContext = getLegacyStorageDataContext();
+                    if (!legacyContext) {
+                        return undefined;
+                    }
+                    const legacyRec = await PersistentVars(legacyContext).findOne({ name });
+                    if (!legacyRec || legacyRec.scope !== scope || legacyRec.isSecret) {
+                        return undefined;
+                    }
+                    const { persistentVarId: _legacyId, ...rest } = legacyRec;
+                    return table.save({ ...rest, persistentVarId: "" }, { weakInsert: true });
+                }
                 async function loadRecFromDb() {
-                    const dc = getDataContext();
+                    const dc = getStorageDataContext();
                     const table = PersistentVars(dc);
                     const name = getVarNameInDb();
                     let dbRec = await table.findOne({ name });
+                    if (!dbRec) {
+                        dbRec = await migrateLegacyRec(table, name);
+                    }
                     if (dbRec) {
                         if (dbRec.scope !== scope) {
                             console.warn(`${name}: deleting old persistent var record because scopes don't match.  If this is unexpected there could be two different persistent variables using the same name`);
@@ -340,7 +385,7 @@ function persistentVarFactory(name, opts) {
                         return;
                     }
                     rec.value.value = value;
-                    const dc = getDataContext();
+                    const dc = getStorageDataContext();
                     const table = PersistentVars(dc);
                     try {
                         rec = await table.save(rec, { weakInsert: true });
@@ -362,7 +407,7 @@ function persistentVarFactory(name, opts) {
                     }
                 }
                 deleteVarImpl = async () => {
-                    const dc = getDataContext();
+                    const dc = getStorageDataContext();
                     const table = PersistentVars(dc);
                     if (rec?.persistentVarId) {
                         await table.delete(rec);
@@ -374,7 +419,7 @@ function persistentVarFactory(name, opts) {
                 };
                 // subscribe to db changes
                 userContext.subscribeToDataChangedAcrossAllGroups(exports.persistentVarsMetaData.name, async (evt) => {
-                    const dc = getDataContext();
+                    const dc = getStorageDataContext();
                     if (dc && evt.dataContext && evt.dataContext.dataContextId !== dc.dataContextId) {
                         return;
                     }

package/dist/data/tool-access-approvals.d.ts

@@ -50,8 +50,8 @@ export declare const toolAccessApprovalSchema: z.ZodObject<{
     userId: string;
     expiresAt: Date;
     toolId: string;
-    createdAt: Date;
     dataContextId: string;
+    createdAt: Date;
     toolAccessApprovalId: string;
     toolName: string;
     argsHash: string;
@@ -106,8 +106,8 @@ export declare function ToolAccessApprovals(dataContext?: DataContext): import("
     userId: string;
     expiresAt: Date;
     toolId: string;
-    createdAt: Date;
     dataContextId: string;
+    createdAt: Date;
     toolAccessApprovalId: string;
     toolName: string;
     argsHash: string;

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/);
+        });
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peers-app/peers-sdk",
-  "version": "0.23.9",
+  "version": "0.23.11",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-sdk.git"