@peers-app/peers-sdk 0.26.4 → 0.26.6

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

@@ -345,6 +345,23 @@ describe("remote contract call authorization (group members)", () => {
         });
         await expect((0, index_1.authorizeRemoteContractCall)({ ...toolCall, targetDeviceId: (0, utils_1.newid)() }, userContext, remoteIdentity)).rejects.toThrow("cannot relay");
     });
+    it("lets a Self-trusted device administer System Packages on this device", 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, contractId: system_ids_1.packagesContractId, name: "activatePackageVersion" }, userContext, remoteIdentity);
+        expect(route.dataContextId).toBe(groupId);
+        expect(route.context?.callerDeviceId).toBe(remoteIdentity.deviceId);
+    });
+    it.each([
+        ["Admin", access_level_1.AccessLevel.Admin],
+        ["Owner", access_level_1.AccessLevel.Owner],
+    ])("refuses System Packages to a group %s who is not trusted as Self", async (_role, level) => {
+        const { remoteIdentity, userContext, groupDataContext } = setupGroupMember({
+            callerLevel: level,
+        });
+        groupDataContext.packageLoader.contractRegistry.getDefinition.mockReturnValue((0, index_1.getPackagesContractDefinition)());
+        await expect((0, index_1.authorizeRemoteContractCall)({ ...toolCall, contractId: system_ids_1.packagesContractId, name: "listPackages" }, userContext, remoteIdentity)).rejects.toThrow("tool is not remotely callable");
+    });
     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 });
@@ -352,6 +369,13 @@ describe("remote contract call authorization (group members)", () => {
         expect(route.dataContextId).toBe(groupId);
         expect(accessLevelMock.calls).toEqual([]);
     });
+    it("refuses a Self-trusted caller naming a group this device does not have", async () => {
+        const { remoteIdentity, userContext } = setupGroupMember({ callerLevel: access_level_1.AccessLevel.None });
+        mockTrustGet.mockResolvedValue({ trustLevel: socket_type_1.TrustLevel.Self });
+        const unknownGroupId = (0, utils_1.newid)();
+        await expect((0, index_1.authorizeRemoteContractCall)({ ...toolCall, dataContextId: unknownGroupId }, userContext, remoteIdentity)).rejects.toThrow("not available locally");
+        expect(userContext.getDataContext).not.toHaveBeenCalledWith(unknownGroupId);
+    });
 });
 describe("local user-context contract routing", () => {
     function setupLocalRouter() {

package/dist/contracts/__tests__/legacy-removal.test.js

@@ -18,6 +18,44 @@ test("the SDK exports no executable registry", () => {
     for (const name of removedRegistryExports)
         expect(sdk).not.toHaveProperty(name);
 });
+test("package administration has no RPC stubs; System Packages replaces them", () => {
+    for (const name of [
+        "addOrUpdatePackage",
+        "seedBundledPeersCore",
+        "signPackageAuthorVersion",
+        "injectUIBundle",
+    ])
+        expect(sdk.rpcServerCalls).not.toHaveProperty(name);
+    expect(sdk).not.toHaveProperty("unwrapAddOrUpdatePackageResult");
+    expect(sdk.getPackagesContractDefinition().name).toBe("System Packages");
+});
+test("the host shell has no RPC stubs; System Host Shell replaces them", () => {
+    for (const name of [
+        "openLinkInBrowser",
+        "openPath",
+        "openPackage",
+        "copyPvarValueToClipboard",
+        "appQuit",
+        "appRestart",
+        "uiReload",
+        "uiInspect",
+        "uiClick",
+        "uiSet",
+        "uiScroll",
+    ])
+        expect(sdk.rpcServerCalls).not.toHaveProperty(name);
+    for (const name of [
+        "setClientPath",
+        "openThread",
+        "uiGetState",
+        "uiDoClick",
+        "uiDoSet",
+        "uiDoScroll",
+    ])
+        expect(sdk.rpcClientCalls).not.toHaveProperty(name);
+    expect(sdk).not.toHaveProperty("UIState");
+    expect(sdk.getHostShellContractDefinition().name).toBe("System Host Shell");
+});
 test("old SDK assignments warn once and never produce executables", () => {
     const builder = new builder_1.ContractBuilder((0, utils_1.newid)(), 1, "Old package");
     const warn = jest.spyOn(console, "warn").mockImplementation(() => { });

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

@@ -30,6 +30,17 @@ afterEach(() => {
     (0, index_1.setRemoteContractTransportFactory)(undefined);
 });
 describe("remote contract endpoint", () => {
+    it("selects the current transport for every call on a cached endpoint", async () => {
+        const first = makeTransport();
+        const second = makeTransport();
+        let current = first.transport;
+        const endpoint = (0, index_1.createRemoteContractEndpoint)(makeRequest(), () => current);
+        await endpoint.handleCall(toolCall, {});
+        current = second.transport;
+        await endpoint.handleCall(toolCall, {});
+        expect(first.emit).toHaveBeenCalledTimes(1);
+        expect(second.emit).toHaveBeenCalledTimes(1);
+    });
     it("strips targetDeviceId and pins the authorized data context before emitting", async () => {
         const { transport, emit } = makeTransport();
         const factory = jest.fn(() => transport);
@@ -50,13 +61,21 @@ describe("remote contract endpoint", () => {
         await expect(endpoint.handleCall(toolCall, {})).rejects.toThrow("disposed");
         expect(emit).not.toHaveBeenCalled();
     });
-    it("refuses package callers for contracts whose providers refuse packages", async () => {
+    it.each([
+        ["System App Updates", system_ids_1.appUpdatesContractId],
+        ["System Packages", system_ids_1.packagesContractId],
+        ["Device Operations", system_ids_1.deviceOperationsContractId],
+    ])("refuses to forward a package's call to %s", async (_name, contractId) => {
         const { transport, emit } = makeTransport();
         const packageContext = { callerPackageId: "package-a" };
-        expect(() => (0, index_1.createRemoteContractEndpoint)(makeRequest({ contractId: system_ids_1.appUpdatesContractId, context: packageContext }), () => transport)).toThrow("packages cannot call contract");
-        const operator = (0, index_1.createRemoteContractEndpoint)(makeRequest({ contractId: system_ids_1.appUpdatesContractId }), () => transport);
-        await expect(operator.handleCall({ ...toolCall, contractId: system_ids_1.appUpdatesContractId }, {})).resolves.toBe("pong");
+        expect(() => (0, index_1.createRemoteContractEndpoint)(makeRequest({ contractId, context: packageContext }), () => transport)).toThrow("packages cannot call system contract");
+        // A package endpoint for its own contract cannot be steered at a system contract.
         const packageTool = (0, index_1.createRemoteContractEndpoint)(makeRequest({ context: packageContext }), () => transport);
+        await expect(packageTool.handleCall({ ...toolCall, contractId }, packageContext)).rejects.toThrow("packages cannot call system contract");
+        expect(emit).not.toHaveBeenCalled();
+        // The user (no package) still reaches it, and the package still reaches its own contract.
+        const operator = (0, index_1.createRemoteContractEndpoint)(makeRequest({ contractId }), () => transport);
+        await expect(operator.handleCall({ ...toolCall, contractId }, {})).resolves.toBe("pong");
         await expect(packageTool.handleCall(toolCall, packageContext)).resolves.toBe("pong");
         expect(emit).toHaveBeenCalledTimes(2);
     });
@@ -65,34 +84,6 @@ describe("remote contract endpoint", () => {
         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");
     });
-    it("refuses package runTool forwarding that could invoke App Updates indirectly", async () => {
-        const { transport, emit } = makeTransport();
-        const packageContext = { callerPackageId: "package-a" };
-        const endpoint = (0, index_1.createRemoteContractEndpoint)(makeRequest({ contractId: system_ids_1.deviceOperationsContractId, context: packageContext }), () => transport);
-        for (const toolName of ["checkForUpdates", "installUpdateAndRestart"]) {
-            const call = {
-                ...toolCall,
-                contractId: system_ids_1.deviceOperationsContractId,
-                name: "runTool",
-                args: [
-                    {
-                        toolIdOrName: (0, index_1.deriveToolCatalogId)({
-                            contractId: system_ids_1.appUpdatesContractId,
-                            version: index_1.APP_UPDATES_CONTRACT_VERSION,
-                            toolName,
-                        }),
-                    },
-                ],
-            };
-            await expect(endpoint.handleCall(call, packageContext)).rejects.toThrow("packages cannot call Device Operations runTool");
-        }
-        expect(emit).not.toHaveBeenCalled();
-        // Read-only tools on the same cached package endpoint still work.
-        await expect(endpoint.handleCall({ ...toolCall, contractId: system_ids_1.deviceOperationsContractId, name: "getDeviceStatus" }, packageContext)).resolves.toBe("pong");
-        const operator = (0, index_1.createRemoteContractEndpoint)(makeRequest({ contractId: system_ids_1.deviceOperationsContractId }), () => transport);
-        await expect(operator.handleCall({ ...toolCall, contractId: system_ids_1.deviceOperationsContractId, name: "runTool" }, {})).resolves.toBe("pong");
-        expect(emit).toHaveBeenCalledTimes(2);
-    });
 });
 describe("resolveRemoteTargetEndpoint", () => {
     it("returns undefined for local routes and for the local device itself", () => {

package/dist/contracts/__tests__/system-contracts.test.js

@@ -4,9 +4,12 @@ const system_ids_1 = require("../../system-ids");
 const utils_1 = require("../../utils");
 const contract_resolvers_1 = require("../contract-resolvers");
 const registry_1 = require("../registry");
+const host_shell_contract_1 = require("../system/host-shell-contract");
 const identity_contract_1 = require("../system/identity-contract");
+const packages_contract_1 = require("../system/packages-contract");
 const system_contracts_1 = require("../system-contracts");
 const tool_catalog_1 = require("../tool-catalog");
+const tool_catalog_service_1 = require("../tool-catalog-service");
 // Populate the catalog with built-in system contracts.
 require("../system");
 describe("system contract catalog", () => {
@@ -25,6 +28,7 @@ describe("system contract catalog", () => {
             system_ids_1.networkControlContractId,
             system_ids_1.toolAccessControlContractId,
             system_ids_1.toolCatalogContractId,
+            system_ids_1.packagesContractId,
         ]));
     });
     it("registers the Logs live resolver", async () => {
@@ -165,3 +169,79 @@ test("host and desktop workflow members are present with workflow-only policy",
             expect(definition?.tools.find((tool) => tool.name === name)?.requiresWorkflowRun).toBe(true);
     }
 });
+test("System Packages is remote only for Self and never workflow-invocable", () => {
+    const registry = new registry_1.ContractRegistry();
+    (0, system_contracts_1.installSystemContracts)(registry);
+    const definition = registry.resolve(system_ids_1.packagesContractId, 1);
+    expect(definition?.name).toBe("System Packages");
+    expect(registry.getProviderPackageId(system_ids_1.packagesContractId, 1)).toBe(system_ids_1.peersSystemPackageId);
+    expect((0, contract_resolvers_1.isLocalOnlyContractId)(system_ids_1.packagesContractId)).toBe(false);
+    for (const tool of definition?.tools ?? []) {
+        expect(tool.remoteAccessLevel).toBeUndefined();
+        expect((0, tool_catalog_service_1.isWorkflowInvocableTarget)({
+            contractId: system_ids_1.packagesContractId,
+            version: 1,
+            toolName: tool.name,
+        })).toBe(false);
+    }
+});
+test("System Host Shell is remote only for Self and never workflow-invocable", () => {
+    const registry = new registry_1.ContractRegistry();
+    (0, system_contracts_1.installSystemContracts)(registry);
+    const definition = registry.resolve(system_ids_1.hostShellContractId, 1);
+    expect(definition?.name).toBe("System Host Shell");
+    expect(registry.getProviderPackageId(system_ids_1.hostShellContractId, 1)).toBe(system_ids_1.peersSystemPackageId);
+    expect((0, contract_resolvers_1.isLocalOnlyContractId)(system_ids_1.hostShellContractId)).toBe(false);
+    expect(definition?.tools.map((tool) => tool.name)).toContain("screenshot");
+    for (const tool of definition?.tools ?? []) {
+        expect(tool.remoteAccessLevel).toBeUndefined();
+        expect((0, tool_catalog_service_1.isWorkflowInvocableTarget)({
+            contractId: system_ids_1.hostShellContractId,
+            version: 1,
+            toolName: tool.name,
+        })).toBe(false);
+    }
+});
+it.each([
+    ["https://peers.app/docs", { kind: "browser", url: "https://peers.app/docs" }],
+    [" http://localhost:3000 ", { kind: "browser", url: "http://localhost:3000" }],
+    ["mailto:someone@example.com", { kind: "browser", url: "mailto:someone@example.com" }],
+    ["~/peers/packages", { kind: "path", path: "~/peers/packages" }],
+    ["/tmp/a b", { kind: "path", path: "/tmp/a b" }],
+    ["C:\\Users\\me", { kind: "path", path: "C:\\Users\\me" }],
+    ["relative/dir", { kind: "path", path: "relative/dir" }],
+])("open routes %p", (target, expected) => {
+    expect((0, host_shell_contract_1.classifyHostOpenTarget)(target)).toEqual(expected);
+});
+it.each([
+    "file:///etc/passwd",
+    "javascript:alert(1)",
+    "vscode://file/x",
+    "smb://host/share",
+    "",
+])("open refuses %p", (target) => {
+    expect(() => (0, host_shell_contract_1.classifyHostOpenTarget)(target)).toThrow(/open (refuses|requires)/);
+});
+it.each([
+    [undefined, ["beta", "stable"]],
+    ["", ["beta", "stable"]],
+    ["dev", ["beta", "stable"]],
+    ["beta", ["stable"]],
+    ["stable", []],
+    ["nightly", []],
+])("promotion targets for %p are %p", (tag, targets) => {
+    expect((0, packages_contract_1.packageVersionPromotionTargets)(tag)).toEqual(targets);
+});
+it.each([
+    ["https://github.com/peers-app/x.git", true],
+    ["http://host/x", true],
+    ["git@github.com:peers-app/x", true],
+    ["  git@github.com:peers-app/x.git", true],
+    ["git@notes", false],
+    ["../x.git", false],
+    ["/abs/x.git", false],
+    ["My Package", false],
+    ["00mvdhk66tdqrj3hy0bacmj32", false],
+])("routes %p to clonePackage: %p", (target, expected) => {
+    expect((0, packages_contract_1.isPackageRepositoryUrl)(target)).toBe(expected);
+});

package/dist/contracts/contract-resolvers.d.ts

@@ -100,7 +100,7 @@ export declare function isLocalOnlyContractId(contractId: string): boolean;
  * 2. The caller's keys must match a valid signed Users record known to the provider.
  * 3. A Self-trusted caller (the provider's own account, or an account granted exact
  *    `TrustLevel.Self`) keeps full access; an omitted data context selects the provider's
- *    personal context.
+ *    personal context, and a named one must be a group this device already has.
  * 4. Any other verified caller is treated as a **group member**: the call must name a
  *    group the provider belongs to, must be a tool run, the contract definition registered
  *    for that group must mark the tool with {@link IContractTool.remoteAccessLevel}, and

package/dist/contracts/contract-resolvers.js

@@ -239,7 +239,7 @@ function isLocalOnlyContractId(contractId) {
  * 2. The caller's keys must match a valid signed Users record known to the provider.
  * 3. A Self-trusted caller (the provider's own account, or an account granted exact
  *    `TrustLevel.Self`) keeps full access; an omitted data context selects the provider's
- *    personal context.
+ *    personal context, and a named one must be a group this device already has.
  * 4. Any other verified caller is treated as a **group member**: the call must name a
  *    group the provider belongs to, must be a tool run, the contract definition registered
  *    for that group must mark the tool with {@link IContractTool.remoteAccessLevel}, and
@@ -269,7 +269,8 @@ async function authorizeRemoteContractCall(call, userContext, remoteIdentity) {
                 callerUserId: remoteIdentity.userId,
                 localUserId: userContext.userId,
                 callerDeviceId: remoteIdentity.deviceId,
-                dataContext: userContext.getDataContext(dataContextId),
+                // Never create a context the caller names: only this device's own groups.
+                dataContext: getAuthorizedLocalDataContext(userContext, dataContextId),
             },
         };
     }

package/dist/contracts/create-local-consumer.d.ts

@@ -1,4 +1,4 @@
-import { type IContractConsumer, type IContractResolution } from "./contract-proxy";
+import { type IContractCallContext, type IContractConsumer, type IContractResolution } from "./contract-proxy";
 import type { IContractDefinition } from "./types";
 /**
  * Build a same-process contract consumer wired to a live provider resolution.
@@ -9,4 +9,5 @@ import type { IContractDefinition } from "./types";
  */
 export declare function createLocalContractConsumer(definition: IContractDefinition, resolution: IContractResolution, opts?: {
     dataContextId?: string;
+    context?: IContractCallContext;
 }): IContractConsumer;

package/dist/contracts/create-local-consumer.js

@@ -12,7 +12,7 @@ const contract_transport_1 = require("./contract-transport");
  */
 function createLocalContractConsumer(definition, resolution, opts) {
     const [consumerTransport, providerTransport] = (0, contract_transport_1.inProcessTransportPair)();
-    (0, contract_proxy_1.createContractProviderSession)(resolution, providerTransport);
+    (0, contract_proxy_1.createContractProviderSession)(resolution, providerTransport, { context: opts?.context });
     return (0, contract_proxy_1.createContractConsumer)(definition, consumerTransport, {
         dataContextId: opts?.dataContextId,
     });

package/dist/contracts/index.d.ts

@@ -17,6 +17,7 @@ export * from "./system/app-updates-contract";
 export { CONTRACT_CATALOG_VERSION, contractCatalogProviderPackageId, getContractCatalogDefinition, type IContractCatalogConsumer, type IContractProviderInfo, type IListContractProvidersInput, } from "./system/contract-catalog-contract";
 export * from "./system/desktop-tools-contract";
 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 * from "./system/host-shell-contract";
 export * from "./system/host-tools-contract";
 export { getHttpContractDefinition, HTTP_CONTRACT_VERSION, HTTP_DEFAULT_TIMEOUT_MS, HTTP_MAX_BODY_BYTES, HTTP_MAX_TIMEOUT_MS, httpProviderPackageId, type IHttpCancelInput, type IHttpConsumer, type IHttpCredentialInfo, type IHttpMultipartPart, type IHttpPolicyInfo, type IHttpRequestInput, type IHttpRequestResult, } from "./system/http-contract";
 export { getIdentityContractDefinition, IDENTITY_CONTRACT_VERSION, type IIdentityConsumer, type IIdentityKeyInfo, type IIdentityRegistryKey, type IIdentityRotateKeyInput, type IIdentityRotateKeyResult, type IIdentitySessionInfo, } from "./system/identity-contract";
@@ -24,6 +25,7 @@ export { getInvitesContractDefinition, type IAcceptInviteResult, type ICreatedIn
 export { getLocalFoldersContractDefinition, type ILocalFolderAssembleInput, type ILocalFolderAssembleResult, type ILocalFolderChange, type ILocalFolderChangedEvent, type ILocalFolderEntry, type ILocalFolderFileBlocks, type ILocalFolderFileBlocksInput, type ILocalFolderGrantInfo, type ILocalFolderIndexInput, type ILocalFolderIndexResult, type ILocalFolderJobFinishedEvent, type ILocalFolderJobHandle, type ILocalFolderJobInfo, type ILocalFolderJobProgressEvent, type ILocalFolderListInput, type ILocalFolderManifestBlock, type ILocalFolderMoveInput, type ILocalFolderPathInput, type ILocalFolderPurgeTrashInput, type ILocalFolderReadRangeInput, type ILocalFolderReadRangeResult, type ILocalFolderRequestGrantInput, type ILocalFolderStatInput, LOCAL_FOLDERS_ASSEMBLE_STALL_MS, LOCAL_FOLDERS_CHUNK_AVG, LOCAL_FOLDERS_CHUNK_MAX, LOCAL_FOLDERS_CHUNK_MIN, LOCAL_FOLDERS_CONTRACT_VERSION, LOCAL_FOLDERS_GETBLOCKS_MAX_BLOCKS, LOCAL_FOLDERS_GETBLOCKS_MAX_BYTES, LOCAL_FOLDERS_HAVE_BATCH, LOCAL_FOLDERS_JOB_TTL_MS, LOCAL_FOLDERS_READ_RANGE_MAX, LOCAL_FOLDERS_RESERVED_DIR, type LocalFolderChangeKind, type LocalFolderEntryKind, type LocalFolderJobKind, type LocalFolderMode, localFoldersProviderPackageId, } from "./system/local-folders-contract";
 export { getLogsContractDefinition, type ILogsConsumer, LOGS_CONTRACT_VERSION, resolveLogsContract, } from "./system/logs-contract";
 export * from "./system/network-contracts";
+export * from "./system/packages-contract";
 export { getSchedulerContractDefinition, type IScheduleInfo, type IScheduleInput, type ISchedulerConsumer, SCHEDULER_CONTRACT_VERSION, SCHEDULER_MAX_DELAY_MS, schedulerProviderPackageId, } from "./system/scheduler-contract";
 export { getToolAccessControlContractDefinition, type IToolAccessControlConsumer, TOOL_ACCESS_CONTROL_CONTRACT_VERSION, } from "./system/tool-access-control-contract";
 export * from "./system/tool-catalog-contract";

package/dist/contracts/index.js

@@ -98,6 +98,7 @@ Object.defineProperty(exports, "DEVICE_OPERATIONS_MAX_TOOLS", { enumerable: true
 Object.defineProperty(exports, "deviceOperationsProviderPackageId", { enumerable: true, get: function () { return device_operations_contract_1.deviceOperationsProviderPackageId; } });
 Object.defineProperty(exports, "deviceOperationsToolIds", { enumerable: true, get: function () { return device_operations_contract_1.deviceOperationsToolIds; } });
 Object.defineProperty(exports, "getDeviceOperationsContractDefinition", { enumerable: true, get: function () { return device_operations_contract_1.getDeviceOperationsContractDefinition; } });
+__exportStar(require("./system/host-shell-contract"), exports);
 __exportStar(require("./system/host-tools-contract"), exports);
 var http_contract_1 = require("./system/http-contract");
 Object.defineProperty(exports, "getHttpContractDefinition", { enumerable: true, get: function () { return http_contract_1.getHttpContractDefinition; } });
@@ -131,6 +132,7 @@ Object.defineProperty(exports, "getLogsContractDefinition", { enumerable: true,
 Object.defineProperty(exports, "LOGS_CONTRACT_VERSION", { enumerable: true, get: function () { return logs_contract_1.LOGS_CONTRACT_VERSION; } });
 Object.defineProperty(exports, "resolveLogsContract", { enumerable: true, get: function () { return logs_contract_1.resolveLogsContract; } });
 __exportStar(require("./system/network-contracts"), exports);
+__exportStar(require("./system/packages-contract"), exports);
 var scheduler_contract_1 = require("./system/scheduler-contract");
 Object.defineProperty(exports, "getSchedulerContractDefinition", { enumerable: true, get: function () { return scheduler_contract_1.getSchedulerContractDefinition; } });
 Object.defineProperty(exports, "SCHEDULER_CONTRACT_VERSION", { enumerable: true, get: function () { return scheduler_contract_1.SCHEDULER_CONTRACT_VERSION; } });

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

@@ -61,12 +61,12 @@ export declare function resolveRemoteTargetEndpoint(request: IContractProviderEn
  * 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. Package callers cannot
- * reach contracts whose providers refuse packages, such as System App Updates, or the
- * Device Operations `runTool` wrapper that could invoke them indirectly.
+ * reach system contracts on another device (System Packages, App Updates, Device
+ * Operations, …): the target would see only this device, acting for the user.
  *
  * @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, the route lacks a target device or data context, or
- *   a package targets a contract that refuses package callers.
+ *   a package targets a system contract.
  */
 export declare function createRemoteContractEndpoint(request: IContractProviderEndpointRequest, factory?: RemoteContractTransportFactory | undefined): IContractProviderEndpoint;

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

@@ -4,14 +4,18 @@ exports.setRemoteContractTransportFactory = setRemoteContractTransportFactory;
 exports.getRemoteContractTransportFactory = getRemoteContractTransportFactory;
 exports.resolveRemoteTargetEndpoint = resolveRemoteTargetEndpoint;
 exports.createRemoteContractEndpoint = createRemoteContractEndpoint;
-const system_ids_1 = require("../system-ids");
 const contract_transport_1 = require("./contract-transport");
+const system_contracts_1 = require("./system-contracts");
 /**
- * Contracts whose providers refuse package callers. A forwarded call reaches the target
- * signed by this device alone, so the target cannot tell that a package made it; the
- * forwarding host refuses instead.
+ * Whether this host refuses to forward a package's call to another device. A forwarded
+ * call reaches the target signed by this device alone, as the user, so the target cannot
+ * tell that a package made it and would grant it the user's full Self authority. Packages
+ * may still call their own (and other packages') contracts there; system contracts, whose
+ * tools administer the device, are refused here instead.
  */
-const packageRefusedRemoteContractIds = new Set([system_ids_1.appUpdatesContractId]);
+function refusesForwardedPackageCall(context, contractId) {
+    return !!context?.callerPackageId && (0, system_contracts_1.isSystemContractId)(contractId);
+}
 const factoriesByUserContext = new WeakMap();
 let defaultFactory;
 /**
@@ -66,21 +70,21 @@ function resolveRemoteTargetEndpoint(request, host) {
  * 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. Package callers cannot
- * reach contracts whose providers refuse packages, such as System App Updates, or the
- * Device Operations `runTool` wrapper that could invoke them indirectly.
+ * reach system contracts on another device (System Packages, App Updates, Device
+ * Operations, …): the target would see only this device, acting for the user.
  *
  * @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, the route lacks a target device or data context, or
- *   a package targets a contract that refuses package callers.
+ *   a package targets a system contract.
  */
 function createRemoteContractEndpoint(request, factory = getRemoteContractTransportFactory()) {
     const { targetDeviceId, dataContextId } = request;
     if (!targetDeviceId) {
         throw new Error("Remote contract endpoint requires a target device id");
     }
-    if (request.context?.callerPackageId && packageRefusedRemoteContractIds.has(request.contractId)) {
-        throw new Error(`Permission denied: packages cannot call contract ${request.contractId} on another device`);
+    if (refusesForwardedPackageCall(request.context, request.contractId)) {
+        throw new Error(`Permission denied: packages cannot call system contract ${request.contractId} on another device`);
     }
     if (!dataContextId) {
         throw new Error("Remote contract endpoint requires an authorized data context id");
@@ -88,7 +92,6 @@ function createRemoteContractEndpoint(request, factory = getRemoteContractTransp
     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) {
@@ -98,14 +101,13 @@ function createRemoteContractEndpoint(request, factory = getRemoteContractTransp
             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`));
             }
-            // runTool refuses packages locally, but the target cannot recover their identity
-            // after forwarding. Without this gate it could invoke App Updates on their behalf.
-            if (request.context.callerPackageId &&
-                request.contractId === system_ids_1.deviceOperationsContractId &&
-                call.name === "runTool") {
-                return Promise.reject(new Error("Permission denied: packages cannot call Device Operations runTool on another device"));
+            if (refusesForwardedPackageCall(request.context, call.contractId)) {
+                return Promise.reject(new Error(`Permission denied: packages cannot call system contract ${call.contractId} on another device`));
             }
             const { targetDeviceId: _stripped, ...outbound } = call;
+            // Endpoints are cached longer than connections. Select the current route for each
+            // call, without replaying a call whose previous transport may have executed it.
+            const transport = factory({ deviceId: targetDeviceId, dataContextId });
             return transport.emit(contract_transport_1.CONTRACT_REQUEST_CHANNEL, { ...outbound, dataContextId });
         },
         dispose() {

package/dist/contracts/system/host-shell-contract.d.ts

@@ -0,0 +1,191 @@
+import type { IContractConsumerBase } from "../contract-proxy";
+import type { IContractDefinition } from "../types";
+/** Version of the built-in System Host Shell contract. */
+export declare const HOST_SHELL_CONTRACT_VERSION = 1;
+/** What the host behind a System Host Shell provider can do. Unsupported tools throw. */
+export interface IHostShellCapabilities {
+    /** The host has a UI window it can inspect, click, type into, scroll, and reload. */
+    ui: boolean;
+    /** The host can capture its UI window as an image. */
+    screenshot: boolean;
+    /** The host can quit and restart itself. */
+    appLifecycle: boolean;
+    /** The host can open web links and local paths (`open`). */
+    open: boolean;
+    /** The host can open a folder in a code editor (`openInEditor`). */
+    editor: boolean;
+    /** The host can copy a variable's value to the system clipboard. */
+    clipboard: boolean;
+}
+/** Serializable description of one interactive UI element. */
+export interface IUIElement {
+    /** Lower-case tag name. */
+    tag: string;
+    /** Visible text or accessible label. */
+    text?: string;
+    /** CSS selector that finds this element again (for `clickUI`, `setUIText`, `scrollUI`). */
+    selector: string;
+    /** Input type, for inputs. */
+    type?: string;
+    /** Current value, for inputs (never for passwords). */
+    value?: string;
+    /** Placeholder, for inputs. */
+    placeholder?: string;
+    /** Target, for links. */
+    href?: string;
+    /** Whether the element is disabled. */
+    disabled?: boolean;
+    /** Position and size in CSS pixels, when requested. */
+    rect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/** Snapshot of the UI window: location, visible text, and interactive elements. */
+export interface IUIState {
+    /** Page URL. */
+    url: string;
+    /** Document title. */
+    title: string;
+    /** Current in-app route, when known. */
+    route?: string;
+    /** Visible text content. */
+    text: string;
+    /** Interactive elements. */
+    elements: IUIElement[];
+}
+/** Outcome of a UI action (`clickUI`, `setUIText`, `scrollUI`). */
+export interface IUIActionResult {
+    /** Whether the action was performed. */
+    success: boolean;
+    /** Why it was not, e.g. no element matched the selector. */
+    error?: string;
+}
+/** Direction for `scrollUI`. */
+export type UIScrollDirection = "up" | "down" | "left" | "right";
+/** Input for `scrollUI`: scroll an element (or the page) by a direction or offsets. */
+export interface IUIScrollInput {
+    /** Element to scroll; the page when omitted. */
+    selector?: string;
+    /** Horizontal offset in pixels. */
+    x?: number;
+    /** Vertical offset in pixels. */
+    y?: number;
+    /** Direction to scroll by {@link amount}, instead of offsets. */
+    direction?: UIScrollDirection;
+    /** Pixels to scroll in {@link direction} (default 300). */
+    amount?: number;
+}
+/** Image format for `screenshot`. */
+export type ScreenshotFormat = "png" | "jpeg";
+/** A captured image of the UI window. */
+export interface IHostScreenshot {
+    /** `image/png` or `image/jpeg`. */
+    mimeType: string;
+    /** Width in pixels. */
+    width: number;
+    /** Height in pixels. */
+    height: number;
+    /** Base64-encoded image bytes. */
+    data: string;
+}
+/** How `open` handled its target. */
+export type HostOpenKind = "browser" | "path";
+/** Typed consumer proxy for System Host Shell v1. */
+export interface IHostShellConsumer extends IContractConsumerBase {
+    tools: {
+        /** Report what this host supports. */
+        getCapabilities(): Promise<{
+            capabilities: IHostShellCapabilities;
+        }>;
+        /** Return the UI window's location, visible text, and interactive elements. */
+        inspectUI(input?: {
+            includeRects?: boolean;
+        }): Promise<IUIState>;
+        /** Click the element matching a CSS selector. */
+        clickUI(input: {
+            selector: string;
+        }): Promise<IUIActionResult>;
+        /** Type text into the input matching a CSS selector. */
+        setUIText(input: {
+            selector: string;
+            text: string;
+            clear?: boolean;
+            pressEnter?: boolean;
+        }): Promise<IUIActionResult>;
+        /** Scroll an element or the page. */
+        scrollUI(input: IUIScrollInput): Promise<IUIActionResult>;
+        /** Reload the UI window. */
+        reloadUI(input?: {
+            ignoreCache?: boolean;
+        }): Promise<{
+            reloaded: boolean;
+        }>;
+        /** Capture the UI window as an image. */
+        screenshot(input?: {
+            format?: ScreenshotFormat;
+            maxWidth?: number;
+        }): Promise<IHostScreenshot>;
+        /** Quit the app. */
+        quitApp(): Promise<{
+            quitting: boolean;
+        }>;
+        /** Restart the app. */
+        restartApp(): Promise<{
+            restarting: boolean;
+        }>;
+        /** Open a web link in the browser, or a local file or folder with the OS. */
+        open(input: {
+            target: string;
+        }): Promise<{
+            opened: HostOpenKind;
+        }>;
+        /** Open a folder in a code editor, falling back to the OS. */
+        openInEditor(input: {
+            path: string;
+        }): Promise<{
+            editor: string;
+        }>;
+        /** Copy a persistent variable's value to the system clipboard. */
+        copyVariableToClipboard(input: {
+            persistentVarId: string;
+            groupId?: string;
+        }): Promise<{
+            copied: boolean;
+            clearsAfterMs?: number;
+        }>;
+    };
+}
+/** URL schemes `open` hands to the browser or mail client; any other scheme is refused. */
+export declare const HOST_OPEN_URL_SCHEMES: readonly string[];
+/** Where `open` sends a target: a URL for the browser, or a local path for the OS. */
+export type HostOpenTarget = {
+    kind: "browser";
+    url: string;
+} | {
+    kind: "path";
+    path: string;
+};
+/**
+ * Decide how `open` handles a target. `http`, `https`, and `mailto` links go to the browser;
+ * any other URL scheme (`file:`, `javascript:`, custom app schemes, …) is refused; everything
+ * else is a local path (`~` is expanded by the host). Windows drive paths are paths.
+ *
+ * @param target - What the caller asked to open.
+ * @throws When the target is empty or uses a scheme that is not allowed.
+ */
+export declare function classifyHostOpenTarget(target: string): HostOpenTarget;
+/**
+ * Return the System Host Shell contract shape.
+ *
+ * Tools carry no `remoteAccessLevel`, so only callers this device trusts as `Self` (the
+ * user's own devices and users explicitly granted Self) can reach them remotely; group
+ * members, Admins included, are refused. Package code and workflows are refused everywhere.
+ * `quitApp` and `restartApp` from another device also need the device's "Allow my other
+ * devices to update and restart this device" setting. Tools the host cannot perform throw
+ * `System Host Shell <tool> is not supported on this host (...)`; `getCapabilities` reports
+ * support up front.
+ */
+export declare function getHostShellContractDefinition(): IContractDefinition;