@sema-agent/core/dist/core/synthetic-read-verdict.js

Stateless, task-oriented AI agent core

import { describeThrown, engineSettlementOf, refuseOutOfContractDecision } from "./tool-policy.js";
import { skillRowRefusal } from "./skill-grant.js";
import { applyPersistedTightening } from "./persisted-rule-arms.js";
import { readOrgRuleLane, readPersistedRuleLane } from "./rule-lane-reads.js";
import { ORG_ADJUDICATION_TIMEOUT_MS, settleOrgVerdictWithin } from "./permission-rule-org.js";
export const SYNTHETIC_READ_LAYERS = Object.freeze(["skill_rows", "narrowing", "caller_policy", "inherited_constraint", "persisted_rules", "org_rules"]);
export const SYNTHETIC_READ_UNANSWERABLE_CAUSES = Object.freeze(["threw", "timed_out", "approval_seat", "call_unreadable", "org_unavailable"]);
export function syntheticReadProbeId(face) {
    if (!/^[a-z][a-z-]*$/.test(face))
        throw new Error(`syntheticReadProbeId: the probe face must be a lowercase word (letters and hyphens), got ${JSON.stringify(face)}`);
    return `${face}-visibility-probe`;
}
const ABORTED = AbortSignal.abort();
export function createSyntheticReadJudge(layers) {
    return async (call, face, budget) => {
        const deadlineAt = budget?.deadlineAt ?? Date.now() + ORG_ADJUDICATION_TIMEOUT_MS;
        const left = () => Math.max(0, Math.min(ORG_ADJUDICATION_TIMEOUT_MS, deadlineAt - Date.now()));
        const req = {
            toolName: "Read",
            args: { file_path: call.file_path, ...(call.offset !== undefined ? { offset: call.offset } : {}), ...(call.limit !== undefined ? { limit: call.limit } : {}) },
            toolCallId: syntheticReadProbeId(face),
            ...(call.cwd !== undefined ? { cwd: call.cwd } : {}),
            ...(call.face !== undefined ? { face: call.face } : {}),
        };
        let unanswered;
        const cannot = (layer, cause, reason) => {
            unanswered ??= { verdict: "unanswerable", layer, cause, reason };
        };
        const spent = (layer) => {
            if (left() > 0)
                return false;
            cannot(layer, "timed_out", "the judgment's wait budget was spent before this layer was asked");
            return true;
        };
        const policyLayer = async (layer, policy, signal) => {
            if (spent(layer))
                return undefined;
            const waitMs = left();
            let timedOut = false;
            const TIMEOUT = Symbol("timeout");
            let d;
            try {
                d = await settleOrgVerdictWithin(Promise.resolve().then(() => policy.check(req, signal)), TIMEOUT, { ...(layers.signal !== undefined ? { signal: layers.signal } : {}), timeoutMs: waitMs, onFallback: () => void (timedOut = true) });
            }
            catch (err) {
                cannot(layer, "threw", describeThrown(err));
                return undefined;
            }
            if (d === TIMEOUT || timedOut) {
                cannot(layer, "timed_out", `no answer within ${waitMs}ms (or the run ended first)`);
                return undefined;
            }
            let read;
            try {
                read = refuseOutOfContractDecision(d);
            }
            catch (err) {
                cannot(layer, "threw", describeThrown(err));
                return undefined;
            }
            if (read.action !== "deny")
                return undefined;
            if (engineSettlementOf(d, req) !== undefined) {
                cannot(layer, "approval_seat", "the policy would ask an approver, who is never consulted for a visibility probe");
                return undefined;
            }
            return { verdict: "deny", layer, ...(read.message !== undefined ? { message: read.message } : {}) };
        };
        try {
            const refusal = skillRowRefusal(layers.skillGrants, req);
            if (refusal !== undefined)
                return { verdict: "deny", layer: "skill_rows", ...(refusal.message !== undefined ? { message: refusal.message } : {}) };
        }
        catch (err) {
            cannot("skill_rows", "threw", describeThrown(err));
        }
        if (layers.denyNarrowingPolicy !== undefined) {
            const v = await policyLayer("narrowing", layers.denyNarrowingPolicy, layers.signal);
            if (v !== undefined)
                return v;
        }
        if (layers.callerPolicy !== undefined) {
            const v = await policyLayer("caller_policy", layers.callerPolicy, ABORTED);
            if (v !== undefined)
                return v;
        }
        for (const parent of layers.inheritedPolicies ?? []) {
            if (parent === layers.callerPolicy)
                continue;
            const v = await policyLayer("inherited_constraint", parent, ABORTED);
            if (v !== undefined)
                return v;
        }
        if (layers.persistedRuleLane !== undefined && !spent("persisted_rules")) {
            const read = await readPersistedRuleLane(layers.persistedRuleLane, req, layers.signal, left());
            const tightened = applyPersistedTightening({ action: "allow" }, read).tightened;
            if (tightened === "deny")
                return { verdict: "deny", layer: "persisted_rules" };
            if (tightened === "unreadable")
                cannot("persisted_rules", "call_unreadable", read.reason ?? "the call could not be read against the rules");
        }
        if (layers.orgRuleLane !== undefined && !spent("org_rules")) {
            const org = await readOrgRuleLane(layers.orgRuleLane, req, layers.signal, left());
            if (org.status === "unavailable")
                cannot("org_rules", left() > 0 ? "org_unavailable" : "timed_out", org.disclosures.join("; ") || "organization governance could not be read");
            else if (org.verdict?.behavior === "deny")
                return { verdict: "deny", layer: "org_rules", message: `an organization policy rule (${org.verdict.rule}) denies it` };
        }
        return unanswered ?? { verdict: "no_objection" };
    };
}