@peers-app/peers-sdk 0.23.10 → 0.23.12

package/dist/contracts/index.d.ts

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

package/dist/contracts/index.js

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

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

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

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

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

package/dist/contracts/types.d.ts

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

package/dist/data/tools.d.ts

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

package/dist/data/tools.js

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

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

@@ -1,4 +1,4 @@
-import type { IAlsoImplementsDeclaration, IConsumedContract, IContractDefinition, IContractObservable, IContractTool } from "../contracts/types";
+import type { IAlsoImplementsDeclaration, IConsumedContract, IContractDefinition, IContractEvent, IContractObservable, IContractTool } from "../contracts/types";
 import { type PersistentVarScope } from "../data/persistent-var-identity";
 import type { IAppNav } from "../types/app-nav";
 import { type IField } from "../types/field-type";
@@ -20,16 +20,21 @@ export interface IIsolatedContractToolRef {
 /**
  * Tool advertised on an isolated provided contract.
  *
- * Shape matches {@link IContractTool}. `suggestedAccessLevel` is a package
- * hint only — the host keeps the effective level at Self until an
- * administrator approves it.
+ * Shape matches {@link IContractTool}. `suggestedAccessLevel` is the default
+ * effective level until install-time approval exists and calls `approveTool`.
+ * Omit it to keep the fail-closed Self default.
  */
 export interface IIsolatedContractTool extends Omit<IContractTool, "inputFields" | "outputFields"> {
     /** Defaults to `[]` during validation when omitted. */
     inputFields?: IField[];
     /** Defaults to `[]` during validation when omitted. */
     outputFields?: IField[];
-    /** Package suggestion only. Effective level stays Self until approved. */
+    /**
+     * Default effective access level for this tool.
+     *
+     * Used until an administrator explicitly approves the tool at install time.
+     * Omit to keep the fail-closed Self default.
+     */
     suggestedAccessLevel?: number;
 }
 /**
@@ -60,6 +65,18 @@ export interface IIsolatedContractPersistentVarBinding {
 export interface IIsolatedContractObservable extends IContractObservable {
     persistentVar: IIsolatedContractPersistentVarBinding;
 }
+/**
+ * Event an isolated provider may emit from an active tool invocation.
+ *
+ * Shape matches {@link IContractEvent}. `payloadFields` defaults to `[]`
+ * during validation when omitted. Events are host-owned: the worker emits via
+ * `emitContractEvent`, and local consumers subscribe through the contract
+ * proxy. Events are fire-and-forget (no replay) and local-only in this slice.
+ */
+export interface IIsolatedContractEvent extends Omit<IContractEvent, "payloadFields"> {
+    /** Defaults to `[]` during validation when omitted. */
+    payloadFields?: IField[];
+}
 /** Contract this package implements and serves from its isolated worker. */
 export interface IIsolatedProvidedContract {
     contractId: string;
@@ -71,6 +88,8 @@ export interface IIsolatedProvidedContract {
     tables?: IIsolatedContractTableRef[];
     /** Pvar-backed observable values exposed to consumers. */
     observables?: IIsolatedContractObservable[];
+    /** Events the worker may emit during an active invocation. */
+    events?: IIsolatedContractEvent[];
     /** Older contract versions this provider shape also satisfies. */
     alsoImplements?: IAlsoImplementsDeclaration[];
 }
@@ -132,6 +151,8 @@ export declare const ISOLATED_CONSUME_HOST_MEMBER = "contract.consume";
 export declare const ISOLATED_TABLE_HOST_MEMBER = "package.table";
 /** Host-contract member guests use to read or write package-prefixed pvars. */
 export declare const ISOLATED_PERSISTENT_VAR_HOST_MEMBER = "package.pvar";
+/** Host-contract member guests use to emit a provided-contract event. */
+export declare const ISOLATED_EVENT_HOST_MEMBER = "contract.emit";
 /**
  * True when `bundle` starts with {@link ISOLATED_PACKAGE_MAGIC}.
  *
@@ -210,6 +231,24 @@ export declare function findProvidedContractTable(provides: IIsolatedProvidedCon
  * @param observableName Public observable name.
  */
 export declare function findProvidedContractObservable(provides: IIsolatedProvidedContract[], contractId: string, version: number, observableName: string): IIsolatedContractObservable | undefined;
+/**
+ * Return a declared event from a provided contract.
+ *
+ * @param provides Provided contracts from the manifest.
+ * @param contractId Target contract ID.
+ * @param version Target contract version.
+ * @param eventName Event name on that contract.
+ */
+export declare function findProvidedContractEvent(provides: IIsolatedProvidedContract[], contractId: string, version: number, eventName: string): IIsolatedContractEvent | undefined;
+/**
+ * True when the package advertises this event on a provided contract.
+ *
+ * @param provides - Provided contracts from the manifest.
+ * @param contractId - Target contract id.
+ * @param version - Target contract version.
+ * @param eventName - Event name on that contract.
+ */
+export declare function packageProvidesEvent(provides: IIsolatedProvidedContract[], contractId: string, version: number, eventName: string): boolean;
 /**
  * True when the package declares a private table.
  *

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ISOLATED_PERSISTENT_VAR_HOST_MEMBER = exports.ISOLATED_TABLE_HOST_MEMBER = exports.ISOLATED_CONSUME_HOST_MEMBER = exports.ISOLATED_PACKAGE_MAGIC = void 0;
+exports.ISOLATED_EVENT_HOST_MEMBER = exports.ISOLATED_PERSISTENT_VAR_HOST_MEMBER = exports.ISOLATED_TABLE_HOST_MEMBER = exports.ISOLATED_CONSUME_HOST_MEMBER = exports.ISOLATED_PACKAGE_MAGIC = void 0;
 exports.looksLikeIsolatedPackageArtifact = looksLikeIsolatedPackageArtifact;
 exports.validateIsolatedPackageArtifact = validateIsolatedPackageArtifact;
 exports.parseIsolatedPackageArtifact = parseIsolatedPackageArtifact;
@@ -10,6 +10,8 @@ exports.packageDeclaresConsume = packageDeclaresConsume;
 exports.packageProvidesTool = packageProvidesTool;
 exports.findProvidedContractTable = findProvidedContractTable;
 exports.findProvidedContractObservable = findProvidedContractObservable;
+exports.findProvidedContractEvent = findProvidedContractEvent;
+exports.packageProvidesEvent = packageProvidesEvent;
 exports.packageProvidesTable = packageProvidesTable;
 exports.findPackageTable = findPackageTable;
 exports.toConsumedContracts = toConsumedContracts;
@@ -29,6 +31,8 @@ exports.ISOLATED_CONSUME_HOST_MEMBER = "contract.consume";
 exports.ISOLATED_TABLE_HOST_MEMBER = "package.table";
 /** Host-contract member guests use to read or write package-prefixed pvars. */
 exports.ISOLATED_PERSISTENT_VAR_HOST_MEMBER = "package.pvar";
+/** Host-contract member guests use to emit a provided-contract event. */
+exports.ISOLATED_EVENT_HOST_MEMBER = "contract.emit";
 const FIELD_TYPES = new Set(Object.values(field_type_1.FieldType));
 const OBSERVABLE_FIELD_TYPES = new Set([
     field_type_1.FieldType.id,
@@ -209,6 +213,7 @@ function validateProvidedContract(contract, index, packageTables) {
         "tools",
         "tables",
         "observables",
+        "events",
         "alsoImplements",
     ], label);
     assertPeerId(contract.contractId, `${label}.contractId`);
@@ -228,7 +233,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 +260,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 = [];
@@ -325,7 +344,36 @@ function validateProvidedContract(contract, index, packageTables) {
         pvarBindings.add(bindingKey);
         validateObservableDefault(binding.defaultValue, observable.valueType, `${observableLabel}.persistentVar.defaultValue`);
     }
-    if (contract.tools.length + contract.tables.length + contract.observables.length === 0) {
+    if (contract.events === undefined) {
+        contract.events = [];
+    }
+    if (!Array.isArray(contract.events)) {
+        throw new Error(`${label}.events must be an array`);
+    }
+    const eventNames = new Set();
+    for (const [eventIndex, event] of contract.events.entries()) {
+        const eventLabel = `${label}.events[${eventIndex}]`;
+        if (!event || typeof event !== "object" || Array.isArray(event)) {
+            throw new Error(`${eventLabel} must be an object`);
+        }
+        assertOnlyKeys(event, ["name", "description", "payloadFields"], eventLabel);
+        if (typeof event.name !== "string" || event.name.trim() === "") {
+            throw new Error(`${eventLabel}.name is required`);
+        }
+        if (eventNames.has(event.name)) {
+            throw new Error(`${label} declares duplicate event "${event.name}"`);
+        }
+        eventNames.add(event.name);
+        if (typeof event.description !== "string") {
+            throw new Error(`${eventLabel}.description is required`);
+        }
+        event.payloadFields = validateFields(event.payloadFields, `${eventLabel}.payloadFields`);
+    }
+    if (contract.tools.length +
+        contract.tables.length +
+        contract.observables.length +
+        contract.events.length ===
+        0) {
         throw new Error(`${label} must declare at least one contract member`);
     }
     if (contract.alsoImplements === undefined) {
@@ -530,6 +578,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);
@@ -549,6 +598,11 @@ function isolatedContractToDefinition(contract, packageTables) {
         valueType: observable.valueType,
         writable: observable.writable,
     }));
+    const events = (contract.events ?? []).map((event) => ({
+        name: event.name,
+        description: event.description,
+        payloadFields: event.payloadFields ?? [],
+    }));
     return {
         contractId: contract.contractId,
         version: contract.version,
@@ -557,7 +611,7 @@ function isolatedContractToDefinition(contract, packageTables) {
         tables,
         tools,
         observables,
-        events: [],
+        events,
     };
 }
 /**
@@ -608,6 +662,30 @@ function findProvidedContractObservable(provides, contractId, version, observabl
         .find((contract) => contract.contractId === contractId && contract.version === version)
         ?.observables?.find((observable) => observable.name === observableName);
 }
+/**
+ * Return a declared event from a provided contract.
+ *
+ * @param provides Provided contracts from the manifest.
+ * @param contractId Target contract ID.
+ * @param version Target contract version.
+ * @param eventName Event name on that contract.
+ */
+function findProvidedContractEvent(provides, contractId, version, eventName) {
+    return provides
+        .find((contract) => contract.contractId === contractId && contract.version === version)
+        ?.events?.find((event) => event.name === eventName);
+}
+/**
+ * True when the package advertises this event on a provided contract.
+ *
+ * @param provides - Provided contracts from the manifest.
+ * @param contractId - Target contract id.
+ * @param version - Target contract version.
+ * @param eventName - Event name on that contract.
+ */
+function packageProvidesEvent(provides, contractId, version, eventName) {
+    return findProvidedContractEvent(provides, contractId, version, eventName) !== undefined;
+}
 /**
  * True when the package declares a private table.
  *