@peers-app/peers-sdk 0.16.5 → 0.17.0

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",

package/dist/data/tools.d.ts

@@ -3,8 +3,7 @@ import type { DataContext } from "../context/data-context";
 export declare enum IOSchemaType {
     none = "none",
     simple = "simple",
-    complex = "complex",
-    code = "code"
+    complex = "complex"
 }
 export declare const ioSchema: z.ZodObject<{
     type: z.ZodNativeEnum<typeof IOSchemaType>;
@@ -215,6 +214,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 +244,7 @@ export declare const toolSchema: z.ZodObject<{
             subType?: string | undefined;
         }[];
     };
+    packageId?: string | undefined;
     detailedDescription?: string | undefined;
     configSchema?: {
         type: IOSchemaType;
@@ -288,6 +289,7 @@ export declare const toolSchema: z.ZodObject<{
         }[] | undefined;
     };
     code?: string | undefined;
+    packageId?: string | undefined;
     detailedDescription?: string | undefined;
     configSchema?: {
         type: IOSchemaType;
@@ -340,6 +342,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

@@ -13,7 +13,6 @@ var IOSchemaType;
     IOSchemaType["none"] = "none";
     IOSchemaType["simple"] = "simple";
     IOSchemaType["complex"] = "complex";
-    IOSchemaType["code"] = "code";
 })(IOSchemaType || (exports.IOSchemaType = IOSchemaType = {}));
 exports.ioSchema = zod_1.z.object({
     type: zod_1.z.nativeEnum(IOSchemaType),
@@ -44,6 +43,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/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./context";
+export * from "./contracts";
 export * from "./data";
 export * as data from "./data";
 export * from "./data/orm";

package/dist/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.tools = exports.workflowLogSchema = exports.WorkflowLogs = exports.getLogger = exports.orm = exports.data = void 0;
 __exportStar(require("./context"), exports);
+__exportStar(require("./contracts"), exports);
 __exportStar(require("./data"), exports);
 exports.data = require("./data");
 __exportStar(require("./data/orm"), exports);

package/dist/package-loader/contract-package-loader.d.ts

@@ -0,0 +1,23 @@
+import type { DataContext } from "../context/data-context";
+import type { ContractRegistry } from "../contracts/registry";
+import type { IPackageDefinitionResult } from "../contracts/types";
+/**
+ * Installs a contract-based package into a DataContext.
+ *
+ * Handles packages that export an `IPackageDefinitionResult` from `definePackage()`.
+ * Registers contracts in the provided ContractRegistry, saves tools/assistants/workflows
+ * with the `packageId` from the definition set, and registers table definitions.
+ */
+export declare function installContractPackage(dataContext: DataContext, packageDefinition: IPackageDefinitionResult, opts?: {
+    registry?: ContractRegistry;
+}): Promise<void>;
+/**
+ * Attempts to extract an `IPackageDefinitionResult` from a bundle's module exports.
+ * Returns undefined if the bundle doesn't export a contract-based package definition.
+ */
+export declare function extractPackageDefinition(bundleExports: Record<string, unknown>): IPackageDefinitionResult | undefined;
+/**
+ * Determines whether a bundle exports a contract-based package definition,
+ * indicating it should be installed via the new contract-aware path.
+ */
+export declare function hasPackageDefinition(bundleExports: Record<string, unknown>): boolean;

package/dist/package-loader/contract-package-loader.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installContractPackage = installContractPackage;
+exports.extractPackageDefinition = extractPackageDefinition;
+exports.hasPackageDefinition = hasPackageDefinition;
+const tools_1 = require("../data/tools");
+const tools_2 = require("../tools");
+/**
+ * Installs a contract-based package into a DataContext.
+ *
+ * Handles packages that export an `IPackageDefinitionResult` from `definePackage()`.
+ * Registers contracts in the provided ContractRegistry, saves tools/assistants/workflows
+ * with the `packageId` from the definition set, and registers table definitions.
+ */
+async function installContractPackage(dataContext, packageDefinition, opts) {
+    const { packageId } = packageDefinition;
+    const registry = opts?.registry;
+    // Register contracts in the in-memory registry
+    if (registry) {
+        for (const contract of packageDefinition.contracts) {
+            const key = `${contract.contractId}@${contract.version}`;
+            const alsoImpl = packageDefinition.alsoImplements.get(key) ?? [];
+            const result = registry.register(packageId, contract, alsoImpl);
+            if (!result.valid) {
+                console.error(`[ContractPackageLoader] Contract registration failed for ${contract.name}:`, result.errors);
+            }
+        }
+    }
+    // Install tool instances with packageId
+    for (const toolInstance of packageDefinition.toolInstances) {
+        (0, tools_2.registerTool)(toolInstance);
+        const toolWithPackageId = { ...toolInstance.tool, packageId };
+        await (0, tools_1.Tools)(dataContext).save(toolWithPackageId);
+    }
+    // Install table definitions
+    for (const tableDefinition of packageDefinition.tableDefinitions) {
+        dataContext.tableContainer.registerTableDefinition(tableDefinition, {
+            overwrite: true,
+        });
+    }
+    // Install assistants with packageId
+    const { Assistants } = await Promise.resolve().then(() => require("../data/assistants"));
+    for (const assistant of packageDefinition.assistants) {
+        const assistantWithPackageId = { ...assistant, packageId };
+        await Assistants(dataContext).save(assistantWithPackageId);
+    }
+}
+/**
+ * Attempts to extract an `IPackageDefinitionResult` from a bundle's module exports.
+ * Returns undefined if the bundle doesn't export a contract-based package definition.
+ */
+function extractPackageDefinition(bundleExports) {
+    const def = bundleExports?.packageDefinition;
+    if (def && Array.isArray(def.contracts) && def.contracts.length > 0) {
+        return def;
+    }
+    return undefined;
+}
+/**
+ * Determines whether a bundle exports a contract-based package definition,
+ * indicating it should be installed via the new contract-aware path.
+ */
+function hasPackageDefinition(bundleExports) {
+    return extractPackageDefinition(bundleExports) !== undefined;
+}

package/dist/package-loader/index.d.ts

@@ -1 +1,2 @@
+export * from "./contract-package-loader";
 export * from "./package-loader";

package/dist/package-loader/index.js

@@ -14,4 +14,5 @@ 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 });
+__exportStar(require("./contract-package-loader"), exports);
 __exportStar(require("./package-loader"), exports);

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

@@ -6,8 +6,12 @@ export declare class PackageLoader {
     static PeersSDK: any;
     static Zod: any;
     private packageInstances;
+    /** Packages that were installed via the contract-based path (tools/assistants/tables already saved with packageId). */
+    private contractInstalledPackages;
     require: (<T>(module: string) => T) | undefined;
     constructor(dataContext: DataContext);
+    /** Returns true if a package was installed via the contract-based definePackage() path. */
+    isContractInstalled(packageId: string): boolean;
     loadAllPackages(opts?: {
         force?: boolean;
     }): Promise<void>;
@@ -16,6 +20,13 @@ export declare class PackageLoader {
         localPath?: string;
     }): Promise<IPeersPackage | undefined>;
     private _readLocalBundle;
+    /**
+     * Post-correction: if the package definition carries version/versionTag,
+     * update the active IPackageVersion record to match. This fixes cases where
+     * the PV record was created with stale or placeholder values (e.g. "0.0.1")
+     * before the bundle was evaluated.
+     */
+    private correctPackageVersion;
     private _evaluateBundle;
 }
 export declare function setDefaultRequire(require: <T>(module: string) => T): void;