@peers-app/peers-sdk 0.20.0 → 0.20.1

package/dist/contracts/index.d.ts

@@ -8,6 +8,7 @@ export { Contracts, ContractsTable, contractsMetaData, contractsSchema, type ICo
 export { extractTableShape, extractToolShape, type IExtractableTableDef, type IExtractableToolInstance, setSchemaToFieldsFn, } from "./extract";
 export { PersistentContractRegistry } from "./persistent-registry";
 export { ContractRegistry } from "./registry";
+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, LOGS_CONTRACT_VERSION, resolveLogsContract, } from "./system/logs-contract";
 export type { IAlsoImplementsDeclaration, IConsumedContract, IContractDefinition, IContractEvent, IContractObservable, IContractTable, IContractTool, IPackageDefinitionResult, IResolvedContract, IValidationError, IValidationResult, } from "./types";
 export { contractKey } from "./types";

package/dist/contracts/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateProviderSatisfiesContract = exports.validateImmutability = exports.validateAlsoImplements = exports.contractKey = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.ContractRegistry = exports.PersistentContractRegistry = exports.setSchemaToFieldsFn = exports.extractToolShape = exports.extractTableShape = 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.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.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.setSchemaToFieldsFn = exports.extractToolShape = exports.extractTableShape = 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.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;
 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; } });
@@ -43,6 +43,15 @@ 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 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; } });
+Object.defineProperty(exports, "DEVICE_OPERATIONS_MAX_RESULT_BYTES", { enumerable: true, get: function () { return device_operations_contract_1.DEVICE_OPERATIONS_MAX_RESULT_BYTES; } });
+Object.defineProperty(exports, "DEVICE_OPERATIONS_MAX_ROWS", { enumerable: true, get: function () { return device_operations_contract_1.DEVICE_OPERATIONS_MAX_ROWS; } });
+Object.defineProperty(exports, "DEVICE_OPERATIONS_MAX_TOOLS", { enumerable: true, get: function () { return device_operations_contract_1.DEVICE_OPERATIONS_MAX_TOOLS; } });
+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; } });
 var logs_contract_1 = require("./system/logs-contract");
 Object.defineProperty(exports, "getLogsContractDefinition", { enumerable: true, get: function () { return logs_contract_1.getLogsContractDefinition; } });
 Object.defineProperty(exports, "LOGS_CONTRACT_VERSION", { enumerable: true, get: function () { return logs_contract_1.LOGS_CONTRACT_VERSION; } });

package/dist/contracts/system/device-operations-contract.d.ts

@@ -0,0 +1,72 @@
+import type { ITool } from "../../data/tools";
+import type { IContractDefinition } from "../types";
+/** Version of the built-in System Device Operations contract. */
+export declare const DEVICE_OPERATIONS_CONTRACT_VERSION = 1;
+/** Maximum SQL text accepted by the remote database operation. */
+export declare const DEVICE_OPERATIONS_MAX_QUERY_LENGTH = 20000;
+/** Maximum rows returned by one remote database operation. */
+export declare const DEVICE_OPERATIONS_MAX_ROWS = 500;
+/** Maximum serialized result size returned by one remote database operation. */
+export declare const DEVICE_OPERATIONS_MAX_RESULT_BYTES = 1000000;
+/** Maximum tools returned by one remote tool-list operation. */
+export declare const DEVICE_OPERATIONS_MAX_TOOLS = 100;
+/** Stable IDs for the live tools implementing System Device Operations v1. */
+export declare const deviceOperationsToolIds: {
+    readonly getDeviceStatus: "00mriijkhr4iptdefp4a7ifcq";
+    readonly queryDatabase: "00mriijkhrd54n33ey0omeejo";
+    readonly listTools: "00mriijkhr4fpyd70nyo5iqlq";
+    readonly getTool: "00mriijkhrid4wpf89i4ikvay";
+    readonly runTool: "00mriijkhrfequch2qaeoihol";
+};
+/** Portable operations supported by System Device Operations v1. */
+export type DeviceOperationCapability = "device-status" | "database-query" | "tool-list" | "tool-get" | "tool-run";
+/** Status and capability information returned by a remote device. */
+export interface IDeviceOperationStatus {
+    deviceId: string;
+    userId: string;
+    dataContextId: string;
+    contractVersion: number;
+    capabilities: DeviceOperationCapability[];
+    limits: {
+        maxQueryLength: number;
+        maxRows: number;
+        maxResultBytes: number;
+        maxTools: number;
+    };
+}
+/** Input for a bounded, read-only remote SQLite query. */
+export interface IDeviceDatabaseQueryInput {
+    query: string;
+}
+/** Serializable result from a bounded, read-only remote SQLite query. */
+export interface IDeviceDatabaseQueryResult {
+    columns: string[];
+    rows: unknown[][];
+    rowCount: number;
+    truncated: boolean;
+}
+/** Input for listing tools available in the selected data context. */
+export interface IDeviceToolListInput {
+    limit?: number;
+}
+/** Input for exact-ID, exact-name, or unambiguous-text tool lookup. */
+export interface IDeviceToolLookupInput {
+    toolIdOrName: string;
+}
+/** Input for running a tool on the remote device. */
+export interface IDeviceToolRunInput extends IDeviceToolLookupInput {
+    args?: Record<string, unknown>;
+    assistantId?: string;
+}
+/** Result of an unambiguous tool lookup, or `null` when no tool matched. */
+export type IDeviceToolLookupResult = ITool | null;
+/**
+ * Return the portable, owner-authorized device administration contract shape.
+ *
+ * The contract intentionally exposes explicit operations instead of arbitrary table,
+ * filesystem, shell, UI, or lifecycle access. Authorization is supplied by the verified
+ * connection host before the live resolver is invoked.
+ */
+export declare function getDeviceOperationsContractDefinition(): IContractDefinition;
+/** Package ID used by live System Device Operations tool instances. */
+export declare const deviceOperationsProviderPackageId = "000peers0system0000000001";

package/dist/contracts/system/device-operations-contract.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deviceOperationsProviderPackageId = exports.deviceOperationsToolIds = exports.DEVICE_OPERATIONS_MAX_TOOLS = exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = exports.DEVICE_OPERATIONS_MAX_ROWS = exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = exports.DEVICE_OPERATIONS_CONTRACT_VERSION = void 0;
+exports.getDeviceOperationsContractDefinition = getDeviceOperationsContractDefinition;
+const system_ids_1 = require("../../system-ids");
+const field_type_1 = require("../../types/field-type");
+/** Version of the built-in System Device Operations contract. */
+exports.DEVICE_OPERATIONS_CONTRACT_VERSION = 1;
+/** Maximum SQL text accepted by the remote database operation. */
+exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = 20_000;
+/** Maximum rows returned by one remote database operation. */
+exports.DEVICE_OPERATIONS_MAX_ROWS = 500;
+/** Maximum serialized result size returned by one remote database operation. */
+exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = 1_000_000;
+/** Maximum tools returned by one remote tool-list operation. */
+exports.DEVICE_OPERATIONS_MAX_TOOLS = 100;
+/** Stable IDs for the live tools implementing System Device Operations v1. */
+exports.deviceOperationsToolIds = {
+    getDeviceStatus: "00mriijkhr4iptdefp4a7ifcq",
+    queryDatabase: "00mriijkhrd54n33ey0omeejo",
+    listTools: "00mriijkhr4fpyd70nyo5iqlq",
+    getTool: "00mriijkhrid4wpf89i4ikvay",
+    runTool: "00mriijkhrfequch2qaeoihol",
+};
+const field = (name, type, description, opts = {}) => ({ name, type, description, ...opts });
+let definition;
+/**
+ * Return the portable, owner-authorized device administration contract shape.
+ *
+ * The contract intentionally exposes explicit operations instead of arbitrary table,
+ * filesystem, shell, UI, or lifecycle access. Authorization is supplied by the verified
+ * connection host before the live resolver is invoked.
+ */
+function getDeviceOperationsContractDefinition() {
+    definition ??= {
+        contractId: system_ids_1.deviceOperationsContractId,
+        version: exports.DEVICE_OPERATIONS_CONTRACT_VERSION,
+        devTag: "dev",
+        name: "System Device Operations",
+        description: "Owner-authorized status, bounded read-only database, and installed-tool operations.",
+        tables: [],
+        tools: [
+            {
+                name: "getDeviceStatus",
+                usageDescription: "Return this device's identity, supported operations, and limits.",
+                inputFields: [],
+                outputFields: [
+                    field("deviceId", field_type_1.FieldType.id, "The provider device ID."),
+                    field("userId", field_type_1.FieldType.id, "The provider user ID."),
+                    field("dataContextId", field_type_1.FieldType.id, "The selected data context ID."),
+                    field("contractVersion", field_type_1.FieldType.number, "The supported contract version."),
+                    field("capabilities", field_type_1.FieldType.string, "Supported portable operations.", {
+                        isArray: true,
+                    }),
+                    field("limits", field_type_1.FieldType.object, "Provider-enforced request and result limits."),
+                ],
+            },
+            {
+                name: "queryDatabase",
+                usageDescription: "Run one bounded read-only SELECT or approved PRAGMA query.",
+                inputFields: [field("query", field_type_1.FieldType.string, "One read-only SQLite statement.")],
+                outputFields: [
+                    field("columns", field_type_1.FieldType.string, "Result column names.", { isArray: true }),
+                    field("rows", field_type_1.FieldType.any, "Serializable result rows.", { isArray: true }),
+                    field("rowCount", field_type_1.FieldType.number, "Number of returned rows."),
+                    field("truncated", field_type_1.FieldType.boolean, "Whether rows were omitted by provider limits."),
+                ],
+            },
+            {
+                name: "listTools",
+                usageDescription: "List installed tools in the selected data context.",
+                inputFields: [
+                    field("limit", field_type_1.FieldType.number, "Maximum tools to return.", { optional: true }),
+                ],
+                outputFields: [
+                    field("tools", field_type_1.FieldType.object, "Installed tool definitions.", { isArray: true }),
+                ],
+            },
+            {
+                name: "getTool",
+                usageDescription: "Resolve a tool by exact ID, exact name, or unambiguous text.",
+                inputFields: [
+                    field("toolIdOrName", field_type_1.FieldType.string, "Tool ID, exact name, or search text."),
+                ],
+                outputFields: [
+                    field("tool", field_type_1.FieldType.object, "The matching tool definition, or null.", {
+                        optional: true,
+                    }),
+                ],
+            },
+            {
+                name: "runTool",
+                usageDescription: "Resolve and run an installed tool in the selected data context.",
+                inputFields: [
+                    field("toolIdOrName", field_type_1.FieldType.string, "Tool ID, exact name, or search text."),
+                    field("args", field_type_1.FieldType.object, "Tool input arguments.", { optional: true }),
+                    field("assistantId", field_type_1.FieldType.id, "Optional assistant execution context.", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: [field("result", field_type_1.FieldType.any, "The tool execution result.")],
+            },
+        ],
+        observables: [],
+        events: [],
+    };
+    return definition;
+}
+/** Package ID used by live System Device Operations tool instances. */
+exports.deviceOperationsProviderPackageId = system_ids_1.peersSystemPackageId;

package/dist/data/assistants.d.ts

@@ -18,8 +18,8 @@ export declare const assistantSchema: z.ZodObject<{
     packageId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
 }, "strip", z.ZodTypeAny, {
     name: string;
-    createdAt: Date;
     assistantId: string;
+    createdAt: Date;
     assistantRunnerToolId: string;
     assistantRunnerConfig: {} & {
         [k: string]: any;
@@ -42,10 +42,10 @@ export declare const assistantSchema: z.ZodObject<{
     toolInclusionStrategy?: ToolInclusionStrategy | undefined;
 }>;
 export type IAssistant = z.infer<typeof assistantSchema>;
-export declare function Assistants(dataContext?: DataContext): import("./orm").Table<{
+export declare function Assistants(dataContext?: DataContext): import("..").Table<{
     name: string;
-    createdAt: Date;
     assistantId: string;
+    createdAt: Date;
     assistantRunnerToolId: string;
     assistantRunnerConfig: {} & {
         [k: string]: any;
@@ -68,8 +68,8 @@ export declare const userPrimaryAssistantVar: import("./persistent-vars").Persis
 export declare const groupPrimaryAssistantVar: import("./persistent-vars").PersistentVar<string | undefined>;
 export declare const getPrimaryAssistant: (dataContext?: DataContext) => Promise<{
     name: string;
-    createdAt: Date;
     assistantId: string;
+    createdAt: Date;
     assistantRunnerToolId: string;
     assistantRunnerConfig: {} & {
         [k: string]: any;

package/dist/data/channels.d.ts

@@ -20,7 +20,7 @@ export declare const channelSchema: z.ZodObject<{
     owningGroupId: string;
 }>;
 export type IChannel = z.infer<typeof channelSchema>;
-export declare function Channels(dataContext?: DataContext): import("./orm").Table<{
+export declare function Channels(dataContext?: DataContext): import("..").Table<{
     name: string;
     description: string;
     createdAt: Date;

package/dist/data/devices.d.ts

@@ -38,7 +38,7 @@ export interface IDeviceHandshake extends IDeviceInfo {
     serverAddress: string;
     timestamp: number;
 }
-export declare function Devices(dataContext?: DataContext): import("./orm").Table<{
+export declare function Devices(dataContext?: DataContext): import("..").Table<{
     userId: string;
     deviceId: string;
     firstSeen: Date;

package/dist/data/embeddings.d.ts

@@ -34,7 +34,7 @@ export declare const embeddingSchema: z.ZodObject<{
     embeddingType: string;
 }>;
 export type IEmbedding = z.infer<typeof embeddingSchema>;
-export declare function Embeddings(dataContext?: DataContext): import("./orm").Table<{
+export declare function Embeddings(dataContext?: DataContext): import("..").Table<{
     metadata: {
         fkId?: string | undefined;
     } & {

package/dist/data/group-secret.d.ts

@@ -0,0 +1,21 @@
+import type { DataContext } from "../context/data-context";
+import { type IPublicKeys, type IPublicPrivateKeys } from "../keys";
+import { type IPersistentVar } from "./persistent-vars";
+/** Prefix used for each group's encrypted secret-key persistent variable. */
+export declare const GROUP_SECRET_KEY_PVAR_PREFIX = "groupSecretKey_";
+/** Return the personal-context persistent-variable name for a group secret key. */
+export declare function groupSecretKeyPvarName(groupId: string): string;
+/**
+ * Derive a group secret's public keys and verify they match the signed group record.
+ *
+ * @throws When the secret is malformed or derives different signing/box public keys.
+ */
+export declare function validateGroupSecretKey(secretKey: string, expected: IPublicKeys): IPublicPrivateKeys;
+/**
+ * Save a known-valid group secret in the user's personal context.
+ *
+ * Legacy random IDs and duplicate name rows are canonicalized before the replacement is
+ * encrypted and saved. The caller must supply the expected signed group public keys, so this
+ * function cannot silently install unrelated key material.
+ */
+export declare function saveGroupSecretKey(userDataContext: DataContext, groupId: string, secretKey: string, expected: IPublicKeys): Promise<IPersistentVar>;

package/dist/data/group-secret.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GROUP_SECRET_KEY_PVAR_PREFIX = void 0;
+exports.groupSecretKeyPvarName = groupSecretKeyPvarName;
+exports.validateGroupSecretKey = validateGroupSecretKey;
+exports.saveGroupSecretKey = saveGroupSecretKey;
+const keys_1 = require("../keys");
+const utils_1 = require("../utils");
+const persistent_vars_1 = require("./persistent-vars");
+/** Prefix used for each group's encrypted secret-key persistent variable. */
+exports.GROUP_SECRET_KEY_PVAR_PREFIX = "groupSecretKey_";
+/** Return the personal-context persistent-variable name for a group secret key. */
+function groupSecretKeyPvarName(groupId) {
+    return `${exports.GROUP_SECRET_KEY_PVAR_PREFIX}${groupId}`;
+}
+/**
+ * Derive a group secret's public keys and verify they match the signed group record.
+ *
+ * @throws When the secret is malformed or derives different signing/box public keys.
+ */
+function validateGroupSecretKey(secretKey, expected) {
+    const derived = (0, keys_1.hydrateKeys)(secretKey);
+    if (derived.publicKey !== expected.publicKey || derived.publicBoxKey !== expected.publicBoxKey) {
+        throw new Error("Group secret key does not match the group's public keys");
+    }
+    return derived;
+}
+/**
+ * Save a known-valid group secret in the user's personal context.
+ *
+ * Legacy random IDs and duplicate name rows are canonicalized before the replacement is
+ * encrypted and saved. The caller must supply the expected signed group public keys, so this
+ * function cannot silently install unrelated key material.
+ */
+async function saveGroupSecretKey(userDataContext, groupId, secretKey, expected) {
+    validateGroupSecretKey(secretKey, expected);
+    const name = groupSecretKeyPvarName(groupId);
+    const table = (0, persistent_vars_1.PersistentVars)(userDataContext);
+    const records = await table.list({ name });
+    let canonical = records.find((record) => record.persistentVarId === (0, utils_1.deterministicPvarId)(name));
+    for (const record of records) {
+        if (record !== canonical) {
+            canonical = await table.migrateLegacyId(record);
+        }
+    }
+    return table.save({
+        persistentVarId: canonical?.persistentVarId ?? "",
+        name,
+        scope: "groupUser",
+        isSecret: true,
+        value: { value: secretKey },
+    });
+}

package/dist/data/index.d.ts

@@ -8,6 +8,7 @@ export * from "./files";
 export * from "./group-member-roles";
 export * from "./group-members";
 export * from "./group-permissions";
+export * from "./group-secret";
 export * from "./group-share";
 export * from "./groups";
 export * from "./messages";

package/dist/data/index.js

@@ -24,6 +24,7 @@ __exportStar(require("./files"), exports);
 __exportStar(require("./group-member-roles"), exports);
 __exportStar(require("./group-members"), exports);
 __exportStar(require("./group-permissions"), exports);
+__exportStar(require("./group-secret"), exports);
 __exportStar(require("./group-share"), exports);
 __exportStar(require("./groups"), exports);
 __exportStar(require("./messages"), exports);

package/dist/data/messages.d.ts

@@ -35,7 +35,7 @@ export declare const messageSchema: z.ZodObject<{
     fileIds?: string[] | undefined;
 }>;
 export type IMessage = z.infer<typeof messageSchema>;
-export declare function Messages(dataContext?: DataContext): import("./orm").Table<{
+export declare function Messages(dataContext?: DataContext): import("..").Table<{
     message: string;
     userId: string;
     createdAt: Date;

package/dist/data/package-versions.d.ts

@@ -54,8 +54,8 @@ declare const schema: z.ZodObject<{
     version: string;
     signature: string;
     packageId: string;
-    createdBy: string;
     createdAt: string;
+    createdBy: string;
     packageVersionId: string;
     packageVersionHash: string;
     packageBundleFileId: string;
@@ -82,8 +82,8 @@ declare const schema: z.ZodObject<{
     version: string;
     signature: string;
     packageId: string;
-    createdBy: string;
     createdAt: string;
+    createdBy: string;
     packageVersionId: string;
     packageVersionHash: string;
     packageBundleFileId: string;

package/dist/data/peer-types.d.ts

@@ -91,7 +91,7 @@ declare const valueTypeSchema: z.ZodObject<{
     iconClass?: string | undefined;
 }>;
 export type IPeerType = z.infer<typeof valueTypeSchema>;
-export declare function PeerTypes(dataContext?: DataContext): import("./orm").Table<{
+export declare function PeerTypes(dataContext?: DataContext): import("..").Table<{
     name: string;
     schema: {
         type: import("./tools").IOSchemaType;

package/dist/data/persistent-vars.d.ts

@@ -52,20 +52,37 @@ declare const schema: z.ZodObject<{
     modifiedAt?: number | undefined;
     packageId?: string | undefined;
 }>;
+/** Table metadata for persisted observable variables. */
 export declare const persistentVarsMetaData: ITableMetaData;
+/** Stored record for one persistent variable. */
 export type IPersistentVar = z.infer<typeof schema>;
+/** Persistent-variable table with deterministic IDs and secret-value handling. */
 export declare class PersistentVarsTable extends Table<IPersistentVar> {
+    /** Insert a persistent variable through the canonical save path. */
     insert(persistentVar: IPersistentVar): Promise<IPersistentVar>;
+    /** Update a persistent variable through the canonical save path. */
     update(persistentVar: IPersistentVar): Promise<IPersistentVar>;
+    /** Save a variable, assigning its deterministic ID and encrypting new secret plaintext. */
     save(persistentVar: IPersistentVar, opts?: ISaveOptions): Promise<IPersistentVar>;
+    /**
+     * Replace a legacy random record ID without re-encrypting its already-stored value.
+     *
+     * Migration is storage-only: the value and modified timestamp are preserved. If the
+     * deterministic record already exists, it wins and the duplicate legacy row is removed.
+     */
+    migrateLegacyId(persistentVar: IPersistentVar): Promise<IPersistentVar>;
+    /** Return a stored variable's raw value by name. */
     getPersistentVarValue<T>(name: string): Promise<T | undefined>;
 }
+/** Return the persistent-variable table for a data context. */
 export declare function PersistentVars(dataContext?: DataContext): PersistentVarsTable;
+/** Reactive persistent value with an awaitable initial load and explicit deletion. */
 export type PersistentVar<T> = Observable<T> & {
     loadingPromise: Promise<PersistentVar<T>>;
     /** Delete the persistent variable from the database and reset to default value */
     delete: () => Promise<void>;
 };
+/** Resolve a persistent-variable record by name, preferring device scope. */
 export declare function getPersistentVar(name: string, dataContext?: DataContext): Promise<IPersistentVar | undefined>;
 interface IPersistentVarOptionsBase {
     scope?: "device" | "user" | "group" | "groupDevice" | "groupUser";

package/dist/data/persistent-vars.js

@@ -5,6 +5,40 @@
  * Tests for this module are located in peers-device/src/persistent-vars.test.ts
  * (requires SQLite which is not available in peers-sdk)
  */
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PersistentVarsTable = exports.persistentVarsMetaData = void 0;
 exports.PersistentVars = PersistentVars;
@@ -21,6 +55,7 @@ const observable_1 = require("../observable");
 const rpc_types_1 = require("../rpc-types");
 const zod_types_1 = require("../types/zod-types");
 const utils_1 = require("../utils");
+const decorators_1 = require("./orm/decorators");
 const table_1 = require("./orm/table");
 const table_definitions_system_1 = require("./orm/table-definitions.system");
 const types_1 = require("./orm/types");
@@ -44,6 +79,7 @@ const schema = zod_1.z.object({
         .optional()
         .describe("The package that owns this persistent variable, if any"),
 });
+/** Table metadata for persisted observable variables. */
 exports.persistentVarsMetaData = {
     name: "PersistentVars",
     description: "table to persist variables across sessions and devices",
@@ -52,46 +88,93 @@ exports.persistentVarsMetaData = {
     iconClassName: "bi bi-braces",
     indexes: [{ fields: ["name"], unique: true }],
 };
-class PersistentVarsTable extends table_1.Table {
-    async insert(persistentVar) {
-        return this.save(persistentVar);
-    }
-    async update(persistentVar) {
-        return this.save(persistentVar);
-    }
-    async save(persistentVar, opts) {
-        if (!persistentVar.persistentVarId) {
-            persistentVar.persistentVarId = (0, utils_1.deterministicPvarId)(persistentVar.name);
+/** Persistent-variable table with deterministic IDs and secret-value handling. */
+let PersistentVarsTable = (() => {
+    let _classSuper = table_1.Table;
+    let _instanceExtraInitializers = [];
+    let _migrateLegacyId_decorators;
+    return class PersistentVarsTable extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _migrateLegacyId_decorators = [(0, decorators_1.ProxyClientTableMethodCalls)()];
+            __esDecorate(this, null, _migrateLegacyId_decorators, { kind: "method", name: "migrateLegacyId", static: false, private: false, access: { has: obj => "migrateLegacyId" in obj, get: obj => obj.migrateLegacyId }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        /** Insert a persistent variable through the canonical save path. */
+        async insert(persistentVar) {
+            return this.save(persistentVar);
+        }
+        /** Update a persistent variable through the canonical save path. */
+        async update(persistentVar) {
+            return this.save(persistentVar);
+        }
+        /** Save a variable, assigning its deterministic ID and encrypting new secret plaintext. */
+        async save(persistentVar, opts) {
+            if (!persistentVar.persistentVarId) {
+                persistentVar.persistentVarId = (0, utils_1.deterministicPvarId)(persistentVar.name);
+            }
+            const dbVar = await this.get(persistentVar.persistentVarId);
+            if (persistentVar.isSecret &&
+                persistentVar.value.value !== undefined &&
+                (!rpc_types_1.isClient || (0, rpc_types_1.isSingleProcessClient)())) {
+                if (!dbVar ||
+                    dbVar.value.value !== persistentVar.value.value ||
+                    dbVar.isSecret !== persistentVar.isSecret) {
+                    persistentVar.value.value = await rpc_types_1.rpcServerCalls.encryptData(persistentVar.value.value || "", this.groupId);
+                }
+            }
+            persistentVar.modifiedAt = Date.now();
+            opts ??= {};
+            opts = { saveAsSnapshot: true, ...opts };
+            return super.save(persistentVar, opts);
+        }
+        /**
+         * Replace a legacy random record ID without re-encrypting its already-stored value.
+         *
+         * Migration is storage-only: the value and modified timestamp are preserved. If the
+         * deterministic record already exists, it wins and the duplicate legacy row is removed.
+         */
+        async migrateLegacyId(persistentVar) {
+            if ((0, utils_1.isDeterministicPvarId)(persistentVar.persistentVarId)) {
+                return persistentVar;
+            }
+            const deterministicId = (0, utils_1.deterministicPvarId)(persistentVar.name);
+            const existing = await this.get(deterministicId);
+            await super.delete(persistentVar);
+            if (existing) {
+                return existing;
+            }
+            const migrated = { ...persistentVar, persistentVarId: deterministicId };
+            try {
+                return await super.save(migrated, { saveAsSnapshot: true });
+            }
+            catch (error) {
+                await super.save(persistentVar, { saveAsSnapshot: true }).catch(() => { });
+                throw error;
+            }
         }
-        const dbVar = await this.get(persistentVar.persistentVarId);
-        if (persistentVar.isSecret &&
-            persistentVar.value.value !== undefined &&
-            (!rpc_types_1.isClient || (0, rpc_types_1.isSingleProcessClient)())) {
-            if (!dbVar ||
-                dbVar.value.value !== persistentVar.value.value ||
-                dbVar.isSecret !== persistentVar.isSecret) {
-                persistentVar.value.value = await rpc_types_1.rpcServerCalls.encryptData(persistentVar.value.value || "", this.groupId);
+        /** Return a stored variable's raw value by name. */
+        async getPersistentVarValue(name) {
+            const pVars = await this.list({ name });
+            if (pVars.length > 1) {
+                console.warn(`Multiple persistent variables found with name "${name}". Using the last one.`);
             }
+            const pVar = pVars[pVars.length - 1];
+            return pVar?.value?.value;
         }
-        persistentVar.modifiedAt = Date.now();
-        opts ??= {};
-        opts = { saveAsSnapshot: true, ...opts };
-        return super.save(persistentVar, opts);
-    }
-    async getPersistentVarValue(name) {
-        const pVars = await this.list({ name });
-        if (pVars.length > 1) {
-            console.warn(`Multiple persistent variables found with name "${name}". Using the last one.`);
+        constructor() {
+            super(...arguments);
+            __runInitializers(this, _instanceExtraInitializers);
         }
-        const pVar = pVars[pVars.length - 1];
-        return pVar?.value?.value;
-    }
-}
+    };
+})();
 exports.PersistentVarsTable = PersistentVarsTable;
 (0, table_definitions_system_1.registerSystemTableDefinition)(exports.persistentVarsMetaData, schema, PersistentVarsTable);
+/** Return the persistent-variable table for a data context. */
 function PersistentVars(dataContext) {
     return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(exports.persistentVarsMetaData, schema, PersistentVarsTable);
 }
+/** Resolve a persistent-variable record by name, preferring device scope. */
 async function getPersistentVar(name, dataContext) {
     const pVars = await PersistentVars(dataContext).list({ name });
     if (!pVars.length) {
@@ -210,10 +293,7 @@ function persistentVarFactory(name, opts) {
                         }
                     }
                     if (dbRec && !(0, utils_1.isDeterministicPvarId)(dbRec.persistentVarId)) {
-                        const newId = (0, utils_1.deterministicPvarId)(name);
-                        await table.delete(dbRec);
-                        dbRec.persistentVarId = newId;
-                        dbRec = await table.save(dbRec);
+                        dbRec = await table.migrateLegacyId(dbRec);
                     }
                     if (!dbRec) {
                         dbRec = {

package/dist/data/persistent-vars.migration.test.d.ts

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

package/dist/data/persistent-vars.migration.test.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const originalClientFlag = process.env.PEERS_IS_CLIENT;
+function createEventRegistry() {
+    return {
+        getEmitter: jest.fn().mockReturnValue({
+            event: { subscribe: jest.fn() },
+            emit: jest.fn(),
+        }),
+    };
+}
+function createLegacyRecord(name) {
+    return {
+        persistentVarId: "00mriijkhq94msfe9m2j6quwp",
+        name,
+        scope: "device",
+        isSecret: true,
+        value: { value: "encrypted:ciphertext" },
+        modifiedAt: 1234,
+    };
+}
+afterEach(() => {
+    if (originalClientFlag === undefined) {
+        delete process.env.PEERS_IS_CLIENT;
+    }
+    else {
+        process.env.PEERS_IS_CLIENT = originalClientFlag;
+    }
+    jest.resetModules();
+    jest.restoreAllMocks();
+});
+describe("PersistentVars legacy ID migration", () => {
+    it("uses one custom table RPC from a renderer client", async () => {
+        process.env.PEERS_IS_CLIENT = "true";
+        jest.resetModules();
+        await jest.isolateModulesAsync(async () => {
+            jest.doMock("../context/user-context-singleton", () => ({
+                getTableContainer: jest.fn(),
+                getUserContext: jest.fn(),
+            }));
+            const { PersistentVarsTable, persistentVarsMetaData } = await Promise.resolve().then(() => require("./persistent-vars"));
+            const { ClientProxyDataSource } = await Promise.resolve().then(() => require("./orm/client-proxy.data-source"));
+            const { rpcServerCalls } = await Promise.resolve().then(() => require("../rpc-types"));
+            const record = createLegacyRecord("rendererMigration");
+            const migrated = { ...record, persistentVarId: "00mriijkhq94msfe9m2j6quwq" };
+            const tableMethodCall = jest.fn().mockResolvedValue(migrated);
+            rpcServerCalls.tableMethodCall = tableMethodCall;
+            const dataContextId = "00mriijkhq94msfe9m2j6qabc";
+            const table = new PersistentVarsTable(persistentVarsMetaData, {
+                dataSource: new ClientProxyDataSource(persistentVarsMetaData, undefined, dataContextId),
+                eventRegistry: createEventRegistry(),
+            });
+            await expect(table.migrateLegacyId(record)).resolves.toEqual(migrated);
+            expect(tableMethodCall).toHaveBeenCalledTimes(1);
+            expect(tableMethodCall).toHaveBeenCalledWith(dataContextId, "PersistentVars", "migrateLegacyId", record);
+        });
+    });
+    it("removes a legacy duplicate when the canonical record already exists", async () => {
+        delete process.env.PEERS_IS_CLIENT;
+        jest.resetModules();
+        await jest.isolateModulesAsync(async () => {
+            jest.doMock("../context/user-context-singleton", () => ({
+                getTableContainer: jest.fn(),
+                getUserContext: jest.fn(),
+            }));
+            const { PersistentVarsTable, persistentVarsMetaData } = await Promise.resolve().then(() => require("./persistent-vars"));
+            const { deterministicPvarId } = await Promise.resolve().then(() => require("../utils"));
+            const legacy = createLegacyRecord("existingCanonical");
+            const canonical = {
+                ...legacy,
+                persistentVarId: deterministicPvarId(legacy.name),
+                value: { value: "encrypted:canonical" },
+            };
+            const deleteRecord = jest.fn().mockResolvedValue(undefined);
+            const save = jest.fn();
+            const table = new PersistentVarsTable(persistentVarsMetaData, {
+                dataSource: {
+                    tableName: "PersistentVars",
+                    primaryKeyName: "persistentVarId",
+                    get: jest.fn().mockResolvedValue(canonical),
+                    list: jest.fn(),
+                    count: jest.fn(),
+                    save,
+                    insert: jest.fn(),
+                    update: jest.fn(),
+                    delete: deleteRecord,
+                },
+                eventRegistry: createEventRegistry(),
+            });
+            await expect(table.migrateLegacyId(legacy)).resolves.toEqual(canonical);
+            expect(deleteRecord).toHaveBeenCalledWith(legacy);
+            expect(save).not.toHaveBeenCalled();
+        });
+    });
+    it("restores the legacy record when writing the canonical ID fails", async () => {
+        delete process.env.PEERS_IS_CLIENT;
+        jest.resetModules();
+        await jest.isolateModulesAsync(async () => {
+            jest.doMock("../context/user-context-singleton", () => ({
+                getTableContainer: jest.fn(),
+                getUserContext: jest.fn(),
+            }));
+            const { PersistentVarsTable, persistentVarsMetaData } = await Promise.resolve().then(() => require("./persistent-vars"));
+            const legacy = createLegacyRecord("rollbackMigration");
+            const migrationError = new Error("canonical write failed");
+            const deleteRecord = jest.fn().mockResolvedValue(undefined);
+            const save = jest.fn().mockRejectedValueOnce(migrationError).mockResolvedValueOnce(legacy);
+            const table = new PersistentVarsTable(persistentVarsMetaData, {
+                dataSource: {
+                    tableName: "PersistentVars",
+                    primaryKeyName: "persistentVarId",
+                    get: jest.fn().mockResolvedValue(undefined),
+                    list: jest.fn(),
+                    count: jest.fn(),
+                    save,
+                    insert: jest.fn(),
+                    update: jest.fn(),
+                    delete: deleteRecord,
+                },
+                eventRegistry: createEventRegistry(),
+            });
+            await expect(table.migrateLegacyId(legacy)).rejects.toBe(migrationError);
+            expect(deleteRecord).toHaveBeenCalledWith(legacy);
+            expect(save).toHaveBeenCalledTimes(2);
+            expect(save.mock.calls[0][0]).toMatchObject({
+                name: legacy.name,
+                value: legacy.value,
+            });
+            expect(save.mock.calls[0][0].persistentVarId).not.toBe(legacy.persistentVarId);
+            expect(save.mock.calls[1][0]).toEqual(legacy);
+        });
+    });
+});

package/dist/data/table-definitions-table.d.ts

@@ -34,7 +34,7 @@ export type ITableDefinitionRecord = z.infer<typeof tableDefinitionRecordSchema>
  *
  * @param dataContext - Optional data context; when omitted the singleton context is used.
  */
-export declare function TableDefinitions(dataContext?: DataContext): import("./orm").Table<{
+export declare function TableDefinitions(dataContext?: DataContext): import("..").Table<{
     name: string;
     metaData: {} & {
         [k: string]: any;

package/dist/data/tool-tests.d.ts

@@ -26,7 +26,7 @@ export declare const toolTestSchema: z.ZodObject<{
     mocks?: any;
 }>;
 export type IToolTest = z.infer<typeof toolTestSchema>;
-export declare function ToolTests(dataContext?: DataContext): import("./orm").Table<{
+export declare function ToolTests(dataContext?: DataContext): import("..").Table<{
     code: string;
     description: string;
     toolId: string;

package/dist/data/tools.d.ts

@@ -313,7 +313,7 @@ export interface IToolInstance {
     inputSchema?: z.ZodObject<any>;
     outputSchema?: z.ZodObject<any>;
 }
-export declare function Tools(dataContext?: DataContext): import("./orm").Table<{
+export declare function Tools(dataContext?: DataContext): import("..").Table<{
     code: string;
     name: string;
     toolId: string;

package/dist/data/user-trust-levels.d.ts

@@ -27,7 +27,7 @@ export declare const userTrustLevelSchema: z.ZodObject<{
 /** A trust assignment for one user within a specific data context. */
 export type IUserTrustLevel = z.infer<typeof userTrustLevelSchema>;
 /** Returns the context-scoped table containing explicit user trust assignments. */
-export declare function UserTrustLevels(dataContext?: DataContext): import("./orm").Table<{
+export declare function UserTrustLevels(dataContext?: DataContext): import("..").Table<{
     userId: string;
     trustLevel: TrustLevel;
     assignedAt?: Date | undefined;

package/dist/data/voice-messages.d.ts

@@ -23,7 +23,7 @@ export declare const voiceMessageSchema: z.ZodObject<{
     threadId?: string | undefined;
 }>;
 export type IVoiceMessage = z.infer<typeof voiceMessageSchema>;
-export declare function VoiceMessages(dataContext?: DataContext): import("./orm").Table<{
+export declare function VoiceMessages(dataContext?: DataContext): import("..").Table<{
     content: string;
     role: "user" | "assistant";
     createdAt: Date;

package/dist/data/workflow-logs.d.ts

@@ -66,7 +66,7 @@ export declare const workflowLogSchema: z.ZodObject<{
     isError?: boolean | undefined;
 }>;
 export type IWorkflowLog = z.infer<typeof workflowLogSchema>;
-export declare function WorkflowLogs(dataContext?: DataContext): import("./orm").Table<{
+export declare function WorkflowLogs(dataContext?: DataContext): import("..").Table<{
     workflowLogId: string;
     workflowRunId: string;
     contextId: string;

package/dist/data/workflow-runs.d.ts

@@ -32,6 +32,7 @@ export declare const workflowRunSchema: z.ZodObject<{
     parentWorkflowRunId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     defaultAssistantId: z.ZodEffects<z.ZodString, string, string>;
 }, "strip", z.ZodTypeAny, {
+    createdAt: Date;
     defaultAssistantId: string;
     instructions: {
         markdown?: string | undefined;
@@ -39,7 +40,6 @@ export declare const workflowRunSchema: z.ZodObject<{
         directCallToolId?: string | undefined;
         subWorkflowId?: string | undefined;
     }[];
-    createdAt: Date;
     workflowRunId: string;
     parentMessageId: string;
     currentInstructionIndex: number;
@@ -57,6 +57,7 @@ export declare const workflowRunSchema: z.ZodObject<{
     defaultAssistantId: string;
     workflowRunId: string;
     parentMessageId: string;
+    createdAt?: Date | undefined;
     workflowId?: string | undefined;
     instructions?: {
         markdown?: string | undefined;
@@ -64,7 +65,6 @@ export declare const workflowRunSchema: z.ZodObject<{
         directCallToolId?: string | undefined;
         subWorkflowId?: string | undefined;
     }[] | undefined;
-    createdAt?: Date | undefined;
     scheduleDT?: Date | undefined;
     currentInstructionIndex?: number | undefined;
     instructionResults?: any[] | undefined;

package/dist/data/workflows.d.ts

@@ -1,7 +1,9 @@
 import type { DataContext } from "../context/data-context";
-export declare function Workflows(dataContext?: DataContext): import("./orm").Table<{
+export declare function Workflows(dataContext?: DataContext): import("..").Table<{
     name: string;
     description: string;
+    createdAt: Date;
+    updatedAt: Date;
     workflowId: string;
     defaultAssistantId: string;
     instructions: {
@@ -11,7 +13,5 @@ export declare function Workflows(dataContext?: DataContext): import("./orm").Ta
         subWorkflowId?: string | undefined;
     }[];
     createdBy: string;
-    createdAt: Date;
-    updatedAt: Date;
     packageId?: string | undefined;
 }>;

package/dist/rpc-types.d.ts

@@ -1,7 +1,12 @@
+import type { IDeviceDatabaseQueryResult, IDeviceOperationStatus, IDeviceToolRunInput } from "./contracts/system/device-operations-contract";
+import type { ITool } from "./data/tools";
+import type { IConsoleLog } from "./logging/console-logs.table";
+/** Named event payload sent across the frontend RPC bridge. */
 export interface IEventData<T = any> {
     name: string;
     data: T;
 }
+/** Serializable description of one interactive UI element. */
 export interface UIElement {
     tag: string;
     text?: string;
@@ -18,6 +23,7 @@ export interface UIElement {
         height: number;
     };
 }
+/** Serializable renderer state returned to CLI UI-inspection commands. */
 export interface UIState {
     url: string;
     title: string;
@@ -25,6 +31,24 @@ export interface UIState {
     text: string;
     elements: UIElement[];
 }
+/** One verified direct device connection exposed by the local Electron bridge. */
+export interface IConnectedDeviceSummary {
+    deviceId: string;
+    userId: string;
+    connectionId: string;
+    connectionAddress?: string;
+    trustLevel: number;
+    verified: boolean;
+}
+/** Filters and bounds for one remote System Logs query. */
+export interface IRemoteLogsQueryInput {
+    dataContextId?: string;
+    filter?: Record<string, unknown>;
+    pageSize?: number;
+    sortBy?: string[];
+    textSearch?: string;
+}
+/** RPC methods implemented by the trusted local server/main process. */
 export declare const rpcServerCalls: {
     ping: (msg: string) => Promise<string>;
     openLinkInBrowser: (url: string) => Promise<void>;
@@ -102,6 +126,13 @@ export declare const rpcServerCalls: {
         rowCount: number;
     }>;
     runTool: (toolId: string, args: Record<string, any>, dataContextId?: string, assistantId?: string) => Promise<any>;
+    listConnectedDevices: () => Promise<IConnectedDeviceSummary[]>;
+    getRemoteDeviceStatus: (deviceId: string, dataContextId?: string) => Promise<IDeviceOperationStatus>;
+    remoteDbQuery: (deviceId: string, query: string, dataContextId?: string) => Promise<IDeviceDatabaseQueryResult>;
+    remoteListTools: (deviceId: string, limit?: number, dataContextId?: string) => Promise<ITool[]>;
+    remoteGetTool: (deviceId: string, toolIdOrName: string, dataContextId?: string) => Promise<ITool | null>;
+    remoteRunTool: (deviceId: string, input: IDeviceToolRunInput, dataContextId?: string) => Promise<unknown>;
+    remoteQueryLogs: (deviceId: string, input?: IRemoteLogsQueryInput) => Promise<IConsoleLog[]>;
     uiReload: (options?: {
         ignoreCache?: boolean;
     }) => Promise<void>;
@@ -152,6 +183,7 @@ export declare const rpcServerCalls: {
     subscribePrefixes: (prefixes: string[]) => Promise<void>;
     unsubscribePrefixes: (prefixes: string[]) => Promise<void>;
 };
+/** RPC methods implemented by renderer/frontend clients. */
 export declare const rpcClientCalls: {
     ping: (msg: string) => Promise<string>;
     emitEvent: (event: IEventData) => Promise<boolean>;
@@ -182,8 +214,13 @@ export declare const rpcClientCalls: {
         error?: string;
     }>;
 };
+/** Name of a server/main-process RPC method. */
 export type RpcServerNames = keyof typeof rpcServerCalls;
+/** Name of a renderer/frontend RPC method. */
 export type RpcClientNames = keyof typeof rpcClientCalls;
+/** Whether this module is executing in a renderer, browser, or CLI client context. */
 export declare const isClient: boolean;
+/** Mark the runtime as a single-process client such as the PWA. */
 export declare function setSingleProcessClient(value: boolean): void;
+/** Return whether client and server responsibilities share one process. */
 export declare function isSingleProcessClient(): boolean;

package/dist/rpc-types.js

@@ -10,6 +10,7 @@ function rpcStub(rpcName) {
             JSON.stringify({ rpcName, args }, null, 2));
     };
 }
+/** RPC methods implemented by the trusted local server/main process. */
 exports.rpcServerCalls = {
     ping: async (msg) => `pong: ${msg}`,
     // TODO collapse these two down to just openPath
@@ -60,6 +61,14 @@ exports.rpcServerCalls = {
     dbQuery: rpcStub("dbQuery"),
     // Direct tool execution (for CLI)
     runTool: rpcStub("runTool"),
+    // Headless direct-device administration bridge (for CLI)
+    listConnectedDevices: rpcStub("listConnectedDevices"),
+    getRemoteDeviceStatus: rpcStub("getRemoteDeviceStatus"),
+    remoteDbQuery: rpcStub("remoteDbQuery"),
+    remoteListTools: rpcStub("remoteListTools"),
+    remoteGetTool: rpcStub("remoteGetTool"),
+    remoteRunTool: rpcStub("remoteRunTool"),
+    remoteQueryLogs: rpcStub("remoteQueryLogs"),
     // UI control (for CLI)
     uiReload: rpcStub("uiReload"),
     uiInspect: rpcStub("uiInspect"),
@@ -90,6 +99,7 @@ exports.rpcServerCalls = {
     subscribePrefixes: rpcStub("subscribePrefixes"),
     unsubscribePrefixes: rpcStub("unsubscribePrefixes"),
 };
+/** RPC methods implemented by renderer/frontend clients. */
 exports.rpcClientCalls = {
     ping: async (msg) => `pong: ${msg}`,
     // emitEvent: rpcStub('emitEvent') as ((event: IEventData) => Promise<boolean>),
@@ -106,14 +116,17 @@ exports.rpcClientCalls = {
 // Check if we're in a client context (browser, webview, or CLI connected to server)
 // - Browser: window + document exist
 // - CLI: process.env.PEERS_IS_CLIENT === 'true'
+/** Whether this module is executing in a renderer, browser, or CLI client context. */
 exports.isClient = (typeof window !== "undefined" && typeof document !== "undefined") ||
     (typeof process !== "undefined" && process.env?.PEERS_IS_CLIENT === "true");
 // Single-process mode (PWA): client and server live in the same process,
 // so Table events must NOT be suppressed on the client side.
 let _singleProcessClient = false;
+/** Mark the runtime as a single-process client such as the PWA. */
 function setSingleProcessClient(value) {
     _singleProcessClient = value;
 }
+/** Return whether client and server responsibilities share one process. */
 function isSingleProcessClient() {
     return _singleProcessClient;
 }

package/dist/system-ids.d.ts

@@ -1,11 +1,20 @@
+/** Stable user ID that owns built-in Peers system records. */
 export declare const peersRootUserId = "000peers0user000000000001";
+/** Default assistant used when no user-selected assistant is available. */
 export declare const defaultAssistantId = "000peers0bot00000000shell";
+/** Stable ID of the bundled OpenCode assistant. */
 export declare const openCodeAssistantId = "00mlwl2km2opencode0000001";
+/** Stable ID of the default assistant-runner tool. */
 export declare const defaultAssistantRunnerToolId = "000peers0tool00000runner1";
+/** Stable ID of the built-in send-message tool. */
 export declare const defaultSendMessageToolId = "000peers0tool00000sendmsg";
+/** Stable ID of the built-in workflow runner tool. */
 export declare const runWorkflowToolId = "000peers0tool0runworkflow";
+/** Stable package ID of the bundled peers-core package. */
 export declare const peersCorePackageId = "00mh0wlipjixk2gqmurbwee0o";
+/** Canonical source repository for peers-core. */
 export declare const peersCorePackageRepoUrl = "https://github.com/peers-app/peers-core";
+/** Trusted publishing key for official peers-core releases. */
 export declare const peersCorePublishPublicKey = "S7cQqnvVz-FVDO6Lk5zC7epSvcP_-NyBVZz9gdcj73c";
 /**
  * Stable id of the peers **system** itself, used as the `providerPackageId` for
@@ -18,3 +27,8 @@ export declare const peersSystemPackageId = "000peers0system0000000001";
  * contract-consumer-based remote RPC. See `contracts/system/logs-contract.ts`.
  */
 export declare const logsContractId = "000peers0logs000000000001";
+/**
+ * Contract id for the built-in **System Device Operations** contract. The provider exposes
+ * explicit owner-authorized status, bounded read-only database, and installed-tool operations.
+ */
+export declare const deviceOperationsContractId = "00mriijkhq94msfe9m2j6quwp";

package/dist/system-ids.js

@@ -1,15 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.logsContractId = exports.peersSystemPackageId = exports.peersCorePublishPublicKey = exports.peersCorePackageRepoUrl = exports.peersCorePackageId = exports.runWorkflowToolId = exports.defaultSendMessageToolId = exports.defaultAssistantRunnerToolId = exports.openCodeAssistantId = exports.defaultAssistantId = exports.peersRootUserId = void 0;
+exports.deviceOperationsContractId = exports.logsContractId = exports.peersSystemPackageId = exports.peersCorePublishPublicKey = exports.peersCorePackageRepoUrl = exports.peersCorePackageId = exports.runWorkflowToolId = exports.defaultSendMessageToolId = exports.defaultAssistantRunnerToolId = exports.openCodeAssistantId = exports.defaultAssistantId = exports.peersRootUserId = void 0;
+/** Stable user ID that owns built-in Peers system records. */
 exports.peersRootUserId = "000peers0user000000000001";
+/** Default assistant used when no user-selected assistant is available. */
 exports.defaultAssistantId = "000peers0bot00000000shell";
 // export const defaultAssistantId = '000peers0bot000000000bot1';
+/** Stable ID of the bundled OpenCode assistant. */
 exports.openCodeAssistantId = "00mlwl2km2opencode0000001";
+/** Stable ID of the default assistant-runner tool. */
 exports.defaultAssistantRunnerToolId = "000peers0tool00000runner1";
+/** Stable ID of the built-in send-message tool. */
 exports.defaultSendMessageToolId = "000peers0tool00000sendmsg";
+/** Stable ID of the built-in workflow runner tool. */
 exports.runWorkflowToolId = "000peers0tool0runworkflow";
+/** Stable package ID of the bundled peers-core package. */
 exports.peersCorePackageId = "00mh0wlipjixk2gqmurbwee0o";
+/** Canonical source repository for peers-core. */
 exports.peersCorePackageRepoUrl = "https://github.com/peers-app/peers-core";
+/** Trusted publishing key for official peers-core releases. */
 exports.peersCorePublishPublicKey = "S7cQqnvVz-FVDO6Lk5zC7epSvcP_-NyBVZz9gdcj73c";
 /**
  * Stable id of the peers **system** itself, used as the `providerPackageId` for
@@ -22,3 +31,8 @@ exports.peersSystemPackageId = "000peers0system0000000001";
  * contract-consumer-based remote RPC. See `contracts/system/logs-contract.ts`.
  */
 exports.logsContractId = "000peers0logs000000000001";
+/**
+ * Contract id for the built-in **System Device Operations** contract. The provider exposes
+ * explicit owner-authorized status, bounded read-only database, and installed-tool operations.
+ */
+exports.deviceOperationsContractId = "00mriijkhq94msfe9m2j6quwp";

package/dist/types/workflow.d.ts

@@ -44,6 +44,8 @@ export declare const workflowSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     name: string;
     description: string;
+    createdAt: Date;
+    updatedAt: Date;
     workflowId: string;
     defaultAssistantId: string;
     instructions: {
@@ -53,8 +55,6 @@ export declare const workflowSchema: z.ZodObject<{
         subWorkflowId?: string | undefined;
     }[];
     createdBy: string;
-    createdAt: Date;
-    updatedAt: Date;
     packageId?: string | undefined;
 }, {
     name: string;
@@ -63,13 +63,13 @@ export declare const workflowSchema: z.ZodObject<{
     defaultAssistantId: string;
     createdBy: string;
     packageId?: string | undefined;
+    createdAt?: Date | undefined;
+    updatedAt?: Date | undefined;
     instructions?: {
         markdown?: string | undefined;
         onError?: string | undefined;
         directCallToolId?: string | undefined;
         subWorkflowId?: string | undefined;
     }[] | undefined;
-    createdAt?: Date | undefined;
-    updatedAt?: Date | undefined;
 }>;
 export type IWorkflow = z.infer<typeof workflowSchema>;

package/package.json

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