@sema-agent/core/dist/tools/fs/shell-read-device.js

Stateless, task-oriented AI agent core

const STANDARD_DEVICES = [
    { spelled: /^\/dev\/null$/ },
    { spelled: /^\/dev\/stdin$/, descriptor: () => 0 },
    { spelled: /^\/dev\/stdout$/, descriptor: () => 1 },
    { spelled: /^\/dev\/stderr$/, descriptor: () => 2 },
    { spelled: /^\/dev\/tty$/ },
    { spelled: /^\/dev\/fd\/(\d+)$/, descriptor: (m) => Number(m[1]) },
    { spelled: /^\/proc\/self\/fd\/([0-2])$/, descriptor: (m) => Number(m[1]) },
];
export function standardDeviceOf(spelled) {
    for (const row of STANDARD_DEVICES) {
        const match = row.spelled.exec(spelled);
        if (match !== null)
            return row.descriptor === undefined ? {} : { descriptor: row.descriptor(match) };
    }
    return undefined;
}
export const GENERATOR_DEVICES = new Set(["/dev/zero", "/dev/random", "/dev/urandom", "/dev/full"]);
export const newLineDescriptors = () => ({ unknown: false, named: false, bound: new Map() });
export function descriptorsBoundBy(r) {
    if (r.fd !== undefined)
        return [r.fd];
    if (r.op === "&>" || r.op === "&>>")
        return [1, 2];
    return [r.op === "<" || r.op === "<<<" || r.op === "<&" ? 0 : 1];
}
export function bindDescriptors(into, r) {
    for (const fd of descriptorsBoundBy(r))
        into.bound.set(fd, (into.bound.get(fd) ?? 0) + 1);
}
const NAMED_DESCRIPTOR_WORD = /^\{[A-Za-z_][A-Za-z0-9_]*\}$/;
export const isNamedDescriptorWord = (raw) => NAMED_DESCRIPTOR_WORD.test(raw);
function reboundBy(text, descriptor, self) {
    if (text.unknown || (text.named && descriptor >= 3))
        return true;
    return (text.bound.get(descriptor) ?? 0) - (self.includes(descriptor) ? 1 : 0) > 0;
}
export function standardDeviceUnrebound(spelled, text, self) {
    const device = standardDeviceOf(spelled);
    return device !== undefined && (device.descriptor === undefined || !reboundBy(text, device.descriptor, self));
}
export const OPENED_PROVENANCES = new Set(["operand", "option_value", "stdin_redirect", "write_redirect_target", "unlisted_word", "traversal_root"]);
export function passesUnasked(candidate) {
    return candidate.device === true && (candidate.face !== "write" || candidate.through === true);
}
const SHELL_CODE_VERBS = new Set(["eval", "source", "."]);
function collectDescriptors(plan, into) {
    if (plan.unreadable !== undefined)
        into.unknown = true;
    for (const segment of plan.segments) {
        if (segment.declines.length > 0 || segment.unreadProgramText !== undefined)
            into.unknown = true;
        if (segment.verb !== undefined && SHELL_CODE_VERBS.has(segment.verb.basename) && segment.nested.length === 0)
            into.unknown = true;
        if (segment.reads.some((c) => c.provenance === "program_path" && c.expands === "unresolvable"))
            into.unknown = true;
        for (const r of segment.redirects)
            bindDescriptors(into, r);
        if (segment.argv.some((w) => isNamedDescriptorWord(w.raw)))
            into.named = true;
        const text = segment.text.replace(/\\\r?\n/g, "");
        if (/(?:^|[^<])<<(?!<)/.test(text)) {
            if (/\d<<(?!<)/.test(text))
                into.unknown = true;
            else
                into.bound.set(0, (into.bound.get(0) ?? 0) + 1);
        }
        for (const n of segment.nested)
            collectDescriptors(n, into);
    }
}
export function descriptorsOfPlan(plan) {
    const into = newLineDescriptors();
    collectDescriptors(plan, into);
    return into;
}
export function markStandardDevices(plan) {
    const text = descriptorsOfPlan(plan);
    const mark = (c, self) => {
        if (c.device === true || c.expands !== false || c.denyOnly === true || c.speculative !== undefined || !OPENED_PROVENANCES.has(c.provenance))
            return c;
        return standardDeviceUnrebound(c.spelled, text, self) ? { ...c, device: true } : c;
    };
    const marked = new Map();
    const walk = (p) => {
        const seen = marked.get(p);
        if (seen !== undefined)
            return seen;
        const out = markedPlan(p);
        marked.set(p, out);
        return out;
    };
    const markedPlan = (p) => ({
        ...p,
        segments: p.segments.map((s) => {
            const useOf = (c) => {
                const r = s.redirects.find((x) => x.target !== undefined && x.target.raw === c.raw && x.target.provenance === c.provenance);
                return r === undefined ? [] : descriptorsBoundBy(r);
            };
            return {
                ...s,
                reads: s.reads.map((c) => mark(c, c.provenance === "stdin_redirect" ? useOf(c) : [])),
                redirects: s.redirects.map((r) => (r.target === undefined ? r : { ...r, target: mark(r.target, descriptorsBoundBy(r)) })),
                nested: s.nested.map(walk),
            };
        }),
    });
    return walk(plan);
}