@sema-agent/core/dist/agents/cross-session-judge.js

Stateless, task-oriented AI agent core

import { isPermissionModeClass } from "./cross-session-envelope.js";
export const CROSS_SESSION_INBOUND_SETTINGS = Object.freeze(["wake", "next-turn", "hold", "refuse"]);
export function isCrossSessionInboundSetting(value) {
    return typeof value === "string" && CROSS_SESSION_INBOUND_SETTINGS.includes(value);
}
const RANK = { wake: 0, "next-turn": 1, hold: 2, refuse: 3 };
const UNSET_BASELINE = "next-turn";
function readLayer(v) {
    if (v === undefined || v === null || v === "default")
        return { value: undefined };
    if (isCrossSessionInboundSetting(v))
        return { value: v };
    return { value: "invalid" };
}
export function resolveCrossSessionInboundSetting(layers) {
    const invalidLayers = [];
    let value;
    let decidedBy;
    for (const [name, raw] of [
        ["managed", layers.managed],
        ["user", layers.user],
    ]) {
        const { value: v } = readLayer(raw);
        if (v === "invalid") {
            invalidLayers.push(name);
            continue;
        }
        if (v !== undefined && value === undefined) {
            value = v;
            decidedBy = name;
        }
    }
    for (const raw of layers.repo ?? []) {
        const { value: v } = readLayer(raw);
        if (v === "invalid") {
            invalidLayers.push("repo");
            continue;
        }
        if (v === undefined)
            continue;
        if (RANK[v] > RANK[value ?? UNSET_BASELINE]) {
            value = v;
            decidedBy = "repo";
        }
        else if (v !== UNSET_BASELINE && value !== undefined && RANK[v] === RANK[value] && decidedBy !== "managed") {
            decidedBy = "repo";
        }
    }
    if (invalidLayers.length > 0 && RANK[value ?? UNSET_BASELINE] < RANK.hold) {
        value = "hold";
        decidedBy = "invalid";
    }
    return { ...(value !== undefined ? { value } : {}), ...(decidedBy !== undefined ? { decidedBy } : {}), invalidLayers };
}
export function principalInboundLayers(layers) {
    return { ...(layers.managed !== undefined ? { managed: layers.managed } : {}), ...(layers.user !== undefined ? { user: layers.user } : {}) };
}
export const CROSS_SESSION_HOLD_CAUSES = Object.freeze([
    "mode-mismatch",
    "no-mode-asserted",
    "explicit-setting",
    "managed-setting",
    "repo-setting",
    "invalid-setting",
    "bypass-default",
    "mode-unknown",
    "invalid-mode-attestation",
    "cross-principal-default",
]);
export function describeCrossSessionHoldCause(cause) {
    switch (cause) {
        case "mode-mismatch":
            return "The sending session's permission mode class doesn't match this session's, so it wasn't delivered automatically.";
        case "no-mode-asserted":
            return "The sender did not attest its permission mode, and this session bypasses permission prompts.";
        case "explicit-setting":
            return 'Your "crossSessionInbound" setting is "hold".';
        case "managed-setting":
            return `Your organization's managed settings set "crossSessionInbound" to "hold".`;
        case "repo-setting":
            return `This repository's settings set "crossSessionInbound" to "hold" (your own "next-turn" cannot override a repo tightening).`;
        case "invalid-setting":
            return 'A settings file has an unrecognized "crossSessionInbound" value (see the settings warning), so messages are held while it is present.';
        case "bypass-default":
            return "This session is not prompting for permissions.";
        case "mode-unknown":
            return "This session's permission mode could not be determined.";
        case "invalid-mode-attestation":
            return "The sender attested an unrecognized permission mode, so the message is held for your review.";
        case "cross-principal-default":
            return `The message came from another user through your organization's delivery gate, and "crossSessionInbound" is not set, so it is held for your review.`;
        default: {
            const _exhaustive = cause;
            void _exhaustive;
            throw new Error(`unreachable hold cause ${String(cause)}`);
        }
    }
}
function describeUnknown(value) {
    try {
        const text = typeof value === "string" ? JSON.stringify(value) : typeof value === "bigint" ? `${value}n` : typeof value === "object" && value !== null ? JSON.stringify(value) : String(value);
        return text.length > 80 ? `${text.slice(0, 80)}…` : text;
    }
    catch {
        return `[unrenderable ${typeof value}]`;
    }
}
function holdFor(cause, warning) {
    return { verdict: "hold", cause, message: describeCrossSessionHoldCause(cause), ...(warning !== undefined ? { warning } : {}) };
}
function causeOf(decidedBy) {
    switch (decidedBy) {
        case "managed":
            return "managed-setting";
        case "repo":
            return "repo-setting";
        case "invalid":
            return "invalid-setting";
        case "user":
        case undefined:
            return "explicit-setting";
        default: {
            const _exhaustive = decidedBy;
            void _exhaustive;
            throw new Error(`unreachable setting source ${String(decidedBy)}`);
        }
    }
}
export function judgeCrossSessionInbound(input) {
    const { setting, selfModeClass, sender } = input;
    if (setting.value === undefined && sender?.fromScope !== undefined)
        return holdFor("cross-principal-default");
    if (setting.value !== undefined) {
        switch (setting.value) {
            case "wake":
            case "next-turn":
                return { verdict: "deliver" };
            case "refuse":
                return { verdict: "refuse", cause: "opt-out" };
            case "hold": {
                const cause = causeOf(setting.decidedBy);
                return holdFor(cause, cause === "invalid-setting" ? `unrecognized "crossSessionInbound" value in: ${setting.invalidLayers.join(", ")}` : undefined);
            }
            default: {
                const _exhaustive = setting.value;
                void _exhaustive;
                throw new Error(`unreachable setting value ${String(setting.value)}`);
            }
        }
    }
    if (sender?.selfSent === true)
        return { verdict: "deliver" };
    if (selfModeClass === "unknown")
        return holdFor("mode-unknown");
    if (sender === undefined)
        return selfModeClass === "bypass" ? holdFor("bypass-default") : { verdict: "deliver" };
    if (sender.fromMode !== undefined) {
        if (!isPermissionModeClass(sender.fromMode)) {
            return holdFor("invalid-mode-attestation", `sender attested from-mode=${describeUnknown(sender.fromMode)} (expected bypass|prompting)`);
        }
        return sender.fromMode === selfModeClass ? { verdict: "deliver" } : holdFor("mode-mismatch");
    }
    return selfModeClass === "bypass" ? holdFor("no-mode-asserted") : { verdict: "deliver" };
}
export function foldPermissionModeClass(effective, askEffective) {
    const byAsk = (() => {
        switch (askEffective) {
            case "auto_allow":
                return "bypass";
            case "human_reachable":
            case "park_only":
            case "auto_deny":
                return "prompting";
            case "unresolved":
                return "unknown";
            default: {
                const _exhaustive = askEffective;
                void _exhaustive;
                throw new Error(`unreachable ask effective ${String(askEffective)}`);
            }
        }
    })();
    return effective === "bypassPermissions" ? "bypass" : byAsk;
}
export const PEER_SEND_VERDICT_CODES = Object.freeze([
    "peer_send.stale_socket",
    "peer_send.socket_busy",
    "peer_send.too_large",
    "peer_send.invalid_target",
    "peer_send.timeout",
    "peer_send.recipient_refuses",
    "peer_send.not_reachable",
    "peer_send.subscription_cap",
    "peer_send.send_uncertain",
    "peer_send.other",
]);
export function peerSendVerdictSeverity(code) {
    return code === "peer_send.send_uncertain" || code === "peer_send.recipient_refuses" || code === "peer_send.subscription_cap" ? "degraded" : "error";
}