@peers-app/peers-sdk 0.21.7 → 0.23.0

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>;

package/dist/data/tool-access.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INFRASTRUCTURE_ACCESS_LEVEL = exports.TOOL_ACCESS_GRANT_TTL_MS = exports.TOOL_ACCESS_APPROVAL_TTL_MS = exports.RESERVED_ACCESS_VAR_KEYS = exports.HOST_APPROVED_APPROVAL_ID_VAR = exports.DIRECT_USER_INVOCATION_VAR = exports.ASSISTANT_ID_VAR = exports.ACCESS_ASSISTANT_ID_VAR = void 0;
+exports.decideToolAccess = decideToolAccess;
+exports.canInvokeAssistant = canInvokeAssistant;
+exports.hashToolArgs = hashToolArgs;
+exports.annotateToolAccessDescription = annotateToolAccessDescription;
+exports.recordAccessLevel = recordAccessLevel;
+exports.resolveDelegatedAccessLevel = resolveDelegatedAccessLevel;
+exports.isReservedAccessVarName = isReservedAccessVarName;
+exports.threadRootMessageId = threadRootMessageId;
+exports.approvalRequiredResult = approvalRequiredResult;
+exports.omitEphemeralAccessVars = omitEphemeralAccessVars;
+exports.omitReservedAccessVars = omitReservedAccessVars;
+exports.inheritAccessVars = inheritAccessVars;
+const keys_1 = require("../keys");
+const access_level_1 = require("./access-level");
+/** Workflow-run var naming the Assistant whose delegated authority applies. */
+exports.ACCESS_ASSISTANT_ID_VAR = "accessAssistantId";
+/** Workflow-run var used as a display / fallback Assistant id. */
+exports.ASSISTANT_ID_VAR = "assistantId";
+/** Workflow-run var set when the user invoked a tool directly (CLI/UI/RPC). */
+exports.DIRECT_USER_INVOCATION_VAR = "directUserInvocation";
+/** Workflow-run var pointing at a host-consumed approval that authorizes this run. */
+exports.HOST_APPROVED_APPROVAL_ID_VAR = "hostApprovedApprovalId";
+/**
+ * Host-owned access keys. Models must not set these via `set-variable` or
+ * `run-a-workflow` child vars.
+ */
+exports.RESERVED_ACCESS_VAR_KEYS = [
+    exports.ACCESS_ASSISTANT_ID_VAR,
+    exports.ASSISTANT_ID_VAR,
+    exports.DIRECT_USER_INVOCATION_VAR,
+    exports.HOST_APPROVED_APPROVAL_ID_VAR,
+];
+/** How long a pending approval stays actionable. */
+exports.TOOL_ACCESS_APPROVAL_TTL_MS = 15 * 60 * 1000;
+/** How long an approved thread- or context-scoped grant remains reusable. */
+exports.TOOL_ACCESS_GRANT_TTL_MS = 15 * 60 * 1000;
+/**
+ * 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.
+ */
+function decideToolAccess(args) {
+    const userAccessLevel = (0, access_level_1.resolveAccessLevel)(args.userAccessLevel);
+    const toolAccessLevel = (0, access_level_1.resolveAccessLevel)(args.toolAccessLevel);
+    const toolLabel = `${(0, access_level_1.getAccessLevelLabel)(toolAccessLevel)} (${toolAccessLevel})`;
+    const userLabel = `${(0, access_level_1.getAccessLevelLabel)(userAccessLevel)} (${userAccessLevel})`;
+    if (toolAccessLevel > userAccessLevel) {
+        return {
+            kind: "deny",
+            reason: `Tool requires ${toolLabel}, but the current user has ${userLabel}.`,
+        };
+    }
+    if (args.assistantAccessLevel == null) {
+        return { kind: "allow" };
+    }
+    const assistantAccessLevel = (0, access_level_1.resolveAccessLevel)(args.assistantAccessLevel);
+    if (args.hasMatchingGrant || toolAccessLevel <= assistantAccessLevel) {
+        return { kind: "allow" };
+    }
+    return {
+        kind: "approval_required",
+        reason: `Tool requires ${toolLabel}. ${(0, access_level_1.getAccessLevelLabel)(assistantAccessLevel)} (${assistantAccessLevel}) can request it; ${userLabel} must approve.`,
+    };
+}
+/**
+ * Return whether a user may invoke an Assistant in the current context.
+ *
+ * @param userAccessLevel - Current user's access.
+ * @param assistantAccessLevel - Assistant minimum / delegated level.
+ */
+function canInvokeAssistant(userAccessLevel, assistantAccessLevel) {
+    return (0, access_level_1.resolveAccessLevel)(userAccessLevel) >= (0, access_level_1.resolveAccessLevel)(assistantAccessLevel);
+}
+/**
+ * Canonical hash of tool arguments used to bind one-time approvals.
+ *
+ * @param args - Tool input object; `undefined` hashes as an empty object.
+ */
+function hashToolArgs(args) {
+    return (0, keys_1.hashObject)(args && typeof args === "object" && !Array.isArray(args) ? args : {});
+}
+/**
+ * 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.
+ */
+function annotateToolAccessDescription(usageDescription, accessLevel) {
+    const level = (0, access_level_1.resolveAccessLevel)(accessLevel);
+    const annotation = `Required access level: ${(0, access_level_1.getAccessLevelLabel)(level)} (${level}).`;
+    if (usageDescription.includes("Required access level:")) {
+        return usageDescription;
+    }
+    return `${usageDescription}\n\n${annotation}`;
+}
+/**
+ * Return the fail-closed access level for a record that may omit the field.
+ *
+ * @param record - Tool or Assistant-like object.
+ */
+function recordAccessLevel(record) {
+    return record?.accessLevel == null
+        ? access_level_1.DEFAULT_ACCESS_LEVEL
+        : (0, access_level_1.resolveAccessLevel)(record.accessLevel);
+}
+/**
+ * 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).
+ */
+function resolveDelegatedAccessLevel(args) {
+    if (args.directUser) {
+        return undefined;
+    }
+    const levels = [];
+    if (args.accessAssistantLevel != null) {
+        levels.push((0, access_level_1.resolveAccessLevel)(args.accessAssistantLevel));
+    }
+    if (args.defaultAssistantLevel != null) {
+        levels.push((0, access_level_1.resolveAccessLevel)(args.defaultAssistantLevel));
+    }
+    if (levels.length === 0) {
+        return access_level_1.AccessLevel.None;
+    }
+    return Math.min(...levels);
+}
+/**
+ * Return whether `name` is a host-owned access-control workflow var.
+ *
+ * @param name - Candidate variable name.
+ */
+function isReservedAccessVarName(name) {
+    return exports.RESERVED_ACCESS_VAR_KEYS.includes(name);
+}
+/**
+ * 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`.
+ */
+function threadRootMessageId(message) {
+    if (!message) {
+        return undefined;
+    }
+    return message.messageParentId || message.messageId;
+}
+/**
+ * Build the model-visible payload for a pending approval.
+ */
+function approvalRequiredResult(args) {
+    return {
+        status: "approval_required",
+        approvalId: args.approvalId,
+        toolId: args.toolId,
+        toolName: args.toolName,
+        requiredAccessLevel: args.requiredAccessLevel,
+        requiredAccessLabel: (0, access_level_1.getAccessLevelLabel)(args.requiredAccessLevel),
+        message: args.message,
+    };
+}
+/** Workflow plumbing / assistant-runner tools that must not block invocation. */
+exports.INFRASTRUCTURE_ACCESS_LEVEL = access_level_1.AccessLevel.None;
+/**
+ * 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 `{}`.
+ */
+function omitEphemeralAccessVars(vars) {
+    if (!vars) {
+        return {};
+    }
+    const next = { ...vars };
+    delete next[exports.DIRECT_USER_INVOCATION_VAR];
+    delete next[exports.HOST_APPROVED_APPROVAL_ID_VAR];
+    return next;
+}
+/**
+ * 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 `{}`.
+ */
+function omitReservedAccessVars(vars) {
+    const next = omitEphemeralAccessVars(vars);
+    delete next[exports.ACCESS_ASSISTANT_ID_VAR];
+    delete next[exports.ASSISTANT_ID_VAR];
+    return next;
+}
+/**
+ * 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.
+ */
+function inheritAccessVars(parentVars, parentDefaultAssistantId, childVars) {
+    const vars = parentVars || {};
+    const parentAccessId = (typeof vars[exports.ACCESS_ASSISTANT_ID_VAR] === "string" && vars[exports.ACCESS_ASSISTANT_ID_VAR]) ||
+        (typeof vars[exports.ASSISTANT_ID_VAR] === "string" && vars[exports.ASSISTANT_ID_VAR]) ||
+        parentDefaultAssistantId;
+    return {
+        ...omitReservedAccessVars(childVars),
+        [exports.ACCESS_ASSISTANT_ID_VAR]: parentAccessId,
+        [exports.ASSISTANT_ID_VAR]: parentAccessId,
+        [exports.DIRECT_USER_INVOCATION_VAR]: vars[exports.DIRECT_USER_INVOCATION_VAR] ?? false,
+    };
+}

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

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

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

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const access_level_1 = require("./access-level");
+const tool_access_1 = require("./tool-access");
+describe("decideToolAccess", () => {
+    it("allows a direct user call at or below their ceiling", () => {
+        expect((0, tool_access_1.decideToolAccess)({
+            userAccessLevel: access_level_1.AccessLevel.Self,
+            toolAccessLevel: access_level_1.AccessLevel.Admin,
+        }).kind).toBe("allow");
+    });
+    it("denies a tool above the user ceiling", () => {
+        const decision = (0, tool_access_1.decideToolAccess)({
+            userAccessLevel: access_level_1.AccessLevel.Writer,
+            toolAccessLevel: access_level_1.AccessLevel.Admin,
+            assistantAccessLevel: access_level_1.AccessLevel.Writer,
+        });
+        expect(decision.kind).toBe("deny");
+    });
+    it("allows an Assistant to run tools at or below its level", () => {
+        expect((0, tool_access_1.decideToolAccess)({
+            userAccessLevel: access_level_1.AccessLevel.Self,
+            assistantAccessLevel: access_level_1.AccessLevel.Writer,
+            toolAccessLevel: access_level_1.AccessLevel.Writer,
+        }).kind).toBe("allow");
+    });
+    it("requires approval when A < T <= U", () => {
+        const decision = (0, tool_access_1.decideToolAccess)({
+            userAccessLevel: access_level_1.AccessLevel.Self,
+            assistantAccessLevel: access_level_1.AccessLevel.Writer,
+            toolAccessLevel: access_level_1.AccessLevel.Admin,
+        });
+        expect(decision.kind).toBe("approval_required");
+    });
+    it("allows a matching grant to skip another prompt", () => {
+        expect((0, tool_access_1.decideToolAccess)({
+            userAccessLevel: access_level_1.AccessLevel.Self,
+            assistantAccessLevel: access_level_1.AccessLevel.Writer,
+            toolAccessLevel: access_level_1.AccessLevel.Admin,
+            hasMatchingGrant: true,
+        }).kind).toBe("allow");
+    });
+});
+describe("canInvokeAssistant", () => {
+    it("denies users below the Assistant level", () => {
+        expect((0, tool_access_1.canInvokeAssistant)(access_level_1.AccessLevel.Writer, access_level_1.AccessLevel.Admin)).toBe(false);
+        expect((0, tool_access_1.canInvokeAssistant)(access_level_1.AccessLevel.Admin, access_level_1.AccessLevel.Admin)).toBe(true);
+    });
+});
+describe("hashToolArgs", () => {
+    it("is stable for key order", () => {
+        expect((0, tool_access_1.hashToolArgs)({ b: 1, a: 2 })).toBe((0, tool_access_1.hashToolArgs)({ a: 2, b: 1 }));
+    });
+});
+describe("annotateToolAccessDescription", () => {
+    it("appends the required level once", () => {
+        const once = (0, tool_access_1.annotateToolAccessDescription)("Does a thing.", 40);
+        expect(once).toContain("Writer (40)");
+        expect((0, tool_access_1.annotateToolAccessDescription)(once, 40)).toBe(once);
+    });
+});
+describe("recordAccessLevel", () => {
+    it("defaults missing records to 100", () => {
+        expect((0, tool_access_1.recordAccessLevel)(undefined)).toBe(100);
+        expect((0, tool_access_1.recordAccessLevel)({})).toBe(100);
+        expect((0, tool_access_1.recordAccessLevel)({ accessLevel: 20 })).toBe(20);
+    });
+});
+describe("resolveDelegatedAccessLevel", () => {
+    it("omits an Assistant ceiling for direct user calls", () => {
+        expect((0, tool_access_1.resolveDelegatedAccessLevel)({
+            directUser: true,
+            accessAssistantLevel: access_level_1.AccessLevel.Writer,
+            defaultAssistantLevel: access_level_1.AccessLevel.Writer,
+        })).toBeUndefined();
+    });
+    it("takes the lower of access-assistant and default Assistant", () => {
+        expect((0, tool_access_1.resolveDelegatedAccessLevel)({
+            directUser: false,
+            accessAssistantLevel: access_level_1.AccessLevel.Admin,
+            defaultAssistantLevel: access_level_1.AccessLevel.Writer,
+        })).toBe(access_level_1.AccessLevel.Writer);
+    });
+    it("fails closed to None when no Assistant record resolved", () => {
+        expect((0, tool_access_1.resolveDelegatedAccessLevel)({ directUser: false })).toBe(access_level_1.AccessLevel.None);
+    });
+});
+describe("threadRootMessageId", () => {
+    it("uses the parent when present and the message itself when it is the root", () => {
+        expect((0, tool_access_1.threadRootMessageId)({
+            messageId: "00reply0000000000000000001",
+            messageParentId: "00root00000000000000000001",
+        })).toBe("00root00000000000000000001");
+        expect((0, tool_access_1.threadRootMessageId)({ messageId: "00root00000000000000000001" })).toBe("00root00000000000000000001");
+        expect((0, tool_access_1.threadRootMessageId)(undefined)).toBeUndefined();
+    });
+});
+describe("isReservedAccessVarName", () => {
+    it("matches host-owned access keys only", () => {
+        expect((0, tool_access_1.isReservedAccessVarName)(tool_access_1.DIRECT_USER_INVOCATION_VAR)).toBe(true);
+        expect((0, tool_access_1.isReservedAccessVarName)(tool_access_1.ASSISTANT_ID_VAR)).toBe(true);
+        expect((0, tool_access_1.isReservedAccessVarName)("cwd")).toBe(false);
+    });
+});
+describe("omitEphemeralAccessVars", () => {
+    it("strips one-shot host tickets and leaves other vars", () => {
+        expect((0, tool_access_1.omitEphemeralAccessVars)({
+            cwd: "/tmp",
+            [tool_access_1.DIRECT_USER_INVOCATION_VAR]: true,
+            [tool_access_1.HOST_APPROVED_APPROVAL_ID_VAR]: "00testapproval0000000001",
+        })).toEqual({ cwd: "/tmp" });
+        expect((0, tool_access_1.omitEphemeralAccessVars)(undefined)).toEqual({});
+    });
+});
+describe("omitReservedAccessVars", () => {
+    it("strips Assistant identity as well as host tickets", () => {
+        expect((0, tool_access_1.omitReservedAccessVars)({
+            cwd: "/tmp",
+            [tool_access_1.ACCESS_ASSISTANT_ID_VAR]: "assistant-a",
+            [tool_access_1.ASSISTANT_ID_VAR]: "assistant-a",
+            [tool_access_1.DIRECT_USER_INVOCATION_VAR]: true,
+        })).toEqual({ cwd: "/tmp" });
+    });
+});
+describe("inheritAccessVars", () => {
+    it("copies parent authority and does not let child vars escalate", () => {
+        const inherited = (0, tool_access_1.inheritAccessVars)({ [tool_access_1.ACCESS_ASSISTANT_ID_VAR]: "assistant-a", [tool_access_1.DIRECT_USER_INVOCATION_VAR]: false }, "assistant-parent", { [tool_access_1.ACCESS_ASSISTANT_ID_VAR]: "assistant-b", [tool_access_1.DIRECT_USER_INVOCATION_VAR]: true, foo: 1 });
+        expect(inherited[tool_access_1.ACCESS_ASSISTANT_ID_VAR]).toBe("assistant-a");
+        expect(inherited[tool_access_1.ASSISTANT_ID_VAR]).toBe("assistant-a");
+        expect(inherited[tool_access_1.DIRECT_USER_INVOCATION_VAR]).toBe(false);
+        expect(inherited.foo).toBe(1);
+    });
+    it("does not copy a host-approved approval id onto the child", () => {
+        const inherited = (0, tool_access_1.inheritAccessVars)({ [tool_access_1.HOST_APPROVED_APPROVAL_ID_VAR]: "00parentapproval00000001" }, "assistant-parent", { [tool_access_1.HOST_APPROVED_APPROVAL_ID_VAR]: "00childapproval000000001", foo: 1 });
+        expect(inherited[tool_access_1.HOST_APPROVED_APPROVAL_ID_VAR]).toBeUndefined();
+        expect(inherited.foo).toBe(1);
+    });
+    it("ignores a child-supplied assistantId", () => {
+        const inherited = (0, tool_access_1.inheritAccessVars)({ [tool_access_1.ACCESS_ASSISTANT_ID_VAR]: "assistant-a" }, "assistant-parent", {
+            [tool_access_1.ASSISTANT_ID_VAR]: "assistant-admin",
+            foo: 1,
+        });
+        expect(inherited[tool_access_1.ASSISTANT_ID_VAR]).toBe("assistant-a");
+        expect(inherited[tool_access_1.ACCESS_ASSISTANT_ID_VAR]).toBe("assistant-a");
+    });
+});
+describe("approvalRequiredResult", () => {
+    it("includes a model-visible status", () => {
+        const result = (0, tool_access_1.approvalRequiredResult)({
+            approvalId: "000peers0tacapprove000001",
+            toolId: "000peers0tool00000sendmsg",
+            toolName: "send-message",
+            requiredAccessLevel: 60,
+            message: "Needs approval",
+        });
+        expect(result.status).toBe("approval_required");
+        expect(result.requiredAccessLabel).toBe("Admin");
+    });
+});

package/dist/data/tools.d.ts

@@ -1,10 +1,12 @@
 import { z } from "zod";
 import type { DataContext } from "../context/data-context";
+/** Shape of a tool input, output, or config schema. */
 export declare enum IOSchemaType {
     none = "none",
     simple = "simple",
     complex = "complex"
 }
+/** Zod schema for {@link IOSchema}. */
 export declare const ioSchema: z.ZodObject<{
     type: z.ZodNativeEnum<typeof IOSchemaType>;
     fields: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -55,7 +57,9 @@ export declare const ioSchema: z.ZodObject<{
         subType?: string | undefined;
     }[] | undefined;
 }>;
+/** Field list plus complexity for a tool IO surface. */
 export type IOSchema = z.infer<typeof ioSchema>;
+/** Zod schema for a persisted {@link ITool} row. */
 export declare const toolSchema: z.ZodObject<{
     toolId: z.ZodEffects<z.ZodString, string, string>;
     name: z.ZodString;
@@ -215,6 +219,7 @@ export declare const toolSchema: z.ZodObject<{
     codeRepository: z.ZodOptional<z.ZodString>;
     isAssistantRunner: z.ZodOptional<z.ZodBoolean>;
     packageId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    accessLevel: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     code: string;
     name: string;
@@ -244,6 +249,7 @@ export declare const toolSchema: z.ZodObject<{
             subType?: string | undefined;
         }[];
     };
+    accessLevel: number;
     packageId?: string | undefined;
     detailedDescription?: string | undefined;
     configSchema?: {
@@ -305,14 +311,22 @@ export declare const toolSchema: z.ZodObject<{
     } | undefined;
     codeRepository?: string | undefined;
     isAssistantRunner?: boolean | undefined;
+    accessLevel?: number | undefined;
 }>;
+/** A tool definition stored in the Tools table. */
 export type ITool = z.infer<typeof toolSchema>;
+/** Runnable tool: persisted metadata plus the in-memory implementation. */
 export interface IToolInstance {
     tool: ITool;
     toolFn: (...args: any[]) => any;
     inputSchema?: z.ZodObject<any>;
     outputSchema?: z.ZodObject<any>;
 }
+/**
+ * Accessor for the Tools table.
+ *
+ * @param dataContext - Optional data context; defaults to the current singleton.
+ */
 export declare function Tools(dataContext?: DataContext): import("..").Table<{
     code: string;
     name: string;
@@ -342,6 +356,7 @@ export declare function Tools(dataContext?: DataContext): import("..").Table<{
             subType?: string | undefined;
         }[];
     };
+    accessLevel: number;
     packageId?: string | undefined;
     detailedDescription?: string | undefined;
     configSchema?: {

package/dist/data/tools.js

@@ -6,18 +6,22 @@ const zod_1 = require("zod");
 const user_context_singleton_1 = require("../context/user-context-singleton");
 const field_type_1 = require("../types/field-type");
 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");
+/** Shape of a tool input, output, or config schema. */
 var IOSchemaType;
 (function (IOSchemaType) {
     IOSchemaType["none"] = "none";
     IOSchemaType["simple"] = "simple";
     IOSchemaType["complex"] = "complex";
 })(IOSchemaType || (exports.IOSchemaType = IOSchemaType = {}));
+/** Zod schema for {@link IOSchema}. */
 exports.ioSchema = zod_1.z.object({
     type: zod_1.z.nativeEnum(IOSchemaType),
     fields: field_type_1.fieldSchema.array().default([]),
 });
+/** Zod schema for a persisted {@link ITool} row. */
 exports.toolSchema = zod_1.z.object({
     toolId: zod_types_1.zodPeerId,
     name: zod_1.z.string().describe("The name of the tool"),
@@ -44,6 +48,7 @@ exports.toolSchema = zod_1.z.object({
         .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"),
+    accessLevel: access_level_1.accessLevelSchema.describe("Required access level (0-100) to run this tool. Unclassified tools default to 100 (Self)."),
 });
 const metaData = {
     name: "Tools",
@@ -52,8 +57,14 @@ const metaData = {
     fields: (0, types_1.schemaToFields)(exports.toolSchema),
     iconClassName: "bi bi-tools",
     indexes: [{ fields: ["name"] }, { fields: ["isAssistantRunner"] }],
+    versionNumber: 1,
 };
 (0, table_definitions_system_1.registerSystemTableDefinition)(metaData, exports.toolSchema);
+/**
+ * Accessor for the Tools table.
+ *
+ * @param dataContext - Optional data context; defaults to the current singleton.
+ */
 function Tools(dataContext) {
     return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(metaData, exports.toolSchema);
 }