@peers-app/peers-sdk 0.16.4 → 0.16.6

package/dist/contracts/validate.js

@@ -0,0 +1,274 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateProviderSatisfiesContract = validateProviderSatisfiesContract;
+exports.validateImmutability = validateImmutability;
+exports.validateAlsoImplements = validateAlsoImplements;
+const types_1 = require("./types");
+function ok() {
+    return { valid: true, errors: [] };
+}
+function fail(errors) {
+    return { valid: false, errors };
+}
+function merge(results) {
+    const errors = results.flatMap((r) => r.errors);
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Check whether `implField` satisfies the contract's `contractField`.
+ * - Types must match exactly.
+ * - If the contract field is required, the implementation must also be required.
+ * - `isArray` must match.
+ */
+function isFieldCompatible(contractField, implField) {
+    if (contractField.type !== implField.type) {
+        return `type mismatch: contract requires '${contractField.type}', implementation has '${implField.type}'`;
+    }
+    if (contractField.isArray && !implField.isArray) {
+        return "contract requires array, implementation is not an array";
+    }
+    if (!contractField.isArray && implField.isArray) {
+        return "contract requires scalar, implementation is an array";
+    }
+    if (!contractField.optional && implField.optional) {
+        return "contract requires a required field, implementation marks it optional";
+    }
+    return null;
+}
+function validateTableFields(contractTable, implTable) {
+    const errors = [];
+    const implFieldMap = new Map(implTable.fields.map((f) => [f.name, f]));
+    for (const contractField of contractTable.fields) {
+        const implField = implFieldMap.get(contractField.name);
+        if (!implField) {
+            if (!contractField.optional) {
+                errors.push({
+                    kind: "field",
+                    name: `${contractTable.name}.${contractField.name}`,
+                    message: `Required field '${contractField.name}' missing from implementation table '${implTable.name}'`,
+                });
+            }
+            continue;
+        }
+        const compat = isFieldCompatible(contractField, implField);
+        if (compat) {
+            errors.push({
+                kind: "field",
+                name: `${contractTable.name}.${contractField.name}`,
+                message: `Field '${contractField.name}' in table '${implTable.name}': ${compat}`,
+            });
+        }
+    }
+    // Extra fields in the implementation are allowed only if optional
+    for (const implField of implTable.fields) {
+        const inContract = contractTable.fields.some((f) => f.name === implField.name);
+        if (!inContract && !implField.optional) {
+            errors.push({
+                kind: "field",
+                name: `${implTable.name}.${implField.name}`,
+                message: `Implementation table '${implTable.name}' has extra required field '${implField.name}' not in contract (must be optional)`,
+            });
+        }
+    }
+    return errors;
+}
+function validateToolFields(contractTool, implTool, direction) {
+    const errors = [];
+    const contractFields = direction === "input" ? contractTool.inputFields : contractTool.outputFields;
+    const implFields = direction === "input" ? implTool.inputFields : implTool.outputFields;
+    const implFieldMap = new Map(implFields.map((f) => [f.name, f]));
+    for (const contractField of contractFields) {
+        const implField = implFieldMap.get(contractField.name);
+        if (!implField) {
+            if (!contractField.optional) {
+                errors.push({
+                    kind: "field",
+                    name: `${contractTool.name}.${direction}.${contractField.name}`,
+                    message: `Required ${direction} field '${contractField.name}' missing from tool '${implTool.name}'`,
+                });
+            }
+            continue;
+        }
+        const compat = isFieldCompatible(contractField, implField);
+        if (compat) {
+            errors.push({
+                kind: "field",
+                name: `${contractTool.name}.${direction}.${contractField.name}`,
+                message: `Field '${contractField.name}' in tool '${implTool.name}' ${direction}: ${compat}`,
+            });
+        }
+    }
+    // For inputs: extra optional fields in the implementation are OK (the impl accepts more)
+    // For outputs: extra fields in the implementation are OK (the impl returns more)
+    if (direction === "input") {
+        for (const implField of implFields) {
+            const inContract = contractFields.some((f) => f.name === implField.name);
+            if (!inContract && !implField.optional) {
+                errors.push({
+                    kind: "field",
+                    name: `${implTool.name}.${direction}.${implField.name}`,
+                    message: `Implementation tool '${implTool.name}' has extra required input field '${implField.name}' not in contract (must be optional)`,
+                });
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Validate that an implementation contract satisfies a target contract shape.
+ * The implementation must be a superset: all contract tables, tools, and
+ * observables must be present with compatible shapes.
+ */
+function validateProviderSatisfiesContract(impl, contract) {
+    const errors = [];
+    // Tables
+    const implTableMap = new Map(impl.tables.map((t) => [t.name, t]));
+    for (const contractTable of contract.tables) {
+        const implTable = implTableMap.get(contractTable.name);
+        if (!implTable) {
+            errors.push({
+                kind: "table",
+                name: contractTable.name,
+                message: `Table '${contractTable.name}' required by contract but not provided by implementation`,
+            });
+            continue;
+        }
+        if (implTable.primaryKeyName !== contractTable.primaryKeyName) {
+            errors.push({
+                kind: "table",
+                name: contractTable.name,
+                message: `Table '${contractTable.name}': primary key mismatch — contract expects '${contractTable.primaryKeyName}', implementation has '${implTable.primaryKeyName}'`,
+            });
+        }
+        errors.push(...validateTableFields(contractTable, implTable));
+    }
+    // Tools
+    const implToolMap = new Map(impl.tools.map((t) => [t.name, t]));
+    for (const contractTool of contract.tools) {
+        const implTool = implToolMap.get(contractTool.name);
+        if (!implTool) {
+            errors.push({
+                kind: "tool",
+                name: contractTool.name,
+                message: `Tool '${contractTool.name}' required by contract but not provided by implementation`,
+            });
+            continue;
+        }
+        errors.push(...validateToolFields(contractTool, implTool, "input"));
+        errors.push(...validateToolFields(contractTool, implTool, "output"));
+    }
+    // Observables
+    const implObsMap = new Map(impl.observables.map((o) => [o.name, o]));
+    for (const contractObs of contract.observables) {
+        const implObs = implObsMap.get(contractObs.name);
+        if (!implObs) {
+            errors.push({
+                kind: "observable",
+                name: contractObs.name,
+                message: `Observable '${contractObs.name}' required by contract but not provided by implementation`,
+            });
+            continue;
+        }
+        if (contractObs.valueType !== implObs.valueType) {
+            errors.push({
+                kind: "observable",
+                name: contractObs.name,
+                message: `Observable '${contractObs.name}': type mismatch — contract expects '${contractObs.valueType}', implementation has '${implObs.valueType}'`,
+            });
+        }
+        if (contractObs.writable && !implObs.writable) {
+            errors.push({
+                kind: "observable",
+                name: contractObs.name,
+                message: `Observable '${contractObs.name}' must be writable per contract, but implementation is read-only`,
+            });
+        }
+    }
+    return errors.length === 0 ? ok() : fail(errors);
+}
+/**
+ * Validate that a frozen (stable) contract definition has not been modified.
+ * If the existing definition has no `devTag` it is frozen; the incoming
+ * definition must be structurally identical and also stable.
+ * Dev contracts (`devTag: "dev"`) may change freely but cannot be registered
+ * once a stable version exists for that contract+version.
+ */
+function validateImmutability(existing, incoming) {
+    if (existing.devTag === "dev") {
+        return ok();
+    }
+    // Existing is stable/frozen — reject any attempt to register a dev version
+    if (incoming.devTag === "dev") {
+        return fail([
+            {
+                kind: "contract",
+                name: (0, types_1.contractKey)(existing.contractId, existing.version),
+                message: `Cannot register a dev version for stable contract ${existing.name} v${existing.version} — contract is already frozen`,
+            },
+        ]);
+    }
+    // Deep-compare the shapes. We serialize to JSON for a simple structural comparison.
+    const existingShape = JSON.stringify({
+        tables: existing.tables,
+        tools: existing.tools,
+        observables: existing.observables,
+    });
+    const incomingShape = JSON.stringify({
+        tables: incoming.tables,
+        tools: incoming.tools,
+        observables: incoming.observables,
+    });
+    if (existingShape !== incomingShape) {
+        return fail([
+            {
+                kind: "contract",
+                name: (0, types_1.contractKey)(existing.contractId, existing.version),
+                message: `Stable contract ${existing.name} v${existing.version} is frozen and cannot be modified`,
+            },
+        ]);
+    }
+    return ok();
+}
+/**
+ * Validate that an implementation satisfies all contracts referenced by its
+ * `alsoImplements` declarations.
+ *
+ * @param impl         The implementation's extracted contract definition.
+ * @param declarations The `alsoImplements` declarations for this contract.
+ * @param getContract  Callback to look up an existing contract definition.
+ */
+function validateAlsoImplements(impl, declarations, getContract) {
+    const results = [];
+    for (const decl of declarations) {
+        const versions = [];
+        if (typeof decl.version === "number") {
+            versions.push(decl.version);
+        }
+        else {
+            for (let v = decl.version.from; v <= decl.version.to; v++) {
+                versions.push(v);
+            }
+        }
+        for (const ver of versions) {
+            const target = getContract(decl.contractId, ver);
+            if (!target) {
+                results.push(fail([
+                    {
+                        kind: "contract",
+                        name: (0, types_1.contractKey)(decl.contractId, ver),
+                        message: `alsoImplements references contract ${decl.contractId} v${ver}, but that contract was not found`,
+                    },
+                ]));
+                continue;
+            }
+            const result = validateProviderSatisfiesContract(impl, target);
+            if (!result.valid) {
+                for (const error of result.errors) {
+                    error.message = `[alsoImplements ${decl.contractId} v${ver}] ${error.message}`;
+                }
+                results.push(result);
+            }
+        }
+    }
+    return merge(results);
+}

package/dist/data/assistants.d.ts

@@ -15,6 +15,7 @@ export declare const assistantSchema: z.ZodObject<{
     assistantRunnerConfig: z.ZodDefault<z.ZodObject<{}, "strip", z.ZodAny, z.objectOutputType<{}, z.ZodAny, "strip">, z.objectInputType<{}, z.ZodAny, "strip">>>;
     toolsToInclude: z.ZodDefault<z.ZodString>;
     toolInclusionStrategy: z.ZodDefault<z.ZodNativeEnum<typeof ToolInclusionStrategy>>;
+    packageId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     createdAt: Date;
@@ -26,11 +27,13 @@ export declare const assistantSchema: z.ZodObject<{
     toolsToInclude: string;
     toolInclusionStrategy: ToolInclusionStrategy;
     description?: string | undefined;
+    packageId?: string | undefined;
     updatedAt?: Date | undefined;
 }, {
     name: string;
     assistantId: string;
     description?: string | undefined;
+    packageId?: string | undefined;
     createdAt?: Date | undefined;
     updatedAt?: Date | undefined;
     assistantRunnerToolId?: string | undefined;
@@ -50,6 +53,7 @@ export declare function Assistants(dataContext?: DataContext): import("./orm").T
     toolsToInclude: string;
     toolInclusionStrategy: ToolInclusionStrategy;
     description?: string | undefined;
+    packageId?: string | undefined;
     updatedAt?: Date | undefined;
 }>;
 /**
@@ -73,6 +77,7 @@ export declare const getPrimaryAssistant: (dataContext?: DataContext) => Promise
     toolsToInclude: string;
     toolInclusionStrategy: ToolInclusionStrategy;
     description?: string | undefined;
+    packageId?: string | undefined;
     updatedAt?: Date | undefined;
 }>;
 export declare function getAllAssistantIdsMentioned(message: string): Promise<string[]>;

package/dist/data/assistants.js

@@ -46,6 +46,7 @@ exports.assistantSchema = zod_1.z.object({
         "- **Linked** - `Fixed` plus tools linked in the message or chat history of the assistant's current conversation.",
         "- **Relevant** - `Linked` plus tools matching the context of the conversation determined via vector search (embeddings) of the tools descriptions.",
     ].join("\n")),
+    packageId: zod_types_1.zodPeerId.optional().describe("The package that installed this assistant, if any"),
 });
 const metaData = {
     name: "Assistants",

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

@@ -36,8 +36,8 @@ declare const schema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     version: string;
     signature: string;
-    packageVersionId: string;
     packageId: string;
+    packageVersionId: string;
     packageVersionHash: string;
     packageBundleFileId: string;
     packageBundleFileHash: string;
@@ -57,8 +57,8 @@ declare const schema: z.ZodObject<{
 }, {
     version: string;
     signature: string;
-    packageVersionId: string;
     packageId: string;
+    packageVersionId: string;
     packageVersionHash: string;
     packageBundleFileId: string;
     packageBundleFileHash: string;

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

@@ -26,6 +26,7 @@ declare const schema: z.ZodObject<{
     userCreated: z.ZodOptional<z.ZodBoolean>;
     isSecret: z.ZodOptional<z.ZodBoolean>;
     modifiedAt: z.ZodOptional<z.ZodNumber>;
+    packageId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     value: {
@@ -37,6 +38,7 @@ declare const schema: z.ZodObject<{
     userCreated?: boolean | undefined;
     isSecret?: boolean | undefined;
     modifiedAt?: number | undefined;
+    packageId?: string | undefined;
 }, {
     name: string;
     value: {
@@ -48,6 +50,7 @@ declare const schema: z.ZodObject<{
     userCreated?: boolean | undefined;
     isSecret?: boolean | undefined;
     modifiedAt?: number | undefined;
+    packageId?: string | undefined;
 }>;
 export declare const persistentVarsMetaData: ITableMetaData;
 export type IPersistentVar = z.infer<typeof schema>;

package/dist/data/persistent-vars.js

@@ -40,6 +40,9 @@ const schema = zod_1.z.object({
         .number()
         .optional()
         .describe("Timestamp of when this pvar was last modified (Date.now())"),
+    packageId: zod_types_1.zodPeerId
+        .optional()
+        .describe("The package that owns this persistent variable, if any"),
 });
 exports.persistentVarsMetaData = {
     name: "PersistentVars",
@@ -58,10 +61,12 @@ class PersistentVarsTable extends table_1.Table {
     }
     async save(persistentVar, opts) {
         if (!persistentVar.persistentVarId) {
-            persistentVar.persistentVarId = (0, utils_1.newid)();
+            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 (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) {
@@ -204,6 +209,12 @@ function persistentVarFactory(name, opts) {
                             dbRec = undefined;
                         }
                     }
+                    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);
+                    }
                     if (!dbRec) {
                         dbRec = {
                             persistentVarId: "",
@@ -271,6 +282,10 @@ function persistentVarFactory(name, opts) {
                 };
                 // subscribe to db changes
                 userContext.subscribeToDataChangedAcrossAllGroups(exports.persistentVarsMetaData.name, async (evt) => {
+                    const dc = getDataContext();
+                    if (dc && evt.dataContext && evt.dataContext.dataContextId !== dc.dataContextId) {
+                        return;
+                    }
                     const dbRec = evt.data.dataObject;
                     const dbName = getVarNameInDb();
                     if (!rec?.persistentVarId && dbRec.name === dbName) {

package/dist/data/tools.d.ts

@@ -215,6 +215,7 @@ export declare const toolSchema: z.ZodObject<{
     code: z.ZodDefault<z.ZodString>;
     codeRepository: z.ZodOptional<z.ZodString>;
     isAssistantRunner: z.ZodOptional<z.ZodBoolean>;
+    packageId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
 }, "strip", z.ZodTypeAny, {
     code: string;
     name: string;
@@ -244,6 +245,7 @@ export declare const toolSchema: z.ZodObject<{
             subType?: string | undefined;
         }[];
     };
+    packageId?: string | undefined;
     detailedDescription?: string | undefined;
     configSchema?: {
         type: IOSchemaType;
@@ -288,6 +290,7 @@ export declare const toolSchema: z.ZodObject<{
         }[] | undefined;
     };
     code?: string | undefined;
+    packageId?: string | undefined;
     detailedDescription?: string | undefined;
     configSchema?: {
         type: IOSchemaType;
@@ -340,6 +343,7 @@ export declare function Tools(dataContext?: DataContext): import("./orm").Table<
             subType?: string | undefined;
         }[];
     };
+    packageId?: string | undefined;
     detailedDescription?: string | undefined;
     configSchema?: {
         type: IOSchemaType;

package/dist/data/tools.js

@@ -44,6 +44,7 @@ exports.toolSchema = zod_1.z.object({
         .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"),
 });
 const metaData = {
     name: "Tools",

package/dist/data/workflows.d.ts

@@ -13,4 +13,5 @@ export declare function Workflows(dataContext?: DataContext): import("./orm").Ta
         subWorkflowId?: string | undefined;
     }[];
     updatedAt: Date;
+    packageId?: string | undefined;
 }>;

package/dist/events.d.ts

@@ -4,10 +4,23 @@ export type IEventHandler<T = any> = (eventData: IEventData<T>) => boolean | voi
 export interface ISubscription {
     filter: IEventFilter;
     handler: IEventHandler;
+    /** When set, this subscription matches only events with this exact name (fast-path via Map lookup). */
+    eventName?: string;
 }
 export interface ISubscriptionResult {
     unsubscribe: () => boolean;
 }
+/**
+ * Notify the events system that the client connection is ready.
+ * Flushes any subscriptions that were registered before the connection.
+ */
+export declare function notifyClientConnected(): void;
+/**
+ * Register a prefix-based event subscription with the server.
+ * Events whose name starts with this prefix will be forwarded to the client.
+ * Returns an unsubscribe function that decrements the refcount.
+ */
+export declare function subscribePrefix(prefix: string): () => void;
 export declare function subscribe<T = any>(nameOrFilter: string | IEventFilter, handler: IEventHandler<T>): ISubscriptionResult;
 export declare function subscribeDebounce<T = any>(nameOrFilter: string | IEventFilter, handler: IEventHandler<T>, debounceMs: number): ISubscriptionResult;
 export declare function emit(event: IEventData, dontPropagate?: boolean): Promise<boolean>;