@peers-app/peers-sdk 0.21.7 → 0.23.0

package/dist/contracts/system/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = exports.DEVICE_OPERATIONS_MAX_TOOLS = exports.DEVICE_OPERATIONS_MAX_ROWS = exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = exports.DEVICE_OPERATIONS_CONTRACT_VERSION = void 0;
+exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = exports.getToolAccessControlContractDefinition = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = exports.DEVICE_OPERATIONS_MAX_TOOLS = exports.DEVICE_OPERATIONS_MAX_ROWS = exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = exports.DEVICE_OPERATIONS_CONTRACT_VERSION = void 0;
 /**
  * Built-in system contracts. Importing this barrel runs each module's
  * {@link registerSystemContract} side effect so the catalog is populated.
@@ -22,6 +22,7 @@ exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsCon
 require("./device-operations-contract");
 require("./logs-contract");
 require("./network-contracts");
+require("./tool-access-control-contract");
 var device_operations_contract_1 = require("./device-operations-contract");
 Object.defineProperty(exports, "DEVICE_OPERATIONS_CONTRACT_VERSION", { enumerable: true, get: function () { return device_operations_contract_1.DEVICE_OPERATIONS_CONTRACT_VERSION; } });
 Object.defineProperty(exports, "DEVICE_OPERATIONS_MAX_QUERY_LENGTH", { enumerable: true, get: function () { return device_operations_contract_1.DEVICE_OPERATIONS_MAX_QUERY_LENGTH; } });
@@ -36,3 +37,6 @@ Object.defineProperty(exports, "getLogsContractDefinition", { enumerable: true,
 Object.defineProperty(exports, "LOGS_CONTRACT_VERSION", { enumerable: true, get: function () { return logs_contract_1.LOGS_CONTRACT_VERSION; } });
 Object.defineProperty(exports, "resolveLogsContract", { enumerable: true, get: function () { return logs_contract_1.resolveLogsContract; } });
 __exportStar(require("./network-contracts"), exports);
+var tool_access_control_contract_1 = require("./tool-access-control-contract");
+Object.defineProperty(exports, "getToolAccessControlContractDefinition", { enumerable: true, get: function () { return tool_access_control_contract_1.getToolAccessControlContractDefinition; } });
+Object.defineProperty(exports, "TOOL_ACCESS_CONTROL_CONTRACT_VERSION", { enumerable: true, get: function () { return tool_access_control_contract_1.TOOL_ACCESS_CONTROL_CONTRACT_VERSION; } });

package/dist/contracts/system/tool-access-control-contract.d.ts

@@ -0,0 +1,35 @@
+import type { IContractConsumerBase } from "../contract-proxy";
+import type { IContractDefinition } from "../types";
+/** Version of the built-in System Tool Access Control contract. */
+export declare const TOOL_ACCESS_CONTROL_CONTRACT_VERSION = 1;
+/**
+ * Local-only host contract for approving or rejecting step-up tool access.
+ *
+ * Assistants never receive these tools. Remote device connections must not
+ * resolve this contract.
+ */
+export declare function getToolAccessControlContractDefinition(): IContractDefinition;
+/** Consumer-side TypeScript shape for System Tool Access Control. */
+export interface IToolAccessControlConsumer extends IContractConsumerBase {
+    tools: {
+        approve(input: {
+            approvalId: string;
+            nonce: string;
+            scope?: "once" | "thread" | "context";
+        }): Promise<{
+            result: unknown;
+        }>;
+        reject(input: {
+            approvalId: string;
+            nonce: string;
+        }): Promise<{
+            result: unknown;
+        }>;
+        listPending(input?: {
+            threadMessageId?: string;
+            workflowRunId?: string;
+        }): Promise<{
+            approvals: unknown[];
+        }>;
+    };
+}

package/dist/contracts/system/tool-access-control-contract.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = void 0;
+exports.getToolAccessControlContractDefinition = getToolAccessControlContractDefinition;
+const system_ids_1 = require("../../system-ids");
+const field_type_1 = require("../../types/field-type");
+const system_contracts_1 = require("../system-contracts");
+/** Version of the built-in System Tool Access Control contract. */
+exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = 1;
+const field = (name, type, description, opts = {}) => ({ name, type, description, ...opts });
+let definition;
+/**
+ * Local-only host contract for approving or rejecting step-up tool access.
+ *
+ * Assistants never receive these tools. Remote device connections must not
+ * resolve this contract.
+ */
+function getToolAccessControlContractDefinition() {
+    definition ??= {
+        contractId: system_ids_1.toolAccessControlContractId,
+        version: exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION,
+        devTag: "dev",
+        name: "System Tool Access Control",
+        description: "Approve or reject privileged tool calls requested by Assistants.",
+        tables: [],
+        tools: [
+            {
+                name: "approve",
+                usageDescription: "Approve a pending tool-access request and execute the frozen call.",
+                inputFields: [
+                    field("approvalId", field_type_1.FieldType.id, "Pending approval id."),
+                    field("nonce", field_type_1.FieldType.string, "Single-use nonce from the pending row."),
+                    field("scope", field_type_1.FieldType.string, "once, thread, or context.", { optional: true }),
+                ],
+                outputFields: [field("result", field_type_1.FieldType.object, "Approval and execution result.")],
+            },
+            {
+                name: "reject",
+                usageDescription: "Reject a pending tool-access request.",
+                inputFields: [
+                    field("approvalId", field_type_1.FieldType.id, "Pending approval id."),
+                    field("nonce", field_type_1.FieldType.string, "Single-use nonce from the pending row."),
+                ],
+                outputFields: [field("result", field_type_1.FieldType.object, "Rejection result.")],
+            },
+            {
+                name: "listPending",
+                usageDescription: "List pending tool-access approvals for a thread or workflow.",
+                inputFields: [
+                    field("threadMessageId", field_type_1.FieldType.id, "Thread root or parent user message.", {
+                        optional: true,
+                    }),
+                    field("workflowRunId", field_type_1.FieldType.id, "Workflow run id.", { optional: true }),
+                ],
+                outputFields: [
+                    field("approvals", field_type_1.FieldType.object, "Pending approval rows.", { isArray: true }),
+                ],
+            },
+        ],
+        observables: [],
+        events: [],
+    };
+    return definition;
+}
+(0, system_contracts_1.registerSystemContract)({
+    providerPackageId: system_ids_1.peersSystemPackageId,
+    contractId: system_ids_1.toolAccessControlContractId,
+    version: exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION,
+    getDefinition: getToolAccessControlContractDefinition,
+});

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

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { GroupMemberRole } from "./group-member-roles";
+/**
+ * Named access-level constants on the same 0–100 scale as {@link GroupMemberRole}.
+ *
+ * Tools and Assistants store an integer in this range. Most callers use these
+ * named values; custom policies may use any integer from 0 through 100.
+ *
+ * `Self` (100) is operational authority in a personal context (or a group
+ * Founder). It is not connection {@link TrustLevel}.
+ */
+export declare const AccessLevel: {
+    readonly None: 0;
+    readonly Reader: 20;
+    readonly Writer: 40;
+    readonly Admin: 60;
+    readonly Owner: 80;
+    readonly Self: 100;
+};
+/** One of the named {@link AccessLevel} constants. */
+export type NamedAccessLevel = (typeof AccessLevel)[keyof typeof AccessLevel];
+/**
+ * Fail-closed default for unclassified tools and Assistants.
+ *
+ * Missing metadata is treated as {@link AccessLevel.Self} so a new package
+ * tool cannot run until someone explicitly lowers its requirement.
+ */
+export declare const DEFAULT_ACCESS_LEVEL: 100;
+/** Inclusive minimum stored access level. */
+export declare const MIN_ACCESS_LEVEL = 0;
+/** Inclusive maximum stored access level. */
+export declare const MAX_ACCESS_LEVEL = 100;
+/**
+ * Zod schema for a stored access level: an integer from 0 through 100.
+ * Unspecified values default to {@link DEFAULT_ACCESS_LEVEL}.
+ */
+export declare const accessLevelSchema: z.ZodDefault<z.ZodNumber>;
+/**
+ * Return a human-readable label for an access-level integer.
+ *
+ * Exact named values return `Self`, `Owner`, `Admin`, `Writer`, `Reader`, or
+ * `None`. Values between named tiers append `+` to the next-lower name
+ * (for example `61` → `Admin+`). Out-of-range numbers return `None`.
+ *
+ * @param value - Access level to label.
+ */
+export declare function getAccessLevelLabel(value: number): string;
+/**
+ * Normalize a stored or missing access level to a safe integer.
+ *
+ * `undefined`, `null`, `NaN`, and non-integers become {@link DEFAULT_ACCESS_LEVEL}.
+ * Values outside 0–100 are clamped.
+ *
+ * @param value - Raw access level from a record or config.
+ */
+export declare function resolveAccessLevel(value: unknown): number;
+/**
+ * Map a {@link GroupMemberRole} onto the access-level scale.
+ *
+ * Numeric values already match except the top label: group `Founder` (100)
+ * is access {@link AccessLevel.Self}.
+ *
+ * @param role - Group membership role.
+ */
+export declare function accessLevelFromGroupRole(role: GroupMemberRole): number;
+/**
+ * Return the named access-level presets used by configuration UIs.
+ */
+export declare function listAccessLevelPresets(): ReadonlyArray<{
+    value: number;
+    label: string;
+}>;

package/dist/data/access-level.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.accessLevelSchema = exports.MAX_ACCESS_LEVEL = exports.MIN_ACCESS_LEVEL = exports.DEFAULT_ACCESS_LEVEL = exports.AccessLevel = void 0;
+exports.getAccessLevelLabel = getAccessLevelLabel;
+exports.resolveAccessLevel = resolveAccessLevel;
+exports.accessLevelFromGroupRole = accessLevelFromGroupRole;
+exports.listAccessLevelPresets = listAccessLevelPresets;
+const zod_1 = require("zod");
+const group_member_roles_1 = require("./group-member-roles");
+/**
+ * Named access-level constants on the same 0–100 scale as {@link GroupMemberRole}.
+ *
+ * Tools and Assistants store an integer in this range. Most callers use these
+ * named values; custom policies may use any integer from 0 through 100.
+ *
+ * `Self` (100) is operational authority in a personal context (or a group
+ * Founder). It is not connection {@link TrustLevel}.
+ */
+exports.AccessLevel = {
+    None: 0,
+    Reader: 20,
+    Writer: 40,
+    Admin: 60,
+    Owner: 80,
+    Self: 100,
+};
+/**
+ * Fail-closed default for unclassified tools and Assistants.
+ *
+ * Missing metadata is treated as {@link AccessLevel.Self} so a new package
+ * tool cannot run until someone explicitly lowers its requirement.
+ */
+exports.DEFAULT_ACCESS_LEVEL = exports.AccessLevel.Self;
+/** Inclusive minimum stored access level. */
+exports.MIN_ACCESS_LEVEL = 0;
+/** Inclusive maximum stored access level. */
+exports.MAX_ACCESS_LEVEL = 100;
+/**
+ * Zod schema for a stored access level: an integer from 0 through 100.
+ * Unspecified values default to {@link DEFAULT_ACCESS_LEVEL}.
+ */
+exports.accessLevelSchema = zod_1.z
+    .number()
+    .int()
+    .min(exports.MIN_ACCESS_LEVEL)
+    .max(exports.MAX_ACCESS_LEVEL)
+    .default(exports.DEFAULT_ACCESS_LEVEL);
+const ACCESS_LEVEL_LABELS = [
+    { level: exports.AccessLevel.Self, label: "Self" },
+    { level: exports.AccessLevel.Owner, label: "Owner" },
+    { level: exports.AccessLevel.Admin, label: "Admin" },
+    { level: exports.AccessLevel.Writer, label: "Writer" },
+    { level: exports.AccessLevel.Reader, label: "Reader" },
+    { level: exports.AccessLevel.None, label: "None" },
+];
+/**
+ * Return a human-readable label for an access-level integer.
+ *
+ * Exact named values return `Self`, `Owner`, `Admin`, `Writer`, `Reader`, or
+ * `None`. Values between named tiers append `+` to the next-lower name
+ * (for example `61` → `Admin+`). Out-of-range numbers return `None`.
+ *
+ * @param value - Access level to label.
+ */
+function getAccessLevelLabel(value) {
+    for (const entry of ACCESS_LEVEL_LABELS) {
+        if (value >= entry.level) {
+            return value === entry.level ? entry.label : `${entry.label}+`;
+        }
+    }
+    return "None";
+}
+/**
+ * Normalize a stored or missing access level to a safe integer.
+ *
+ * `undefined`, `null`, `NaN`, and non-integers become {@link DEFAULT_ACCESS_LEVEL}.
+ * Values outside 0–100 are clamped.
+ *
+ * @param value - Raw access level from a record or config.
+ */
+function resolveAccessLevel(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value)) {
+        return exports.DEFAULT_ACCESS_LEVEL;
+    }
+    if (value < exports.MIN_ACCESS_LEVEL)
+        return exports.MIN_ACCESS_LEVEL;
+    if (value > exports.MAX_ACCESS_LEVEL)
+        return exports.MAX_ACCESS_LEVEL;
+    return value;
+}
+/**
+ * Map a {@link GroupMemberRole} onto the access-level scale.
+ *
+ * Numeric values already match except the top label: group `Founder` (100)
+ * is access {@link AccessLevel.Self}.
+ *
+ * @param role - Group membership role.
+ */
+function accessLevelFromGroupRole(role) {
+    return role === group_member_roles_1.GroupMemberRole.Founder ? exports.AccessLevel.Self : role;
+}
+/**
+ * Return the named access-level presets used by configuration UIs.
+ */
+function listAccessLevelPresets() {
+    return ACCESS_LEVEL_LABELS.slice()
+        .reverse()
+        .map(({ level, label }) => ({ value: level, label }));
+}

package/dist/data/access-level.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/data/access-level.test.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const group_member_roles_1 = require("./group-member-roles");
+const access_level_1 = require("./access-level");
+describe("accessLevelSchema", () => {
+    it("defaults missing values to Self (100)", () => {
+        expect(access_level_1.accessLevelSchema.parse(undefined)).toBe(access_level_1.AccessLevel.Self);
+        expect(access_level_1.DEFAULT_ACCESS_LEVEL).toBe(100);
+    });
+    it("accepts custom integers between named tiers", () => {
+        expect(access_level_1.accessLevelSchema.parse(45)).toBe(45);
+    });
+    it("rejects values outside 0–100", () => {
+        expect(access_level_1.accessLevelSchema.safeParse(-1).success).toBe(false);
+        expect(access_level_1.accessLevelSchema.safeParse(101).success).toBe(false);
+        expect(access_level_1.accessLevelSchema.safeParse(40.5).success).toBe(false);
+    });
+});
+describe("getAccessLevelLabel", () => {
+    it("labels named tiers", () => {
+        expect((0, access_level_1.getAccessLevelLabel)(0)).toBe("None");
+        expect((0, access_level_1.getAccessLevelLabel)(20)).toBe("Reader");
+        expect((0, access_level_1.getAccessLevelLabel)(40)).toBe("Writer");
+        expect((0, access_level_1.getAccessLevelLabel)(60)).toBe("Admin");
+        expect((0, access_level_1.getAccessLevelLabel)(80)).toBe("Owner");
+        expect((0, access_level_1.getAccessLevelLabel)(100)).toBe("Self");
+    });
+    it("labels in-between values with +", () => {
+        expect((0, access_level_1.getAccessLevelLabel)(61)).toBe("Admin+");
+    });
+});
+describe("resolveAccessLevel", () => {
+    it("fail-closes invalid values to 100", () => {
+        expect((0, access_level_1.resolveAccessLevel)(undefined)).toBe(100);
+        expect((0, access_level_1.resolveAccessLevel)("40")).toBe(100);
+        expect((0, access_level_1.resolveAccessLevel)(Number.NaN)).toBe(100);
+    });
+    it("clamps out-of-range integers", () => {
+        expect((0, access_level_1.resolveAccessLevel)(-5)).toBe(0);
+        expect((0, access_level_1.resolveAccessLevel)(200)).toBe(100);
+    });
+});
+describe("accessLevelFromGroupRole", () => {
+    it("maps Founder to Self 100", () => {
+        expect((0, access_level_1.accessLevelFromGroupRole)(group_member_roles_1.GroupMemberRole.Founder)).toBe(access_level_1.AccessLevel.Self);
+        expect((0, access_level_1.accessLevelFromGroupRole)(group_member_roles_1.GroupMemberRole.Admin)).toBe(access_level_1.AccessLevel.Admin);
+    });
+});
+describe("listAccessLevelPresets", () => {
+    it("returns named presets in ascending order", () => {
+        expect((0, access_level_1.listAccessLevelPresets)().map((p) => p.value)).toEqual([0, 20, 40, 60, 80, 100]);
+    });
+});

package/dist/data/assistants.d.ts

@@ -1,10 +1,12 @@
 import { z } from "zod";
 import type { DataContext } from "../context/data-context";
+/** How an Assistant selects tools for each run. */
 export declare enum ToolInclusionStrategy {
     Fixed = "Fixed",
     Linked = "Linked",
     Relevant = "Relevant"
 }
+/** Zod schema for a persisted {@link IAssistant} row. */
 export declare const assistantSchema: z.ZodObject<{
     assistantId: z.ZodEffects<z.ZodString, string, string>;
     name: z.ZodString;
@@ -16,8 +18,10 @@ export declare const assistantSchema: z.ZodObject<{
     toolsToInclude: z.ZodDefault<z.ZodString>;
     toolInclusionStrategy: z.ZodDefault<z.ZodNativeEnum<typeof ToolInclusionStrategy>>;
     packageId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    accessLevel: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     name: string;
+    accessLevel: number;
     assistantId: string;
     createdAt: Date;
     assistantRunnerToolId: string;
@@ -34,6 +38,7 @@ export declare const assistantSchema: z.ZodObject<{
     assistantId: string;
     description?: string | undefined;
     packageId?: string | undefined;
+    accessLevel?: number | undefined;
     createdAt?: Date | undefined;
     updatedAt?: Date | undefined;
     assistantRunnerToolId?: string | undefined;
@@ -41,9 +46,16 @@ export declare const assistantSchema: z.ZodObject<{
     toolsToInclude?: string | undefined;
     toolInclusionStrategy?: ToolInclusionStrategy | undefined;
 }>;
+/** An Assistant definition stored in the Assistants table. */
 export type IAssistant = z.infer<typeof assistantSchema>;
+/**
+ * Accessor for the Assistants table.
+ *
+ * @param dataContext - Optional data context; defaults to the current singleton.
+ */
 export declare function Assistants(dataContext?: DataContext): import("..").Table<{
     name: string;
+    accessLevel: number;
     assistantId: string;
     createdAt: Date;
     assistantRunnerToolId: string;
@@ -66,8 +78,15 @@ export declare const userPrimaryAssistantVar: import("./persistent-vars").Persis
  * their own preference. Can be set by group admins. Synced to all group members.
  */
 export declare const groupPrimaryAssistantVar: import("./persistent-vars").PersistentVar<string | undefined>;
+/**
+ * Resolve the current user's primary Assistant, falling back to the group
+ * default and then the built-in Shell Assistant.
+ *
+ * @param dataContext - Optional data context for the lookup.
+ */
 export declare const getPrimaryAssistant: (dataContext?: DataContext) => Promise<{
     name: string;
+    accessLevel: number;
     assistantId: string;
     createdAt: Date;
     assistantRunnerToolId: string;
@@ -80,4 +99,9 @@ export declare const getPrimaryAssistant: (dataContext?: DataContext) => Promise
     packageId?: string | undefined;
     updatedAt?: Date | undefined;
 }>;
+/**
+ * Return Assistant ids mentioned in markdown (`<@assistant:name:id>`).
+ *
+ * @param message - Message markdown that may contain mentions.
+ */
 export declare function getAllAssistantIdsMentioned(message: string): Promise<string[]>;

package/dist/data/assistants.js

@@ -8,15 +8,18 @@ const user_context_singleton_1 = require("../context/user-context-singleton");
 const mentions_1 = require("../mentions");
 const system_ids_1 = require("../system-ids");
 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");
 const persistent_vars_1 = require("./persistent-vars");
+/** How an Assistant selects tools for each run. */
 var ToolInclusionStrategy;
 (function (ToolInclusionStrategy) {
     ToolInclusionStrategy["Fixed"] = "Fixed";
     ToolInclusionStrategy["Linked"] = "Linked";
     ToolInclusionStrategy["Relevant"] = "Relevant";
 })(ToolInclusionStrategy || (exports.ToolInclusionStrategy = ToolInclusionStrategy = {}));
+/** Zod schema for a persisted {@link IAssistant} row. */
 exports.assistantSchema = zod_1.z.object({
     assistantId: zod_types_1.zodPeerId,
     name: zod_1.z.string(),
@@ -47,6 +50,7 @@ exports.assistantSchema = zod_1.z.object({
         "- **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"),
+    accessLevel: access_level_1.accessLevelSchema.describe("Minimum user access to invoke this assistant, and the level it may run automatically. Unclassified assistants default to 100 (Self)."),
 });
 const metaData = {
     name: "Assistants",
@@ -55,8 +59,14 @@ const metaData = {
     fields: (0, types_1.schemaToFields)(exports.assistantSchema),
     iconClassName: "bi bi-person-fill-gear",
     indexes: [{ fields: ["name"] }],
+    versionNumber: 1,
 };
 (0, table_definitions_system_1.registerSystemTableDefinition)(metaData, exports.assistantSchema);
+/**
+ * Accessor for the Assistants table.
+ *
+ * @param dataContext - Optional data context; defaults to the current singleton.
+ */
 function Assistants(dataContext) {
     return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(metaData, exports.assistantSchema);
 }
@@ -70,6 +80,12 @@ exports.userPrimaryAssistantVar = (0, persistent_vars_1.groupUserVar)("userPrima
  * their own preference. Can be set by group admins. Synced to all group members.
  */
 exports.groupPrimaryAssistantVar = (0, persistent_vars_1.groupVar)("groupPrimaryAssistantId");
+/**
+ * Resolve the current user's primary Assistant, falling back to the group
+ * default and then the built-in Shell Assistant.
+ *
+ * @param dataContext - Optional data context for the lookup.
+ */
 const getPrimaryAssistant = async (dataContext) => {
     await exports.userPrimaryAssistantVar.loadingPromise;
     const userAssistantId = (0, exports.userPrimaryAssistantVar)();
@@ -91,6 +107,11 @@ const getPrimaryAssistant = async (dataContext) => {
     return fallback;
 };
 exports.getPrimaryAssistant = getPrimaryAssistant;
+/**
+ * Return Assistant ids mentioned in markdown (`<@assistant:name:id>`).
+ *
+ * @param message - Message markdown that may contain mentions.
+ */
 async function getAllAssistantIdsMentioned(message) {
     const mentions = (0, mentions_1.getAllMentions)(message);
     return mentions.filter((m) => m.kind === "assistant").map((m) => m.id);

package/dist/data/group-member-roles.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Numeric group membership roles. The same 0–100 scale is used for tool and
+ * Assistant {@link AccessLevel} values (`Founder` maps to access `Self`).
+ */
 export declare enum GroupMemberRole {
     None = 0,
     Reader = 20,
@@ -6,4 +10,9 @@ export declare enum GroupMemberRole {
     Owner = 80,
     Founder = 100
 }
+/**
+ * Return a human-readable group-role label, using `+` for in-between values.
+ *
+ * @param value - Numeric role or access-like integer.
+ */
 export declare function getRoleLabel(value: number): string;

package/dist/data/group-member-roles.js

@@ -2,6 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GroupMemberRole = void 0;
 exports.getRoleLabel = getRoleLabel;
+/**
+ * Numeric group membership roles. The same 0–100 scale is used for tool and
+ * Assistant {@link AccessLevel} values (`Founder` maps to access `Self`).
+ */
 var GroupMemberRole;
 (function (GroupMemberRole) {
     GroupMemberRole[GroupMemberRole["None"] = 0] = "None";
@@ -11,6 +15,11 @@ var GroupMemberRole;
     GroupMemberRole[GroupMemberRole["Owner"] = 80] = "Owner";
     GroupMemberRole[GroupMemberRole["Founder"] = 100] = "Founder";
 })(GroupMemberRole || (exports.GroupMemberRole = GroupMemberRole = {}));
+/**
+ * Return a human-readable group-role label, using `+` for in-between values.
+ *
+ * @param value - Numeric role or access-like integer.
+ */
 function getRoleLabel(value) {
     const roleEntries = Object.entries(GroupMemberRole)
         .filter(([_key, val]) => typeof val === "number")

package/dist/data/group-permissions.d.ts

@@ -1,8 +1,62 @@
+import type { DataContext } from "../context/data-context";
+import type { UserContext } from "../context/user-context";
 import { GroupMemberRole } from "./group-member-roles";
 import type { IGroupMember } from "./group-members";
 import type { IGroup } from "./groups";
 export { GroupMemberRole };
-export declare function getUserRole(groupId: string, userId: string): Promise<GroupMemberRole>;
+/**
+ * Return a user's {@link GroupMemberRole} in `groupId`.
+ *
+ * Missing groups and the group's founder resolve to {@link GroupMemberRole.Founder},
+ * which is how a personal context (no Groups row) becomes access 100.
+ *
+ * Prefer passing `userContext` from the provider that owns the data. The
+ * process singleton is only a fallback and is not awaited — multi-device
+ * tests never set it, and hanging here would stall contract calls.
+ *
+ * @param groupId - Group id, or the user's id for their personal context.
+ * @param userId - User whose role is requested.
+ * @param userContext - Provider-owned context. Falls back to {@link peekUserContext}.
+ * @throws If neither an explicit context nor the process singleton is available.
+ */
+export declare function getUserRole(groupId: string, userId: string, userContext?: UserContext): Promise<GroupMemberRole>;
+/**
+ * Resolve a group role from the signing public key of a Users record.
+ *
+ * Uses {@link peekUserContext}; throws if the process singleton is unset.
+ *
+ * @param groupId - Group or personal context id.
+ * @param publicKey - User public key that signed a record.
+ */
 export declare function getUserRoleFromPublicKey(groupId: string, publicKey: string): Promise<GroupMemberRole>;
+/**
+ * Return the current user's access level in `dataContext`.
+ *
+ * Personal contexts (no `groupId`) use the user's id and resolve to 100.
+ *
+ * @param dataContext - Context whose group/personal role is evaluated.
+ */
+export declare function getCurrentUserAccessLevel(dataContext: DataContext): Promise<number>;
+/**
+ * Return `userId`'s access level in `dataContext`.
+ *
+ * @param dataContext - Context whose group/personal role is evaluated.
+ * @param userId - User to resolve.
+ */
+export declare function getUserAccessLevel(dataContext: DataContext, userId: string): Promise<number>;
+/**
+ * Verify that a group record was signed by an Admin+ member (Founder to change founder).
+ *
+ * @param group - Proposed group record.
+ * @param oldGroup - Previous record when this is an update.
+ */
 export declare function verifyGroupSignature(group: IGroup, oldGroup?: IGroup): Promise<void>;
+/**
+ * Return whether a group-member write is signed by someone allowed to make it.
+ *
+ * @param groupId - Group the membership belongs to.
+ * @param newGroupMember - Proposed membership row.
+ * @param oldGroupMember - Previous row when this is an update.
+ * @param signerRole - Optional precomputed signer role.
+ */
 export declare function isGroupMemberSignatureValid(groupId: string, newGroupMember: IGroupMember, oldGroupMember?: IGroupMember, signerRole?: GroupMemberRole): Promise<boolean>;