@peers-app/peers-sdk 0.1.4

package/dist/data/user-permissions.test.js

@@ -0,0 +1,252 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const keys_1 = require("../keys");
+const user_permissions_1 = require("./user-permissions");
+const socket_type_1 = require("../device/socket.type");
+// Test the user permissions logic directly without ORM dependencies
+describe('User Permissions Logic', () => {
+    let testUser;
+    let userKeys;
+    let otherUserKeys;
+    beforeEach(() => {
+        userKeys = (0, keys_1.newKeys)();
+        otherUserKeys = (0, keys_1.newKeys)();
+        testUser = {
+            userId: 'test-user-1',
+            name: 'Test User',
+            publicKey: userKeys.publicKey,
+            publicBoxKey: userKeys.publicBoxKey,
+            trustLevel: socket_type_1.TrustLevel.Trusted,
+            signature: ''
+        };
+    });
+    describe('basic signature functionality', () => {
+        it('should add signature to user object', () => {
+            const signedUser = (0, keys_1.addSignatureToObject)(testUser, userKeys.secretKey);
+            expect(signedUser.signature).toBeTruthy();
+            expect(signedUser.signature).toContain(':');
+            expect(signedUser.userId).toBe(testUser.userId);
+            expect(signedUser.name).toBe(testUser.name);
+            expect(signedUser.publicKey).toBe(testUser.publicKey);
+        });
+        it('should verify valid signature', () => {
+            const signedUser = (0, keys_1.addSignatureToObject)(testUser, userKeys.secretKey);
+            const isValid = (0, keys_1.isObjectSignatureValid)(signedUser);
+            expect(isValid).toBe(true);
+        });
+        it('should reject invalid signature after modification', () => {
+            const signedUser = (0, keys_1.addSignatureToObject)(testUser, userKeys.secretKey);
+            // Modify the user after signing
+            signedUser.name = 'Modified Name';
+            const isValid = (0, keys_1.isObjectSignatureValid)(signedUser);
+            expect(isValid).toBe(false);
+        });
+        it('should extract public key from signature', () => {
+            const signedUser = (0, keys_1.addSignatureToObject)(testUser, userKeys.secretKey);
+            const extractedPublicKey = (0, keys_1.getPublicKeyFromObjectSignature)(signedUser);
+            expect(extractedPublicKey).toBe(userKeys.publicKey);
+        });
+    });
+    describe('signUserObject helper', () => {
+        it('should sign user object correctly', () => {
+            const signedUser = (0, user_permissions_1.signUserObject)(testUser, userKeys.secretKey);
+            expect(signedUser.signature).toBeTruthy();
+            expect((0, keys_1.isObjectSignatureValid)(signedUser)).toBe(true);
+            expect((0, keys_1.getPublicKeyFromObjectSignature)(signedUser)).toBe(userKeys.publicKey);
+        });
+    });
+    describe('verifyUserSignature', () => {
+        it('should verify valid signature for new user', () => {
+            const signedUser = (0, user_permissions_1.signUserObject)(testUser, userKeys.secretKey);
+            expect(() => (0, user_permissions_1.verifyUserSignature)(signedUser)).not.toThrow();
+        });
+        it('should verify valid signature for existing user update', () => {
+            const originalUser = (0, user_permissions_1.signUserObject)(testUser, userKeys.secretKey);
+            const updatedUser = {
+                ...originalUser,
+                name: 'Updated Name',
+                signature: ''
+            };
+            const signedUpdatedUser = (0, user_permissions_1.signUserObject)(updatedUser, userKeys.secretKey);
+            expect(() => (0, user_permissions_1.verifyUserSignature)(signedUpdatedUser, originalUser)).not.toThrow();
+        });
+        it('should reject signature that does not match user public key for new user', () => {
+            const signedUser = (0, user_permissions_1.signUserObject)(testUser, otherUserKeys.secretKey);
+            expect(() => (0, user_permissions_1.verifyUserSignature)(signedUser)).toThrow('User signature must be signed with their own public key');
+        });
+        it('should reject signature that does not match existing user public key', () => {
+            const originalUser = (0, user_permissions_1.signUserObject)(testUser, userKeys.secretKey);
+            const updatedUser = {
+                ...originalUser,
+                name: 'Updated Name',
+                signature: ''
+            };
+            const signedUpdatedUser = (0, user_permissions_1.signUserObject)(updatedUser, otherUserKeys.secretKey);
+            expect(() => (0, user_permissions_1.verifyUserSignature)(signedUpdatedUser, originalUser)).toThrow('User update must be signed by the user themselves');
+        });
+        it('should reject public key changes', () => {
+            const originalUser = (0, user_permissions_1.signUserObject)(testUser, userKeys.secretKey);
+            const updatedUser = {
+                ...originalUser,
+                publicKey: otherUserKeys.publicKey,
+                signature: ''
+            };
+            const signedUpdatedUser = (0, user_permissions_1.signUserObject)(updatedUser, userKeys.secretKey);
+            expect(() => (0, user_permissions_1.verifyUserSignature)(signedUpdatedUser, originalUser)).toThrow('Public key changes are not currently supported');
+        });
+        it('should handle missing signature gracefully', () => {
+            const userWithoutSignature = { ...testUser };
+            expect(() => (0, user_permissions_1.verifyUserSignature)(userWithoutSignature)).toThrow();
+        });
+    });
+    describe('verifyUserSignature - Group Context (With Signature)', () => {
+        it('should allow valid signature for new user in group context', () => {
+            const signedUser = (0, user_permissions_1.signUserObject)(testUser, userKeys.secretKey);
+            expect(() => (0, user_permissions_1.verifyUserSignature)(signedUser, undefined)).not.toThrow();
+        });
+        it('should allow valid signature for existing user update in group context', () => {
+            const originalUser = (0, user_permissions_1.signUserObject)(testUser, userKeys.secretKey);
+            const updatedUser = {
+                ...originalUser,
+                name: 'Updated Name',
+                signature: ''
+            };
+            const signedUpdatedUser = (0, user_permissions_1.signUserObject)(updatedUser, userKeys.secretKey);
+            expect(() => (0, user_permissions_1.verifyUserSignature)(signedUpdatedUser, originalUser)).not.toThrow();
+        });
+        it('should reject invalid signature in group context', () => {
+            const signedUser = (0, user_permissions_1.signUserObject)(testUser, userKeys.secretKey);
+            // Tamper with the signature
+            signedUser.name = 'Tampered Name';
+            expect(() => (0, user_permissions_1.verifyUserSignature)(signedUser, undefined)).toThrow();
+        });
+        it('should reject signature from wrong user for new user', () => {
+            const signedUser = (0, user_permissions_1.signUserObject)(testUser, otherUserKeys.secretKey);
+            expect(() => (0, user_permissions_1.verifyUserSignature)(signedUser, undefined)).toThrow();
+        });
+        it('should reject signature from wrong user for existing user update', () => {
+            const originalUser = (0, user_permissions_1.signUserObject)(testUser, userKeys.secretKey);
+            const updatedUser = {
+                ...originalUser,
+                name: 'Updated Name',
+                signature: ''
+            };
+            const signedUpdatedUser = (0, user_permissions_1.signUserObject)(updatedUser, otherUserKeys.secretKey);
+            expect(() => (0, user_permissions_1.verifyUserSignature)(signedUpdatedUser, originalUser)).toThrow();
+        });
+        it('should reject public key changes in group context', () => {
+            const originalUser = (0, user_permissions_1.signUserObject)(testUser, userKeys.secretKey);
+            const updatedUser = {
+                ...originalUser,
+                publicKey: otherUserKeys.publicKey, // Change public key
+                signature: ''
+            };
+            const signedUpdatedUser = (0, user_permissions_1.signUserObject)(updatedUser, userKeys.secretKey);
+            expect(() => (0, user_permissions_1.verifyUserSignature)(signedUpdatedUser, originalUser)).toThrow();
+        });
+        it('should allow trust level changes with valid signature in group context', () => {
+            const originalUser = (0, user_permissions_1.signUserObject)({ ...testUser, trustLevel: socket_type_1.TrustLevel.Unknown }, userKeys.secretKey);
+            const updatedUser = {
+                ...originalUser,
+                trustLevel: socket_type_1.TrustLevel.Trusted,
+                signature: ''
+            };
+            const signedUpdatedUser = (0, user_permissions_1.signUserObject)(updatedUser, userKeys.secretKey);
+            expect(() => (0, user_permissions_1.verifyUserSignature)(signedUpdatedUser, originalUser)).not.toThrow();
+        });
+    });
+    describe('verifyUserSignature - Signature Requirements', () => {
+        it('should reject updates without signature when signature is required', () => {
+            const userWithoutSignature = { ...testUser };
+            expect(() => (0, user_permissions_1.verifyUserSignature)(userWithoutSignature, undefined)).toThrow();
+        });
+        it('should accept valid signature when signature is provided', () => {
+            const signedUser = (0, user_permissions_1.signUserObject)(testUser, userKeys.secretKey);
+            expect(() => (0, user_permissions_1.verifyUserSignature)(signedUser, undefined)).not.toThrow();
+        });
+        it('should reject empty signature when signature is required', () => {
+            const userWithEmptySignature = { ...testUser, signature: '' };
+            expect(() => (0, user_permissions_1.verifyUserSignature)(userWithEmptySignature, undefined)).toThrow();
+        });
+        it('should reject whitespace-only signature when signature is required', () => {
+            const userWithWhitespaceSignature = { ...testUser, signature: '   ' };
+            expect(() => (0, user_permissions_1.verifyUserSignature)(userWithWhitespaceSignature, undefined)).toThrow();
+        });
+    });
+    describe('edge cases and error handling', () => {
+        it('should handle undefined user gracefully', () => {
+            // @ts-ignore - Testing edge case
+            expect(() => (0, user_permissions_1.verifyUserSignature)(undefined, undefined)).toThrow();
+        });
+        it('should handle malformed signature', () => {
+            const userWithBadSignature = { ...testUser, signature: 'invalid-signature' };
+            expect(() => (0, user_permissions_1.verifyUserSignature)(userWithBadSignature, undefined)).toThrow();
+        });
+        it('should handle missing public key in user object', () => {
+            const userWithoutPublicKey = { ...testUser, publicKey: '' };
+            const signedUser = (0, user_permissions_1.signUserObject)(userWithoutPublicKey, userKeys.secretKey);
+            expect(() => (0, user_permissions_1.verifyUserSignature)(signedUser, undefined)).toThrow();
+        });
+        it('should handle existing user with missing public key', () => {
+            const originalUser = { ...testUser, publicKey: '' };
+            const updatedUser = { ...testUser, name: 'Updated' };
+            const signedUpdatedUser = (0, user_permissions_1.signUserObject)(updatedUser, userKeys.secretKey);
+            expect(() => (0, user_permissions_1.verifyUserSignature)(signedUpdatedUser, originalUser)).toThrow();
+        });
+        it('should handle complex trust level enum values', () => {
+            const userWithComplexTrust = {
+                ...testUser,
+                trustLevel: socket_type_1.TrustLevel.Malicious
+            };
+            const signedUser = (0, user_permissions_1.signUserObject)(userWithComplexTrust, userKeys.secretKey);
+            expect(() => (0, user_permissions_1.verifyUserSignature)(signedUser, undefined)).not.toThrow();
+        });
+    });
+    describe('security scenarios', () => {
+        it('should prevent impersonation attacks', () => {
+            // Attacker tries to create a user record with victim's public key but signed with attacker's key
+            const victimUser = {
+                userId: 'victim-user',
+                name: 'Victim User',
+                publicKey: userKeys.publicKey, // Victim's public key
+                publicBoxKey: userKeys.publicBoxKey,
+                trustLevel: socket_type_1.TrustLevel.Trusted,
+                signature: ''
+            };
+            const maliciousSignedUser = (0, user_permissions_1.signUserObject)(victimUser, otherUserKeys.secretKey); // Signed with attacker's key
+            expect(() => (0, user_permissions_1.verifyUserSignature)(maliciousSignedUser, undefined)).toThrow();
+        });
+        it('should prevent profile takeover attacks', () => {
+            const originalUser = (0, user_permissions_1.signUserObject)(testUser, userKeys.secretKey);
+            // Attacker tries to update the user's profile with their own signature
+            const maliciousUpdate = {
+                ...originalUser,
+                name: 'Attacker Name',
+                signature: ''
+            };
+            const maliciousSignedUpdate = (0, user_permissions_1.signUserObject)(maliciousUpdate, otherUserKeys.secretKey);
+            expect(() => (0, user_permissions_1.verifyUserSignature)(maliciousSignedUpdate, originalUser)).toThrow();
+        });
+        it('should prevent public key rotation attacks', () => {
+            const originalUser = (0, user_permissions_1.signUserObject)(testUser, userKeys.secretKey);
+            // Attacker tries to change the public key to their own
+            const keyRotationAttack = {
+                ...originalUser,
+                publicKey: otherUserKeys.publicKey, // Change to attacker's key
+                signature: ''
+            };
+            const signedAttack = (0, user_permissions_1.signUserObject)(keyRotationAttack, userKeys.secretKey);
+            expect(() => (0, user_permissions_1.verifyUserSignature)(signedAttack, originalUser)).toThrow();
+        });
+        it('should allow legitimate name changes with proper signature', () => {
+            const originalUser = (0, user_permissions_1.signUserObject)(testUser, userKeys.secretKey);
+            const legitimateUpdate = {
+                ...originalUser,
+                name: 'New Legal Name',
+                signature: ''
+            };
+            const signedUpdate = (0, user_permissions_1.signUserObject)(legitimateUpdate, userKeys.secretKey);
+            expect(() => (0, user_permissions_1.verifyUserSignature)(signedUpdate, originalUser)).not.toThrow();
+        });
+    });
+});

package/dist/data/users.d.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import type { DataContext } from "../context/data-context";
+import { TrustLevel } from "../device/socket.type";
+import { ISaveOptions, Table } from "./orm";
+export declare const userSchema: z.ZodObject<{
+    userId: z.ZodString;
+    name: z.ZodString;
+    publicKey: z.ZodString;
+    publicBoxKey: z.ZodString;
+    trustLevel: z.ZodOptional<z.ZodNativeEnum<typeof TrustLevel>>;
+    signature: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    publicKey: string;
+    userId: string;
+    publicBoxKey: string;
+    signature?: string | undefined;
+    trustLevel?: TrustLevel | undefined;
+}, {
+    name: string;
+    publicKey: string;
+    userId: string;
+    publicBoxKey: string;
+    signature?: string | undefined;
+    trustLevel?: TrustLevel | undefined;
+}>;
+export type IUser = z.infer<typeof userSchema>;
+export declare class UsersTable extends Table<IUser> {
+    static isPassthrough: boolean;
+    save(user: IUser, opts?: ISaveOptions): Promise<IUser>;
+    /** @deprecated Forbidden on UsersTable; use save() */
+    insert(..._args: Parameters<Table<IUser>['insert']>): never;
+    /** @deprecated Forbidden on UsersTable; use save() */
+    update(..._args: Parameters<Table<IUser>['update']>): never;
+}
+export declare function Users(dataContext?: DataContext): UsersTable;
+export declare const myUserId: import("./persistent-vars").PersistentVar<string>;
+export declare function getMe(): Promise<IUser>;

package/dist/data/users.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.myUserId = exports.UsersTable = exports.userSchema = void 0;
+exports.Users = Users;
+exports.getMe = getMe;
+const zod_1 = require("zod");
+const user_context_singleton_1 = require("../context/user-context-singleton");
+const socket_type_1 = require("../device/socket.type");
+const orm_1 = require("./orm");
+const table_definitions_system_1 = require("./orm/table-definitions.system");
+const types_1 = require("./orm/types");
+const user_permissions_1 = require("./user-permissions");
+const persistent_vars_1 = require("./persistent-vars");
+exports.userSchema = zod_1.z.object({
+    userId: zod_1.z.string(),
+    name: zod_1.z.string(),
+    publicKey: zod_1.z.string().describe('The public key the user uses to sign messages'),
+    publicBoxKey: zod_1.z.string().describe('The public key to use to encrypt data that only this user can decrypt'),
+    trustLevel: zod_1.z.nativeEnum(socket_type_1.TrustLevel).optional().describe('The trust level of the user'),
+    signature: zod_1.z.string().optional().describe('The signed hash of this user object excluding the signature itself'),
+});
+const metaData = {
+    name: 'Users',
+    description: 'users',
+    primaryKeyName: 'userId',
+    fields: (0, types_1.schemaToFields)(exports.userSchema),
+    indexes: [
+        { fields: ['name'] },
+        { fields: ['publicKey'] },
+        { fields: ['publicBoxKey'] },
+    ]
+};
+class UsersTable extends orm_1.Table {
+    static isPassthrough = false;
+    async save(user, opts) {
+        if (UsersTable.isPassthrough) {
+            return super.save(user, opts);
+        }
+        const userContext = await (0, user_context_singleton_1.getUserContext)();
+        const userContextUserTable = Users(userContext.userDataContext);
+        if (this === userContextUserTable) {
+            // user is allowed to make any changes they want to their own user table
+            return super.save(user, opts);
+        }
+        // Get the old user record if it exists
+        const oldUser = await this.get(user.userId);
+        await (0, user_permissions_1.verifyUserSignature)(user, oldUser);
+        return super.save(user, opts);
+    }
+    /** @deprecated Forbidden on UsersTable; use save() */
+    insert(..._args) {
+        throw new Error('UsersTable forbids insert; use save()');
+    }
+    /** @deprecated Forbidden on UsersTable; use save() */
+    update(..._args) {
+        throw new Error('UsersTable forbids update; use save()');
+    }
+}
+exports.UsersTable = UsersTable;
+(0, table_definitions_system_1.registerSystemTableDefinition)(metaData, exports.userSchema, UsersTable);
+function Users(dataContext) {
+    return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(metaData, exports.userSchema, UsersTable);
+}
+exports.myUserId = (0, persistent_vars_1.deviceVar)('myUserId', { defaultValue: '' });
+// let me: IUser | undefined = undefined;
+async function getMe() {
+    const userContext = await (0, user_context_singleton_1.getUserContext)();
+    const me = await userContext.getMe();
+    if (!me) {
+        throw new Error('My user object was not found in the DB. Is the user setup?');
+    }
+    return me;
+}

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

@@ -0,0 +1,106 @@
+import { z } from "zod";
+import type { DataContext } from "../context/data-context";
+export declare const workflowLogSchema: z.ZodObject<{
+    workflowLogId: z.ZodEffects<z.ZodString, string, string>;
+    workflowRunId: z.ZodEffects<z.ZodString, string, string>;
+    contextId: z.ZodEffects<z.ZodString, string, string>;
+    logDT: z.ZodDefault<z.ZodDate>;
+    logText: z.ZodString;
+    result: z.ZodOptional<z.ZodString>;
+    instruction: z.ZodOptional<z.ZodObject<{
+        markdown: z.ZodOptional<z.ZodString>;
+        onError: z.ZodOptional<z.ZodString>;
+        directCallToolId: z.ZodOptional<z.ZodString>;
+        subWorkflowId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        markdown?: string | undefined;
+        onError?: string | undefined;
+        directCallToolId?: string | undefined;
+        subWorkflowId?: string | undefined;
+    }, {
+        markdown?: string | undefined;
+        onError?: string | undefined;
+        directCallToolId?: string | undefined;
+        subWorkflowId?: string | undefined;
+    }>>;
+    toolId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    toolArgs: z.ZodOptional<z.ZodObject<{}, "strip", z.ZodAny, z.objectOutputType<{}, z.ZodAny, "strip">, z.objectInputType<{}, z.ZodAny, "strip">>>;
+    toolRunTimeMs: z.ZodOptional<z.ZodNumber>;
+    resultObject: z.ZodOptional<z.ZodUnion<[z.ZodObject<{}, "strip", z.ZodAny, z.objectOutputType<{}, z.ZodAny, "strip">, z.objectInputType<{}, z.ZodAny, "strip">>, z.ZodArray<z.ZodAny, "many">]>>;
+    isError: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    workflowLogId: string;
+    workflowRunId: string;
+    contextId: string;
+    logDT: Date;
+    logText: string;
+    toolId?: string | undefined;
+    result?: string | undefined;
+    instruction?: {
+        markdown?: string | undefined;
+        onError?: string | undefined;
+        directCallToolId?: string | undefined;
+        subWorkflowId?: string | undefined;
+    } | undefined;
+    toolArgs?: z.objectOutputType<{}, z.ZodAny, "strip"> | undefined;
+    toolRunTimeMs?: number | undefined;
+    resultObject?: any[] | z.objectOutputType<{}, z.ZodAny, "strip"> | undefined;
+    isError?: boolean | undefined;
+}, {
+    workflowLogId: string;
+    workflowRunId: string;
+    contextId: string;
+    logText: string;
+    toolId?: string | undefined;
+    logDT?: Date | undefined;
+    result?: string | undefined;
+    instruction?: {
+        markdown?: string | undefined;
+        onError?: string | undefined;
+        directCallToolId?: string | undefined;
+        subWorkflowId?: string | undefined;
+    } | undefined;
+    toolArgs?: z.objectInputType<{}, z.ZodAny, "strip"> | undefined;
+    toolRunTimeMs?: number | undefined;
+    resultObject?: any[] | z.objectInputType<{}, z.ZodAny, "strip"> | undefined;
+    isError?: boolean | undefined;
+}>;
+export type IWorkflowLog = z.infer<typeof workflowLogSchema>;
+export declare function WorkflowLogs(dataContext?: DataContext): import("./orm").Table<{
+    workflowLogId: string;
+    workflowRunId: string;
+    contextId: string;
+    logDT: Date;
+    logText: string;
+    toolId?: string | undefined;
+    result?: string | undefined;
+    instruction?: {
+        markdown?: string | undefined;
+        onError?: string | undefined;
+        directCallToolId?: string | undefined;
+        subWorkflowId?: string | undefined;
+    } | undefined;
+    toolArgs?: z.objectOutputType<{}, z.ZodAny, "strip"> | undefined;
+    toolRunTimeMs?: number | undefined;
+    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<{
+    workflowLogId: string;
+    workflowRunId: string;
+    contextId: string;
+    logDT: Date;
+    logText: string;
+    toolId?: string | undefined;
+    result?: string | undefined;
+    instruction?: {
+        markdown?: string | undefined;
+        onError?: string | undefined;
+        directCallToolId?: string | undefined;
+        subWorkflowId?: string | undefined;
+    } | undefined;
+    toolArgs?: z.objectOutputType<{}, z.ZodAny, "strip"> | undefined;
+    toolRunTimeMs?: number | undefined;
+    resultObject?: any[] | z.objectOutputType<{}, z.ZodAny, "strip"> | undefined;
+    isError?: boolean | undefined;
+}>;

package/dist/data/workflow-logs.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLogger = exports.workflowLogSchema = void 0;
+exports.WorkflowLogs = WorkflowLogs;
+const zod_1 = require("zod");
+const workflow_1 = require("../types/workflow");
+const zod_types_1 = require("../types/zod-types");
+const utils_1 = require("../utils");
+const types_1 = require("./orm/types");
+const user_context_singleton_1 = require("../context/user-context-singleton");
+const table_definitions_system_1 = require("./orm/table-definitions.system");
+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'),
+    contextId: zod_types_1.zodPeerId.describe('The context that this log entry is associated with'),
+    logDT: zod_1.z.date().default(() => new Date()).describe('The date the log occurred'),
+    logText: zod_1.z.string().describe('The text of the log entry'),
+    result: zod_1.z.string().optional().describe('The result of the instructions'),
+    instruction: workflow_1.workflowInstructionSchema.optional().describe('The instruction that was run'),
+    toolId: zod_types_1.zodPeerId.optional().describe('The tool that was run'),
+    toolArgs: zod_types_1.zodAnyObject.optional().describe('The arguments that were passed to the tool'),
+    toolRunTimeMs: zod_1.z.number().optional().describe('The time it took to run the tool in milliseconds'),
+    resultObject: zod_types_1.zodAnyObjectOrArray.optional().describe('If the result is structured data it will be stored here'),
+    isError: zod_1.z.boolean().optional().describe('Whether or not the log entry is the result of an error'),
+});
+const metaData = {
+    name: 'WorkflowLogs',
+    description: 'The log entries for workflow runs.',
+    primaryKeyName: 'workflowLogId',
+    fields: (0, types_1.schemaToFields)(exports.workflowLogSchema),
+};
+(0, table_definitions_system_1.registerSystemTableDefinition)(metaData, exports.workflowLogSchema);
+function WorkflowLogs(dataContext) {
+    return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(metaData, exports.workflowLogSchema);
+}
+const getLogger = (workflowRunId, contextId) => {
+    return async (logData) => {
+        try {
+            let logRecord;
+            if (typeof logData === 'string') {
+                logRecord = WorkflowLogs().initRecord({
+                    workflowRunId,
+                    workflowLogId: (0, utils_1.newid)(),
+                    logText: logData,
+                });
+            }
+            else {
+                logRecord = WorkflowLogs().initRecord({
+                    workflowRunId,
+                    workflowLogId: (0, utils_1.newid)(),
+                    ...logData,
+                });
+            }
+            logRecord.workflowRunId = workflowRunId;
+            logRecord.logText = logRecord.logText || '';
+            logRecord.contextId = contextId;
+            return await WorkflowLogs().insert(logRecord);
+        }
+        catch (err) {
+            // console.error(`Error recording log for assistant run - assistantId: ${assistantId}, messageId: ${messageId}, logData: ${logData}`, err);
+            console.error(`Error recording workflow log - logData: ${logData}`, err);
+            throw err;
+        }
+    };
+};
+exports.getLogger = getLogger;
+// export type IWorkflowLogger = ReturnType<typeof getLogger>;

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

@@ -0,0 +1,103 @@
+import { Table } from "./orm/table";
+import { z } from "zod";
+import { IDataLock } from "./data-locks";
+import type { DataContext } from "../context/data-context";
+export declare const workflowRunSchema: z.ZodObject<{
+    workflowRunId: z.ZodEffects<z.ZodString, string, string>;
+    workflowId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    parentMessageId: z.ZodEffects<z.ZodString, string, string>;
+    createdAt: z.ZodDefault<z.ZodDate>;
+    scheduleDT: z.ZodOptional<z.ZodDate>;
+    instructions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        markdown: z.ZodOptional<z.ZodString>;
+        onError: z.ZodOptional<z.ZodString>;
+        directCallToolId: z.ZodOptional<z.ZodString>;
+        subWorkflowId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        markdown?: string | undefined;
+        onError?: string | undefined;
+        directCallToolId?: string | undefined;
+        subWorkflowId?: string | undefined;
+    }, {
+        markdown?: string | undefined;
+        onError?: string | undefined;
+        directCallToolId?: string | undefined;
+        subWorkflowId?: string | undefined;
+    }>, "many">>;
+    currentInstructionIndex: z.ZodDefault<z.ZodNumber>;
+    instructionResults: z.ZodDefault<z.ZodArray<z.ZodAny, "many">>;
+    inErrorState: z.ZodOptional<z.ZodBoolean>;
+    startedAt: z.ZodOptional<z.ZodDate>;
+    completedAt: z.ZodOptional<z.ZodDate>;
+    vars: z.ZodDefault<z.ZodObject<{}, "strip", z.ZodAny, z.objectOutputType<{}, z.ZodAny, "strip">, z.objectInputType<{}, z.ZodAny, "strip">>>;
+    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;
+        onError?: string | undefined;
+        directCallToolId?: string | undefined;
+        subWorkflowId?: string | undefined;
+    }[];
+    workflowRunId: string;
+    parentMessageId: string;
+    currentInstructionIndex: number;
+    instructionResults: any[];
+    vars: {} & {
+        [k: string]: any;
+    };
+    workflowId?: string | undefined;
+    scheduleDT?: Date | undefined;
+    inErrorState?: boolean | undefined;
+    startedAt?: Date | undefined;
+    completedAt?: Date | undefined;
+    parentWorkflowRunId?: string | undefined;
+}, {
+    defaultAssistantId: string;
+    workflowRunId: string;
+    parentMessageId: string;
+    createdAt?: Date | undefined;
+    workflowId?: string | undefined;
+    instructions?: {
+        markdown?: string | undefined;
+        onError?: string | undefined;
+        directCallToolId?: string | undefined;
+        subWorkflowId?: string | undefined;
+    }[] | 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>;
+declare class WorkflowRunTable extends Table<IWorkflowRun> {
+    /** @deprecated Direct calls to save forbidden; use insert or saveWithLock */
+    save(..._args: Parameters<Table<any>['insert']>): never;
+    /** @deprecated Direct calls to update forbidden; use saveWithLock() */
+    update(..._args: Parameters<Table<any>['update']>): never;
+    saveWithLock(workflowRun: IWorkflowRun, lock?: IDataLock): Promise<IWorkflowRun>;
+    acquireLock(workflowRunId: string, timeoutMs?: number, lockTimeMs?: number): Promise<IDataLock | undefined>;
+    saveAndRelease(workflowRun: IWorkflowRun, lock: IDataLock): Promise<void>;
+    haltRun(workflowRunId: string): Promise<void>;
+    /**
+     * Removes the error state from a workflow run and locks it so
+     * additional editing can be done before it is re-run.
+     */
+    clearErrorState(workflowRunId: string): Promise<IDataLock | false>;
+}
+export declare function WorkflowRuns(dataContext?: DataContext): WorkflowRunTable;
+export interface IRunWorkflowOptions {
+    workflowId: string;
+    parentMessageIdOrChannelIdOrGroupId?: string;
+    parentWorkflowRunId?: string;
+    vars: Record<string, any>;
+    scheduleDT?: Date;
+}
+export declare function runWorkflow(args: IRunWorkflowOptions): Promise<IWorkflowRun>;
+export {};