@peers-app/peers-sdk 0.25.20 → 0.26.0

package/dist/data/tools.d.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import type { DataContext } from "../context/data-context";
+export { isToolCatalogPatch, toolCatalogContractDescriptiveFields, toolCatalogIdentityFields, toolCatalogPatch, toolCatalogPatchFields, toolCatalogSupplementalFields, } from "./tool-catalog-fields";
 /** Shape of a tool input, output, or config schema. */
 export declare enum IOSchemaType {
     none = "none",
@@ -62,6 +63,12 @@ export type IOSchema = z.infer<typeof ioSchema>;
 /** Zod schema for a persisted {@link ITool} row. */
 export declare const toolSchema: z.ZodObject<{
     toolId: z.ZodEffects<z.ZodString, string, string>;
+    contractId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    contractVersion: z.ZodOptional<z.ZodNumber>;
+    toolName: z.ZodOptional<z.ZodString>;
+    catalogIdentity: z.ZodOptional<z.ZodEnum<["deterministic", "legacy-alias"]>>;
+    catalogState: z.ZodOptional<z.ZodEnum<["resolved", "unresolved", "quarantined"]>>;
+    catalogReason: z.ZodOptional<z.ZodString>;
     name: z.ZodString;
     usageDescription: z.ZodString;
     detailedDescription: z.ZodOptional<z.ZodString>;
@@ -225,7 +232,6 @@ export declare const toolSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     code: string;
     name: string;
-    toolId: string;
     usageDescription: string;
     inputSchema: {
         type: IOSchemaType;
@@ -251,7 +257,13 @@ export declare const toolSchema: z.ZodObject<{
             subType?: string | undefined;
         }[];
     };
-    detailedDescription?: string | undefined;
+    toolId: string;
+    contractId?: string | undefined;
+    contractVersion?: number | undefined;
+    toolName?: string | undefined;
+    catalogIdentity?: "deterministic" | "legacy-alias" | undefined;
+    catalogState?: "resolved" | "unresolved" | "quarantined" | undefined;
+    catalogReason?: string | undefined;
     configSchema?: {
         type: IOSchemaType;
         fields: {
@@ -264,15 +276,15 @@ export declare const toolSchema: z.ZodObject<{
             subType?: string | undefined;
         }[];
     } | undefined;
-    codeRepository?: string | undefined;
     isAssistantRunner?: boolean | undefined;
+    detailedDescription?: string | undefined;
+    codeRepository?: string | undefined;
     packageId?: string | undefined;
     authorityPropagation?: "preserve" | "cap" | undefined;
     accessLevel?: number | undefined;
     remoteAccessLevel?: number | undefined;
 }, {
     name: string;
-    toolId: string;
     usageDescription: string;
     inputSchema: {
         type: IOSchemaType;
@@ -298,8 +310,14 @@ export declare const toolSchema: z.ZodObject<{
             subType?: string | undefined;
         }[] | undefined;
     };
+    toolId: string;
     code?: string | undefined;
-    detailedDescription?: string | undefined;
+    contractId?: string | undefined;
+    contractVersion?: number | undefined;
+    toolName?: string | undefined;
+    catalogIdentity?: "deterministic" | "legacy-alias" | undefined;
+    catalogState?: "resolved" | "unresolved" | "quarantined" | undefined;
+    catalogReason?: string | undefined;
     configSchema?: {
         type: IOSchemaType;
         fields?: {
@@ -312,8 +330,9 @@ export declare const toolSchema: z.ZodObject<{
             subType?: string | undefined;
         }[] | undefined;
     } | undefined;
-    codeRepository?: string | undefined;
     isAssistantRunner?: boolean | undefined;
+    detailedDescription?: string | undefined;
+    codeRepository?: string | undefined;
     packageId?: string | undefined;
     authorityPropagation?: "preserve" | "cap" | undefined;
     accessLevel?: number | undefined;
@@ -321,7 +340,10 @@ export declare const toolSchema: z.ZodObject<{
 }>;
 /** A tool definition stored in the Tools table. */
 export type ITool = z.infer<typeof toolSchema>;
-/** Runnable tool: persisted metadata plus the in-memory implementation. */
+/**
+ * Historical tool instance shape used by older packages.
+ * @deprecated Use IContractToolImplementation with a contract resolver.
+ */
 export interface IToolInstance {
     tool: ITool;
     toolFn: (...args: any[]) => any;
@@ -336,7 +358,6 @@ export interface IToolInstance {
 export declare function Tools(dataContext?: DataContext): import("..").Table<{
     code: string;
     name: string;
-    toolId: string;
     usageDescription: string;
     inputSchema: {
         type: IOSchemaType;
@@ -362,7 +383,13 @@ export declare function Tools(dataContext?: DataContext): import("..").Table<{
             subType?: string | undefined;
         }[];
     };
-    detailedDescription?: string | undefined;
+    toolId: string;
+    contractId?: string | undefined;
+    contractVersion?: number | undefined;
+    toolName?: string | undefined;
+    catalogIdentity?: "deterministic" | "legacy-alias" | undefined;
+    catalogState?: "resolved" | "unresolved" | "quarantined" | undefined;
+    catalogReason?: string | undefined;
     configSchema?: {
         type: IOSchemaType;
         fields: {
@@ -375,8 +402,9 @@ export declare function Tools(dataContext?: DataContext): import("..").Table<{
             subType?: string | undefined;
         }[];
     } | undefined;
-    codeRepository?: string | undefined;
     isAssistantRunner?: boolean | undefined;
+    detailedDescription?: string | undefined;
+    codeRepository?: string | undefined;
     packageId?: string | undefined;
     authorityPropagation?: "preserve" | "cap" | undefined;
     accessLevel?: number | undefined;

package/dist/data/tools.js

@@ -1,14 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toolSchema = exports.ioSchema = exports.IOSchemaType = void 0;
+exports.toolSchema = exports.ioSchema = exports.IOSchemaType = exports.toolCatalogSupplementalFields = exports.toolCatalogPatchFields = exports.toolCatalogPatch = exports.toolCatalogIdentityFields = exports.toolCatalogContractDescriptiveFields = exports.isToolCatalogPatch = void 0;
 exports.Tools = Tools;
 const zod_1 = require("zod");
 const user_context_singleton_1 = require("../context/user-context-singleton");
+const tool_catalog_identity_1 = require("../contracts/tool-catalog-identity");
 const field_type_1 = require("../types/field-type");
 const zod_types_1 = require("../types/zod-types");
 const access_level_1 = require("./access-level");
 const table_definitions_system_1 = require("./orm/table-definitions.system");
 const types_1 = require("./orm/types");
+var tool_catalog_fields_1 = require("./tool-catalog-fields");
+Object.defineProperty(exports, "isToolCatalogPatch", { enumerable: true, get: function () { return tool_catalog_fields_1.isToolCatalogPatch; } });
+Object.defineProperty(exports, "toolCatalogContractDescriptiveFields", { enumerable: true, get: function () { return tool_catalog_fields_1.toolCatalogContractDescriptiveFields; } });
+Object.defineProperty(exports, "toolCatalogIdentityFields", { enumerable: true, get: function () { return tool_catalog_fields_1.toolCatalogIdentityFields; } });
+Object.defineProperty(exports, "toolCatalogPatch", { enumerable: true, get: function () { return tool_catalog_fields_1.toolCatalogPatch; } });
+Object.defineProperty(exports, "toolCatalogPatchFields", { enumerable: true, get: function () { return tool_catalog_fields_1.toolCatalogPatchFields; } });
+Object.defineProperty(exports, "toolCatalogSupplementalFields", { enumerable: true, get: function () { return tool_catalog_fields_1.toolCatalogSupplementalFields; } });
 /** Shape of a tool input, output, or config schema. */
 var IOSchemaType;
 (function (IOSchemaType) {
@@ -23,7 +31,13 @@ exports.ioSchema = zod_1.z.object({
 });
 /** Zod schema for a persisted {@link ITool} row. */
 exports.toolSchema = zod_1.z.object({
-    toolId: zod_types_1.zodPeerId,
+    toolId: zod_1.z.string().refine(tool_catalog_identity_1.isCatalogToolId, "Invalid tool ID"),
+    contractId: zod_1.z.string().refine(tool_catalog_identity_1.isCatalogContractId, "Invalid catalog contract ID").optional(),
+    contractVersion: zod_1.z.number().int().positive().max(Number.MAX_SAFE_INTEGER).optional(),
+    toolName: zod_1.z.string().optional(),
+    catalogIdentity: zod_1.z.enum(["deterministic", "legacy-alias"]).optional(),
+    catalogState: zod_1.z.enum(["resolved", "unresolved", "quarantined"]).optional(),
+    catalogReason: zod_1.z.string().optional(),
     name: zod_1.z.string().describe("The name of the tool"),
     usageDescription: zod_1.z
         .string()
@@ -37,17 +51,22 @@ exports.toolSchema = zod_1.z.object({
     configSchema: exports.ioSchema
         .optional()
         .describe("The schema of any configuration values that the tool may need"),
-    code: zod_1.z.string().default("").describe("The code that implements the tool"),
+    code: zod_1.z
+        .string()
+        .default("")
+        .describe("Historical tool source; this runtime never writes or executes it"),
     codeRepository: zod_1.z
         .string()
         .optional()
-        .describe("The repository where the code for the tool is stored"),
+        .describe("Historical source repository; this runtime never writes or executes it"),
     // TODO versioning somehow, maybe a git tag or branch
     isAssistantRunner: zod_1.z
         .boolean()
         .optional()
         .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"),
+    packageId: zod_types_1.zodPeerId
+        .optional()
+        .describe("Historical package provenance; not ownership, availability or permission"),
     authorityPropagation: zod_1.z
         .enum(["cap", "preserve"])
         .optional()
@@ -65,12 +84,16 @@ exports.toolSchema = zod_1.z.object({
 });
 const metaData = {
     name: "Tools",
-    description: "Tools that can be used by assistants.",
+    description: "Permanent public contract tool catalog and preserved legacy tools.",
     primaryKeyName: "toolId",
     fields: (0, types_1.schemaToFields)(exports.toolSchema),
     iconClassName: "bi bi-tools",
-    indexes: [{ fields: ["name"] }, { fields: ["isAssistantRunner"] }],
-    versionNumber: 1,
+    indexes: [
+        { fields: ["name"] },
+        { fields: ["isAssistantRunner"] },
+        { fields: ["contractId", "contractVersion", "toolName"] },
+    ],
+    versionNumber: 2,
 };
 (0, table_definitions_system_1.registerSystemTableDefinition)(metaData, exports.toolSchema);
 /**

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

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import type { DataContext } from "../context/data-context";
+/** Persisted execution logs and tool results for one workflow. */
 export declare const workflowLogSchema: z.ZodObject<{
     workflowLogId: z.ZodEffects<z.ZodString, string, string>;
     workflowRunId: z.ZodEffects<z.ZodString, string, string>;
@@ -52,8 +53,8 @@ export declare const workflowLogSchema: z.ZodObject<{
     contextId: string;
     logText: string;
     toolId?: string | undefined;
-    result?: string | undefined;
     logDT?: Date | undefined;
+    result?: string | undefined;
     instruction?: {
         markdown?: string | undefined;
         onError?: string | undefined;
@@ -65,7 +66,9 @@ export declare const workflowLogSchema: z.ZodObject<{
     resultObject?: any[] | z.objectInputType<{}, z.ZodAny, "strip"> | undefined;
     isError?: boolean | undefined;
 }>;
+/** A persisted workflow execution log record. */
 export type IWorkflowLog = z.infer<typeof workflowLogSchema>;
+/** Read or write workflow logs in the specified context. */
 export declare function WorkflowLogs(dataContext?: DataContext): import("..").Table<{
     workflowRunId: string;
     workflowLogId: string;
@@ -85,7 +88,8 @@ export declare function WorkflowLogs(dataContext?: DataContext): import("..").Ta
     resultObject?: any[] | z.objectOutputType<{}, z.ZodAny, "strip"> | undefined;
     isError?: boolean | undefined;
 }>;
-export declare const getLogger: (workflowRunId: string, contextId: string) => (logData: string | Omit<Partial<IWorkflowLog>, "workflowRunId" | "workflowLogId">) => Promise<{
+/** Bind a logger to its run and owning context, independent of the active group. */
+export declare const getLogger: (workflowRunId: string, contextId: string, dataContext?: DataContext) => (logData: string | Omit<Partial<IWorkflowLog>, "workflowRunId" | "workflowLogId">) => Promise<{
     workflowRunId: string;
     workflowLogId: string;
     contextId: string;

package/dist/data/workflow-logs.js

@@ -9,6 +9,7 @@ const zod_types_1 = require("../types/zod-types");
 const utils_1 = require("../utils");
 const table_definitions_system_1 = require("./orm/table-definitions.system");
 const types_1 = require("./orm/types");
+/** Persisted execution logs and tool results for one workflow. */
 exports.workflowLogSchema = zod_1.z.object({
     workflowLogId: zod_types_1.zodPeerId,
     workflowRunId: zod_types_1.zodPeerId.describe("The workflow run that this log entry is associated with"),
@@ -39,22 +40,24 @@ const metaData = {
     localOnly: true,
 };
 (0, table_definitions_system_1.registerSystemTableDefinition)(metaData, exports.workflowLogSchema);
+/** Read or write workflow logs in the specified context. */
 function WorkflowLogs(dataContext) {
     return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(metaData, exports.workflowLogSchema);
 }
-const getLogger = (workflowRunId, contextId) => {
+/** Bind a logger to its run and owning context, independent of the active group. */
+const getLogger = (workflowRunId, contextId, dataContext) => {
     return async (logData) => {
         try {
             let logRecord;
             if (typeof logData === "string") {
-                logRecord = WorkflowLogs().initRecord({
+                logRecord = WorkflowLogs(dataContext).initRecord({
                     workflowRunId,
                     workflowLogId: (0, utils_1.newid)(),
                     logText: logData,
                 });
             }
             else {
-                logRecord = WorkflowLogs().initRecord({
+                logRecord = WorkflowLogs(dataContext).initRecord({
                     workflowRunId,
                     workflowLogId: (0, utils_1.newid)(),
                     ...logData,
@@ -63,7 +66,7 @@ const getLogger = (workflowRunId, contextId) => {
             logRecord.workflowRunId = workflowRunId;
             logRecord.logText = logRecord.logText || "";
             logRecord.contextId = contextId;
-            return await WorkflowLogs().insert(logRecord);
+            return await WorkflowLogs(dataContext).insert(logRecord);
         }
         catch (err) {
             // console.error(`Error recording log for assistant run - assistantId: ${assistantId}, messageId: ${messageId}, logData: ${logData}`, err);
@@ -73,4 +76,3 @@ const getLogger = (workflowRunId, contextId) => {
     };
 };
 exports.getLogger = getLogger;
-// export type IWorkflowLogger = ReturnType<typeof getLogger>;

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

@@ -33,7 +33,6 @@ export declare const workflowRunSchema: z.ZodObject<{
     defaultAssistantId: z.ZodEffects<z.ZodString, string, string>;
 }, "strip", z.ZodTypeAny, {
     createdAt: Date;
-    workflowRunId: string;
     defaultAssistantId: string;
     instructions: {
         markdown?: string | undefined;
@@ -41,12 +40,13 @@ export declare const workflowRunSchema: z.ZodObject<{
         directCallToolId?: string | undefined;
         subWorkflowId?: string | undefined;
     }[];
-    parentMessageId: string;
-    currentInstructionIndex: number;
-    instructionResults: any[];
     vars: {} & {
         [k: string]: any;
     };
+    workflowRunId: string;
+    parentMessageId: string;
+    currentInstructionIndex: number;
+    instructionResults: any[];
     workflowId?: string | undefined;
     scheduleDT?: Date | undefined;
     inErrorState?: boolean | undefined;
@@ -54,8 +54,8 @@ export declare const workflowRunSchema: z.ZodObject<{
     completedAt?: Date | undefined;
     parentWorkflowRunId?: string | undefined;
 }, {
-    workflowRunId: string;
     defaultAssistantId: string;
+    workflowRunId: string;
     parentMessageId: string;
     createdAt?: Date | undefined;
     workflowId?: string | undefined;
@@ -65,13 +65,13 @@ export declare const workflowRunSchema: z.ZodObject<{
         directCallToolId?: string | undefined;
         subWorkflowId?: string | undefined;
     }[] | undefined;
+    vars?: z.objectInputType<{}, z.ZodAny, "strip"> | undefined;
     scheduleDT?: Date | undefined;
     currentInstructionIndex?: number | undefined;
     instructionResults?: any[] | undefined;
     inErrorState?: boolean | undefined;
     startedAt?: Date | undefined;
     completedAt?: Date | undefined;
-    vars?: z.objectInputType<{}, z.ZodAny, "strip"> | undefined;
     parentWorkflowRunId?: string | undefined;
 }>;
 export type IWorkflowRun = z.infer<typeof workflowRunSchema>;

package/dist/index.d.ts

@@ -38,8 +38,6 @@ export * from "./peers-ui/peers-ui.types";
 export * from "./rpc-types";
 export * from "./serial-json";
 export * from "./system-ids";
-export * from "./tools";
-export * as tools from "./tools";
 export * from "./types/app-nav";
 export * from "./types/assistant-runner-args";
 export * from "./types/field-type";

package/dist/index.js

@@ -14,7 +14,7 @@ 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.tools = exports.workflowLogSchema = exports.WorkflowLogs = exports.getLogger = exports.orm = exports.data = void 0;
+exports.workflowLogSchema = exports.WorkflowLogs = exports.getLogger = exports.orm = exports.data = void 0;
 __exportStar(require("./context"), exports);
 __exportStar(require("./contracts"), exports);
 __exportStar(require("./data"), exports);
@@ -59,8 +59,6 @@ __exportStar(require("./peers-ui/peers-ui.types"), exports);
 __exportStar(require("./rpc-types"), exports);
 __exportStar(require("./serial-json"), exports);
 __exportStar(require("./system-ids"), exports);
-__exportStar(require("./tools"), exports);
-exports.tools = require("./tools");
 __exportStar(require("./types/app-nav"), exports);
 __exportStar(require("./types/assistant-runner-args"), exports);
 __exportStar(require("./types/field-type"), exports);

package/dist/package-installer/package-creator.d.ts

@@ -27,30 +27,39 @@ export declare function ensureTemplateCache(deps: IPackageInstallerDeps, templat
 /**
  * Resolve (or create) the Ed25519 publish public key for a package.
  *
- * Idempotent: never rotates an established key. Reuses `existingPublishPublicKey`
- * when present, derives the public key from an existing secret pvar when possible,
- * and only generates a new keypair when both are missing.
+ * Never rotates an established identity. Checks the Packages key, the public key
+ * cached in the personal signing pvar's description, and any key recoverable from
+ * its secret for agreement before writing. Hosts may decrypt legacy secrets via
+ * `resolveSigningPublicKey`; plaintext secrets never need to leave the host.
+ * Lazily caches recovered public keys without changing the stored secret value.
+ * Generates keys only when both the secret and every public-key source are missing.
  *
- * @throws When a readable secret key does not match an established `publishPublicKey`.
+ * @throws When recovered public keys disagree, or a secret has no recoverable public key.
  */
 export declare function ensurePackageSigningKey(opts: {
     personalContext?: DataContext;
     packageId: string;
     packageName: string;
     existingPublishPublicKey?: string;
+    /** Host-only recovery of a public key from an encrypted personal signing secret. */
+    resolveSigningPublicKey?: ICreatePackageOpts["resolveSigningPublicKey"];
 }): Promise<string>;
 /**
  * Import an existing on-disk Peers package directory into the current data context.
  *
  * Validates the manifest packageId, creates/updates the Packages record, persists
  * `packageLocalPath_*`, provisions a signing key when missing, then installs the
- * local dev bundles.
+ * local dev bundles. When the target Packages row is absent, reuses the first
+ * nonblank public key for the same packageId from the user's personal context
+ * or groups. Other contexts' package metadata is not copied.
  */
 export declare function importExistingPackage(dataContext: DataContext, deps: IPackageInstallerDeps, opts: {
     location: string;
     personalContext?: DataContext;
     /** Display name fallback when the manifest name is a slug. */
     displayName?: string;
+    /** Host-only recovery of a public key from an encrypted personal signing secret. */
+    resolveSigningPublicKey?: ICreatePackageOpts["resolveSigningPublicKey"];
 }): Promise<ICreatePackageResult>;
 /**
  * Create a new Peers package from the package template.

package/dist/package-installer/package-creator.js

@@ -106,63 +106,96 @@ async function ensureTemplateCache(deps, templateRepo) {
     await deps.shell.exec(`git clone ${templateRepo} ${cachePath}`);
     return { cachePath };
 }
+const SIGNING_KEY_MARKER_PREFIX = "peers-package-signing-key:";
+function validSigningPublicKey(value) {
+    return typeof value === "string" && (0, keys_1.derivePublicBoxKey)(value) ? value : undefined;
+}
+function cachedSigningPublicKey(description, packageId) {
+    const markers = (description || "")
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith(SIGNING_KEY_MARKER_PREFIX));
+    if (markers.length !== 1)
+        return undefined;
+    const match = /^peers-package-signing-key:v1:([^:]+):([^:]+)$/.exec(markers[0]);
+    return match?.[1] === packageId ? validSigningPublicKey(match[2]) : undefined;
+}
+function signingKeyDescription(description, packageId, publicKey) {
+    const text = description
+        .split(/\r?\n/)
+        .filter((line) => !line.startsWith(SIGNING_KEY_MARKER_PREFIX))
+        .join("\n");
+    return `${text}${text ? "\n" : ""}${SIGNING_KEY_MARKER_PREFIX}v1:${packageId}:${publicKey}`;
+}
 /**
  * Resolve (or create) the Ed25519 publish public key for a package.
  *
- * Idempotent: never rotates an established key. Reuses `existingPublishPublicKey`
- * when present, derives the public key from an existing secret pvar when possible,
- * and only generates a new keypair when both are missing.
+ * Never rotates an established identity. Checks the Packages key, the public key
+ * cached in the personal signing pvar's description, and any key recoverable from
+ * its secret for agreement before writing. Hosts may decrypt legacy secrets via
+ * `resolveSigningPublicKey`; plaintext secrets never need to leave the host.
+ * Lazily caches recovered public keys without changing the stored secret value.
+ * Generates keys only when both the secret and every public-key source are missing.
  *
- * @throws When a readable secret key does not match an established `publishPublicKey`.
+ * @throws When recovered public keys disagree, or a secret has no recoverable public key.
  */
 async function ensurePackageSigningKey(opts) {
     const { personalContext, packageId, packageName, existingPublishPublicKey } = opts;
     const establishedKey = existingPublishPublicKey?.trim() || "";
-    if (personalContext) {
-        const keyName = `${package_author_signing_1.PACKAGE_SIGNING_KEY_PREFIX}${packageId}`;
-        const existingKey = await (0, persistent_vars_1.PersistentVars)(personalContext).findOne({ name: keyName });
-        const rawSecret = existingKey?.value?.value;
-        if (typeof rawSecret === "string" && rawSecret.length > 0) {
+    if (!personalContext)
+        return establishedKey;
+    const keyName = `${package_author_signing_1.PACKAGE_SIGNING_KEY_PREFIX}${packageId}`;
+    const table = (0, persistent_vars_1.PersistentVars)(personalContext);
+    const existingKey = await table.findOne({ name: keyName });
+    const rawSecret = existingKey?.value?.value;
+    const cachedKey = cachedSigningPublicKey(existingKey?.description, packageId);
+    let derivedKey;
+    if (typeof rawSecret === "string" && rawSecret.length > 0) {
+        try {
+            derivedKey = validSigningPublicKey((0, keys_1.hydrateKeys)(rawSecret).publicKey);
+        }
+        catch {
+            // Encrypted-at-rest secrets cannot be hydrated directly by the SDK.
+        }
+        if (!derivedKey && opts.resolveSigningPublicKey) {
             try {
-                const derivedPublicKey = (0, keys_1.hydrateKeys)(rawSecret).publicKey;
-                if (establishedKey && derivedPublicKey !== establishedKey) {
-                    throw new Error(`Package signing key mismatch for "${packageName}" (${packageId}): ` +
-                        "stored secret does not match Packages.publishPublicKey. " +
-                        "Refusing to rotate the established key.");
-                }
-                return establishedKey || derivedPublicKey;
+                derivedKey = validSigningPublicKey(await opts.resolveSigningPublicKey(rawSecret));
             }
-            catch (err) {
-                if (err instanceof Error && err.message.includes("signing key mismatch")) {
-                    throw err;
-                }
-                // Secret is likely encrypted at rest — cannot derive here without the user key.
-                if (establishedKey) {
-                    return establishedKey;
-                }
-                throw new Error(`Package "${packageName}" (${packageId}) has a signing secret pvar but no ` +
-                    "publishPublicKey, and the secret could not be hydrated. " +
-                    "Restore publishPublicKey or replace the unreadable key before importing.");
+            catch {
+                // Decryption is best-effort. Never expose ciphertext, plaintext, or host errors.
             }
         }
     }
-    if (establishedKey) {
-        return establishedKey;
+    const publicKey = establishedKey || cachedKey || derivedKey;
+    if ([establishedKey, cachedKey, derivedKey].some((key) => key && key !== publicKey)) {
+        throw new Error(`Package signing key mismatch for "${packageName}" (${packageId}): ` +
+            "Packages.publishPublicKey, cached public key, and stored secret must agree. " +
+            "Refusing to rotate the established key.");
     }
-    if (!personalContext) {
-        return "";
+    if (publicKey) {
+        if (existingKey && validSigningPublicKey(publicKey)) {
+            const description = signingKeyDescription(existingKey.description || "", packageId, publicKey);
+            if (description !== existingKey.description) {
+                // Keep the ciphertext identical so PersistentVarsTable.save does not encrypt it again.
+                await table.save({ ...existingKey, description });
+            }
+        }
+        return publicKey;
+    }
+    if (rawSecret !== undefined && rawSecret !== null && rawSecret !== "") {
+        throw new Error(`Package "${packageName}" (${packageId}) has a signing secret pvar but no ` +
+            "recoverable publishPublicKey, and the secret could not be hydrated. " +
+            "Restore publishPublicKey or unlock the signing secret before importing.");
     }
     const keys = (0, keys_1.newKeys)();
-    const keyName = `${package_author_signing_1.PACKAGE_SIGNING_KEY_PREFIX}${packageId}`;
-    await (0, persistent_vars_1.PersistentVars)(personalContext).save({
+    await table.save({
         persistentVarId: (0, utils_1.deterministicPvarId)(keyName),
         name: keyName,
         scope: "user",
         value: { value: keys.secretKey },
         isSecret: true,
-        description: `Signing key for package "${packageName}"`,
+        description: signingKeyDescription(`Signing key for package "${packageName}"`, packageId, keys.publicKey),
         modifiedAt: Date.now(),
-    });
+    }, { restoreIfDeleted: true });
     return keys.publicKey;
 }
 async function registerPackageRecord(dataContext, opts) {
@@ -195,7 +228,9 @@ async function persistPackageLocalPath(dataContext, deps, packageId, location) {
  *
  * Validates the manifest packageId, creates/updates the Packages record, persists
  * `packageLocalPath_*`, provisions a signing key when missing, then installs the
- * local dev bundles.
+ * local dev bundles. When the target Packages row is absent, reuses the first
+ * nonblank public key for the same packageId from the user's personal context
+ * or groups. Other contexts' package metadata is not copied.
  */
 async function importExistingPackage(dataContext, deps, opts) {
     const info = await (0, package_installer_1.getPackageInfo)(deps, opts.location);
@@ -204,12 +239,30 @@ async function importExistingPackage(dataContext, deps, opts) {
     }
     const packageId = info.packageId;
     const existing = await (0, packages_1.Packages)(dataContext).get(packageId);
+    let existingPublishPublicKey = existing?.publishPublicKey;
+    const userContext = dataContext.userContext;
+    if (!existing && userContext) {
+        for (const sourceContext of [
+            userContext.userDataContext,
+            ...userContext.groupDataContexts.values(),
+        ]) {
+            if (sourceContext.dataContextId === dataContext.dataContextId)
+                continue;
+            const sourcePackage = await (0, packages_1.Packages)(sourceContext).get(packageId);
+            const sourcePublicKey = sourcePackage?.publishPublicKey?.trim();
+            if (sourcePublicKey) {
+                existingPublishPublicKey = sourcePublicKey;
+                break;
+            }
+        }
+    }
     const packageName = opts.displayName || info.name || packageId;
     const publishPublicKey = await ensurePackageSigningKey({
         personalContext: opts.personalContext,
         packageId,
         packageName,
-        existingPublishPublicKey: existing?.publishPublicKey,
+        existingPublishPublicKey,
+        resolveSigningPublicKey: opts.resolveSigningPublicKey,
     });
     await registerPackageRecord(dataContext, {
         packageId,
@@ -248,6 +301,7 @@ async function createPackage(dataContext, deps, opts) {
             location,
             personalContext: opts.personalContext,
             displayName: opts.name,
+            resolveSigningPublicKey: opts.resolveSigningPublicKey,
         });
     }
     await (0, package_dev_tools_1.assertPackageDevTools)(deps);
@@ -313,6 +367,7 @@ async function createPackage(dataContext, deps, opts) {
         personalContext: opts.personalContext,
         packageId,
         packageName: opts.name,
+        resolveSigningPublicKey: opts.resolveSigningPublicKey,
     });
     await registerPackageRecord(dataContext, {
         packageId,