@peers-app/peers-sdk 0.22.0 → 0.23.1

package/dist/data/orm/sql.data-source.js

@@ -245,13 +245,7 @@ class SQLDataSource {
             // @ts-expect-error - need to figure out how to get typescript to understand what's going on here
             record[this.metaData.primaryKeyName] = (0, utils_1.newid)();
         }
-        // validate data
-        try {
-            this.schema.parse(record);
-        }
-        catch (e) {
-            throw new Error(`Validation on insert failed for ${this.tableName}: ${e}`);
-        }
+        this.applySchemaDefaults(record);
         const fields = this.metaData.fields.map((field) => `"${field.name}"`).join(", ");
         const values = this.metaData.fields.map((field) => jsValueToSqlValue(record[field.name]));
         const placeholders = values.map((_v) => "?").join(", ");
@@ -265,16 +259,14 @@ class SQLDataSource {
             // @ts-expect-error - need to figure out how to get typescript to understand what's going on here
             record[this.metaData.primaryKeyName] = (0, utils_1.newid)();
         }
-        // validate data
         this.schema.parse(record);
         const primaryKey = record[this.metaData.primaryKeyName];
-        const fields = this.metaData.fields
-            .filter((field) => field.name !== this.metaData.primaryKeyName)
-            .map((field) => `"${field.name}" = ?`)
-            .join(",\n");
-        const values = this.metaData.fields
-            .filter((field) => field.name !== this.metaData.primaryKeyName)
-            .map((field) => jsValueToSqlValue(record[field.name]));
+        const updateFields = this.fieldsForUpdate(record);
+        if (updateFields.length === 0) {
+            return record;
+        }
+        const fields = updateFields.map((field) => `"${field.name}" = ?`).join(",\n");
+        const values = updateFields.map((field) => jsValueToSqlValue(record[field.name]));
         const sql = [
             `UPDATE "${this.tableName}"`,
             `SET ${fields}`,
@@ -299,6 +291,40 @@ class SQLDataSource {
         const sql = `DELETE FROM "${this.tableName}"`;
         await this.db.exec(sql, []);
     }
+    /**
+     * Validate `record` and copy Zod defaults onto missing keys so NOT NULL
+     * columns (for example `accessLevel`) are written on insert.
+     */
+    applySchemaDefaults(record) {
+        let parsed;
+        try {
+            parsed = this.schema.parse(record);
+        }
+        catch (e) {
+            throw new Error(`Validation on insert failed for ${this.tableName}: ${e}`);
+        }
+        const writable = record;
+        for (const field of this.metaData.fields) {
+            if (writable[field.name] === undefined && parsed[field.name] !== undefined) {
+                writable[field.name] = parsed[field.name];
+            }
+        }
+    }
+    /**
+     * Columns to SET on update. Required fields that are missing are omitted so
+     * older peers without a new column do not overwrite a local value with NULL.
+     */
+    fieldsForUpdate(record) {
+        return this.metaData.fields.filter((field) => {
+            if (field.name === this.metaData.primaryKeyName) {
+                return false;
+            }
+            if (record[field.name] === undefined && !field.optional) {
+                return false;
+            }
+            return true;
+        });
+    }
     initRecord(data = {}) {
         const defaults = {};
         for (const field of this.metaData.fields) {
@@ -323,13 +349,7 @@ class SQLDataSource {
             // @ts-expect-error - need to figure out how to get typescript to understand what's going on here
             record[this.metaData.primaryKeyName] = (0, utils_1.newid)();
         }
-        // validate data
-        try {
-            this.schema.parse(record);
-        }
-        catch (e) {
-            throw new Error(`Validation on insert failed for ${this.tableName}: ${e}`);
-        }
+        this.applySchemaDefaults(record);
         const fields = this.metaData.fields.map((field) => `"${field.name}"`).join(", ");
         const values = this.metaData.fields.map((field) => jsValueToSqlValue(record[field.name]));
         const placeholders = values.map((_v) => "?").join(", ");
@@ -346,16 +366,14 @@ class SQLDataSource {
             // @ts-expect-error - need to figure out how to get typescript to understand what's going on here
             record[this.metaData.primaryKeyName] = (0, utils_1.newid)();
         }
-        // validate data
         this.schema.parse(record);
         const primaryKey = record[this.metaData.primaryKeyName];
-        const fields = this.metaData.fields
-            .filter((field) => field.name !== this.metaData.primaryKeyName)
-            .map((field) => `"${field.name}" = ?`)
-            .join(",\n");
-        const values = this.metaData.fields
-            .filter((field) => field.name !== this.metaData.primaryKeyName)
-            .map((field) => jsValueToSqlValue(record[field.name]));
+        const updateFields = this.fieldsForUpdate(record);
+        if (updateFields.length === 0) {
+            return record;
+        }
+        const fields = updateFields.map((field) => `"${field.name}" = ?`).join(",\n");
+        const values = updateFields.map((field) => jsValueToSqlValue(record[field.name]));
         const sql = [
             `UPDATE "${this.tableName}"`,
             `SET ${fields}`,

package/dist/data/orm/sql.data-source.test.js

@@ -205,6 +205,19 @@ describe("table", () => {
             newTask.title = "Test Task";
             expect(() => TasksTable.schema.parse(newTask)).not.toThrow();
         });
+        it("applies schema defaults on insert and preserves required fields on partial update", async () => {
+            const inserted = await TasksTable.insert({ title: "Defaulted body" });
+            expect(inserted.body).toBe("");
+            const stored = await TasksTable.get(inserted.taskId);
+            expect(stored?.body).toBe("");
+            await TasksTable.update({
+                taskId: inserted.taskId,
+                title: "Renamed",
+            });
+            const afterUpdate = await TasksTable.get(inserted.taskId);
+            expect(afterUpdate?.title).toBe("Renamed");
+            expect(afterUpdate?.body).toBe("");
+        });
         afterAll(async () => {
             await TasksTable.dropTableIfExists();
             await TasksTable.db.close();

package/dist/data/package-version-resolver.test.js

@@ -7,6 +7,7 @@ const SQLiteDB = require("better-sqlite3");
 const user_context_1 = require("../context/user-context");
 const user_context_singleton_1 = require("../context/user-context-singleton");
 const utils_1 = require("../utils");
+const access_level_1 = require("./access-level");
 const assistants_1 = require("./assistants");
 const group_member_roles_1 = require("./group-member-roles");
 const groups_1 = require("./groups");
@@ -375,6 +376,7 @@ describe("resolveDevicePackageVersion — expected behavior (control)", () => {
         const savedAssistant = await (0, assistants_1.Assistants)(dc).get(testAssistantId);
         expect(savedAssistant).toBeDefined();
         expect(savedAssistant?.name).toBe("Upgrade Test Assistant");
+        expect(savedAssistant?.accessLevel).toBe(access_level_1.DEFAULT_ACCESS_LEVEL);
         const savedWorkflow = await (0, workflows_1.Workflows)(dc).get(testWorkflowId);
         expect(savedWorkflow).toBeDefined();
         expect(savedWorkflow?.name).toBe("Upgrade Test Workflow");

package/dist/data/tool-access-approvals.d.ts

@@ -0,0 +1,126 @@
+import { z } from "zod";
+import type { DataContext } from "../context/data-context";
+/** Lifecycle of a tool-access approval request or reusable grant. */
+export declare enum ToolAccessApprovalStatus {
+    pending = "pending",
+    approved = "approved",
+    executed = "executed",
+    rejected = "rejected",
+    expired = "expired",
+    failed = "failed"
+}
+/** How far a granted approval applies after the first execution. */
+export declare enum ToolAccessApprovalScope {
+    once = "once",
+    thread = "thread",
+    context = "context"
+}
+/**
+ * Local-only record of a step-up tool approval.
+ *
+ * Stores identifiers, a frozen argument hash, and sanitized preview text.
+ * Do not put secrets, tokens, or raw log bodies in this table.
+ */
+export declare const toolAccessApprovalSchema: z.ZodObject<{
+    toolAccessApprovalId: z.ZodEffects<z.ZodString, string, string>;
+    userId: z.ZodEffects<z.ZodString, string, string>;
+    assistantId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    toolId: z.ZodEffects<z.ZodString, string, string>;
+    toolName: z.ZodString;
+    dataContextId: z.ZodString;
+    workflowRunId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    threadMessageId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    workflowLogId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    argsHash: z.ZodString;
+    argsPreview: z.ZodDefault<z.ZodString>;
+    frozenArgs: z.ZodObject<{}, "strip", z.ZodAny, z.objectOutputType<{}, z.ZodAny, "strip">, z.objectInputType<{}, z.ZodAny, "strip">>;
+    requiredAccessLevel: z.ZodDefault<z.ZodNumber>;
+    scope: z.ZodDefault<z.ZodNativeEnum<typeof ToolAccessApprovalScope>>;
+    status: z.ZodDefault<z.ZodNativeEnum<typeof ToolAccessApprovalStatus>>;
+    nonce: z.ZodString;
+    expiresAt: z.ZodDate;
+    createdAt: z.ZodDefault<z.ZodDate>;
+    decidedAt: z.ZodOptional<z.ZodDate>;
+    executedAt: z.ZodOptional<z.ZodDate>;
+    resultSummary: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    nonce: string;
+    status: ToolAccessApprovalStatus;
+    scope: ToolAccessApprovalScope;
+    userId: string;
+    expiresAt: Date;
+    toolId: string;
+    createdAt: Date;
+    dataContextId: string;
+    toolAccessApprovalId: string;
+    toolName: string;
+    argsHash: string;
+    argsPreview: string;
+    frozenArgs: {} & {
+        [k: string]: any;
+    };
+    requiredAccessLevel: number;
+    assistantId?: string | undefined;
+    threadMessageId?: string | undefined;
+    workflowRunId?: string | undefined;
+    workflowLogId?: string | undefined;
+    decidedAt?: Date | undefined;
+    executedAt?: Date | undefined;
+    resultSummary?: string | undefined;
+}, {
+    nonce: string;
+    userId: string;
+    expiresAt: Date;
+    toolId: string;
+    dataContextId: string;
+    toolAccessApprovalId: string;
+    toolName: string;
+    argsHash: string;
+    frozenArgs: {} & {
+        [k: string]: any;
+    };
+    status?: ToolAccessApprovalStatus | undefined;
+    scope?: ToolAccessApprovalScope | undefined;
+    assistantId?: string | undefined;
+    createdAt?: Date | undefined;
+    threadMessageId?: string | undefined;
+    workflowRunId?: string | undefined;
+    workflowLogId?: string | undefined;
+    argsPreview?: string | undefined;
+    requiredAccessLevel?: number | undefined;
+    decidedAt?: Date | undefined;
+    executedAt?: Date | undefined;
+    resultSummary?: string | undefined;
+}>;
+/** A local-only tool-access approval or grant. */
+export type IToolAccessApproval = z.infer<typeof toolAccessApprovalSchema>;
+/**
+ * Accessor for the local-only {@link ToolAccessApprovals} table.
+ *
+ * @param dataContext - Optional data context; defaults to the current singleton.
+ */
+export declare function ToolAccessApprovals(dataContext?: DataContext): import("..").Table<{
+    nonce: string;
+    status: ToolAccessApprovalStatus;
+    scope: ToolAccessApprovalScope;
+    userId: string;
+    expiresAt: Date;
+    toolId: string;
+    createdAt: Date;
+    dataContextId: string;
+    toolAccessApprovalId: string;
+    toolName: string;
+    argsHash: string;
+    argsPreview: string;
+    frozenArgs: {} & {
+        [k: string]: any;
+    };
+    requiredAccessLevel: number;
+    assistantId?: string | undefined;
+    threadMessageId?: string | undefined;
+    workflowRunId?: string | undefined;
+    workflowLogId?: string | undefined;
+    decidedAt?: Date | undefined;
+    executedAt?: Date | undefined;
+    resultSummary?: string | undefined;
+}>;

package/dist/data/tool-access-approvals.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolAccessApprovalSchema = exports.ToolAccessApprovalScope = exports.ToolAccessApprovalStatus = void 0;
+exports.ToolAccessApprovals = ToolAccessApprovals;
+const zod_1 = require("zod");
+const user_context_singleton_1 = require("../context/user-context-singleton");
+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");
+/** Lifecycle of a tool-access approval request or reusable grant. */
+var ToolAccessApprovalStatus;
+(function (ToolAccessApprovalStatus) {
+    ToolAccessApprovalStatus["pending"] = "pending";
+    ToolAccessApprovalStatus["approved"] = "approved";
+    ToolAccessApprovalStatus["executed"] = "executed";
+    ToolAccessApprovalStatus["rejected"] = "rejected";
+    ToolAccessApprovalStatus["expired"] = "expired";
+    ToolAccessApprovalStatus["failed"] = "failed";
+})(ToolAccessApprovalStatus || (exports.ToolAccessApprovalStatus = ToolAccessApprovalStatus = {}));
+/** How far a granted approval applies after the first execution. */
+var ToolAccessApprovalScope;
+(function (ToolAccessApprovalScope) {
+    ToolAccessApprovalScope["once"] = "once";
+    ToolAccessApprovalScope["thread"] = "thread";
+    ToolAccessApprovalScope["context"] = "context";
+})(ToolAccessApprovalScope || (exports.ToolAccessApprovalScope = ToolAccessApprovalScope = {}));
+/**
+ * Local-only record of a step-up tool approval.
+ *
+ * Stores identifiers, a frozen argument hash, and sanitized preview text.
+ * Do not put secrets, tokens, or raw log bodies in this table.
+ */
+exports.toolAccessApprovalSchema = zod_1.z.object({
+    toolAccessApprovalId: zod_types_1.zodPeerId,
+    userId: zod_types_1.zodPeerId.describe("User who must approve and who requested the elevation"),
+    assistantId: zod_types_1.zodPeerId
+        .optional()
+        .describe("Assistant that requested the tool; omitted for direct user calls"),
+    toolId: zod_types_1.zodPeerId,
+    toolName: zod_1.z.string().describe("Display name of the tool at request time"),
+    dataContextId: zod_1.z.string().describe("Data context the tool would run in"),
+    workflowRunId: zod_types_1.zodPeerId.optional(),
+    threadMessageId: zod_types_1.zodPeerId
+        .optional()
+        .describe("User message / thread root that owns the workflow"),
+    workflowLogId: zod_types_1.zodPeerId.optional(),
+    argsHash: zod_1.z.string().describe("Canonical hash of the frozen tool arguments"),
+    argsPreview: zod_1.z
+        .string()
+        .default("")
+        .describe("Sanitized, truncated argument summary for the approval card"),
+    frozenArgs: zod_types_1.zodAnyObject.describe("Frozen arguments executed on approve; no secrets"),
+    requiredAccessLevel: access_level_1.accessLevelSchema,
+    scope: zod_1.z.nativeEnum(ToolAccessApprovalScope).default(ToolAccessApprovalScope.once),
+    status: zod_1.z.nativeEnum(ToolAccessApprovalStatus).default(ToolAccessApprovalStatus.pending),
+    nonce: zod_1.z.string().describe("Single-use token; empty after consume"),
+    expiresAt: zod_1.z.date(),
+    createdAt: zod_1.z.date().default(() => new Date()),
+    decidedAt: zod_1.z.date().optional(),
+    executedAt: zod_1.z.date().optional(),
+    resultSummary: zod_1.z.string().optional().describe("Sanitized outcome after execute or deny"),
+});
+const metaData = {
+    name: "ToolAccessApprovals",
+    description: "Local-only pending and granted step-up approvals for privileged tools.",
+    primaryKeyName: "toolAccessApprovalId",
+    fields: (0, types_1.schemaToFields)(exports.toolAccessApprovalSchema),
+    iconClassName: "bi bi-shield-lock",
+    localOnly: true,
+    indexes: [
+        { fields: ["threadMessageId"] },
+        { fields: ["workflowRunId"] },
+        { fields: ["status"] },
+        { fields: ["toolId"] },
+    ],
+};
+(0, table_definitions_system_1.registerSystemTableDefinition)(metaData, exports.toolAccessApprovalSchema);
+/**
+ * Accessor for the local-only {@link ToolAccessApprovals} table.
+ *
+ * @param dataContext - Optional data context; defaults to the current singleton.
+ */
+function ToolAccessApprovals(dataContext) {
+    return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(metaData, exports.toolAccessApprovalSchema);
+}

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

@@ -0,0 +1,162 @@
+/** Workflow-run var naming the Assistant whose delegated authority applies. */
+export declare const ACCESS_ASSISTANT_ID_VAR = "accessAssistantId";
+/** Workflow-run var used as a display / fallback Assistant id. */
+export declare const ASSISTANT_ID_VAR = "assistantId";
+/** Workflow-run var set when the user invoked a tool directly (CLI/UI/RPC). */
+export declare const DIRECT_USER_INVOCATION_VAR = "directUserInvocation";
+/** Workflow-run var pointing at a host-consumed approval that authorizes this run. */
+export declare const HOST_APPROVED_APPROVAL_ID_VAR = "hostApprovedApprovalId";
+/**
+ * Host-owned access keys. Models must not set these via `set-variable` or
+ * `run-a-workflow` child vars.
+ */
+export declare const RESERVED_ACCESS_VAR_KEYS: readonly ["accessAssistantId", "assistantId", "directUserInvocation", "hostApprovedApprovalId"];
+/** How long a pending approval stays actionable. */
+export declare const TOOL_ACCESS_APPROVAL_TTL_MS: number;
+/** How long an approved thread- or context-scoped grant remains reusable. */
+export declare const TOOL_ACCESS_GRANT_TTL_MS: number;
+/** Outcome of {@link decideToolAccess}. */
+export type ToolAccessDecision = {
+    kind: "allow";
+} | {
+    kind: "deny";
+    reason: string;
+} | {
+    kind: "approval_required";
+    reason: string;
+};
+/**
+ * Decide whether a tool may run automatically, needs step-up approval, or is denied.
+ *
+ * Policy (`U` user, `A` Assistant, `T` tool):
+ * - Direct user invocation: allow when `T <= U`, otherwise deny.
+ * - Assistant invocation: deny when `T > U`; allow when `T <= A` or a matching
+ *   grant exists; require approval when `A < T <= U`.
+ *
+ * @param args.userAccessLevel - Current user's group/personal access.
+ * @param args.toolAccessLevel - Required level declared on the tool.
+ * @param args.assistantAccessLevel - Assistant delegated level; omit for direct user calls.
+ * @param args.hasMatchingGrant - True when a reusable scoped grant already covers this call.
+ */
+export declare function decideToolAccess(args: {
+    userAccessLevel: number;
+    toolAccessLevel: number;
+    assistantAccessLevel?: number;
+    hasMatchingGrant?: boolean;
+}): ToolAccessDecision;
+/**
+ * Return whether a user may invoke an Assistant in the current context.
+ *
+ * @param userAccessLevel - Current user's access.
+ * @param assistantAccessLevel - Assistant minimum / delegated level.
+ */
+export declare function canInvokeAssistant(userAccessLevel: number, assistantAccessLevel: number): boolean;
+/**
+ * Canonical hash of tool arguments used to bind one-time approvals.
+ *
+ * @param args - Tool input object; `undefined` hashes as an empty object.
+ */
+export declare function hashToolArgs(args: Record<string, unknown> | undefined): string;
+/**
+ * Append the required access level to a model-facing tool description.
+ *
+ * @param usageDescription - Existing tool usage text.
+ * @param accessLevel - Required level, already resolved or raw.
+ */
+export declare function annotateToolAccessDescription(usageDescription: string, accessLevel: unknown): string;
+/**
+ * Return the fail-closed access level for a record that may omit the field.
+ *
+ * @param record - Tool or Assistant-like object.
+ */
+export declare function recordAccessLevel(record: {
+    accessLevel?: unknown;
+} | undefined): number;
+/**
+ * Choose the delegated Assistant ceiling for a run.
+ *
+ * Direct user calls have no Assistant ceiling (`undefined`). Otherwise only
+ * levels from existing Assistant records are considered; a missing record
+ * does not default to Self. When both an access-assistant and the run default
+ * resolve, the lower level wins so vars cannot escalate past the host-owned
+ * default Assistant.
+ *
+ * @returns `undefined` for direct user calls; otherwise 0–100 (`0` if none resolve).
+ */
+export declare function resolveDelegatedAccessLevel(args: {
+    directUser: boolean;
+    accessAssistantLevel?: number;
+    defaultAssistantLevel?: number;
+}): number | undefined;
+/**
+ * Return whether `name` is a host-owned access-control workflow var.
+ *
+ * @param name - Candidate variable name.
+ */
+export declare function isReservedAccessVarName(name: string): boolean;
+/**
+ * Return the thread root id for a message: its parent, or itself if it is the root.
+ *
+ * Thread-scoped grants must key off this id so a follow-up reply in the same
+ * thread matches the original approval.
+ *
+ * @param message - Message or message-like object; `undefined` returns `undefined`.
+ */
+export declare function threadRootMessageId(message: {
+    messageId?: string;
+    messageParentId?: string;
+} | undefined): string | undefined;
+/**
+ * Structured result returned to a model when a tool needs user approval.
+ */
+export interface IToolAccessApprovalRequiredResult {
+    status: "approval_required";
+    approvalId: string;
+    toolId: string;
+    toolName: string;
+    requiredAccessLevel: number;
+    requiredAccessLabel: string;
+    message: string;
+}
+/**
+ * Build the model-visible payload for a pending approval.
+ */
+export declare function approvalRequiredResult(args: {
+    approvalId: string;
+    toolId: string;
+    toolName: string;
+    requiredAccessLevel: number;
+    message: string;
+}): IToolAccessApprovalRequiredResult;
+/** Workflow plumbing / assistant-runner tools that must not block invocation. */
+export declare const INFRASTRUCTURE_ACCESS_LEVEL: 0;
+/**
+ * Remove one-shot host access tickets from a vars object.
+ *
+ * `directUserInvocation` and `hostApprovedApprovalId` authorize a single
+ * workflow run. Persisting them on a thread message lets later calls reuse a
+ * once-approval or skip Assistant-level checks.
+ *
+ * @param vars - Workflow or message vars; `undefined` becomes `{}`.
+ */
+export declare function omitEphemeralAccessVars(vars: Record<string, unknown> | undefined): Record<string, unknown>;
+/**
+ * Strip every host-owned access key, including Assistant identity vars.
+ *
+ * Use this before showing vars to a model or copying caller-supplied child
+ * vars onto a nested run.
+ *
+ * @param vars - Workflow or message vars; `undefined` becomes `{}`.
+ */
+export declare function omitReservedAccessVars(vars: Record<string, unknown> | undefined): Record<string, unknown>;
+/**
+ * Copy access-authority vars onto a child workflow so nested runs cannot escalate.
+ *
+ * Caller-supplied reserved keys are stripped. The child keeps the parent's
+ * Assistant id and whether the *parent* was a direct user invocation.
+ *
+ * @param parentVars - Parent workflow vars.
+ * @param parentDefaultAssistantId - Parent run's default Assistant.
+ * @param childVars - Vars about to be stored on the child.
+ */
+export declare function inheritAccessVars(parentVars: Record<string, unknown> | undefined, parentDefaultAssistantId: string | undefined, childVars: Record<string, unknown>): Record<string, unknown>;