@sema-agent/core/dist/core/read-only-shell-table.d.ts

Stateless, task-oriented AI agent core

/**
 * The READ-ONLY shell tables — the closed data the read-only reader (`read-only-shell.ts`) judges a
 * command against, transcribed from upstream's own tables (CC 2.1.250) and kept as DATA so the parity
 * question is answered by diffing two tables, never by reading two programs:
 *  - {@link READ_ONLY_COMMAND_TABLE} — the flag-vetted commands: a command (one or more leading words,
 *    `git status`, `gh pr view`, `grep`) with the closed set of flags it may carry, each flag's value
 *    ARITY, and where upstream carries one, its extra danger predicate over the remaining words
 *    (upstream `w3t` + `tqe` + `nqe` + `XGn` + `JGn` + `dmt`);
 *  - {@link READ_ONLY_BARE_PROGRAMS} — programs read-only under ANY literal arguments (upstream `jpe`);
 *  - {@link READ_ONLY_GLOB_PROGRAMS} — the programs a segment carrying a GLOB may still be read-only
 *    under (upstream `B3t`; a glob may expand to any name, so only a program that cannot write however
 *    it is named is admitted);
 *  - {@link READ_ONLY_EXACT_FORMS} / {@link READ_ONLY_BARE_ONLY} — whole-command forms (`node -v`) and
 *    programs admitted only bare (`pwd`) (upstream `N3t` / `D3t`);
 *  - {@link FIND_ACTION_PRIMARIES} / {@link FIND_VALUE_PRIMARIES} / {@link FIND_NEWER_PRIMARY} — the
 *    `find` primaries that ACT (write, execute) and the ones that take a value (upstream `I3t`/`smt`/`amt`);
 *  - {@link READ_ONLY_ENV_NAMES} — the environment variables a read-only command may be prefixed with
 *    (upstream `nH`: a variable that cannot change what a program DOES);
 *  - {@link XARGS_READ_ONLY_TARGETS} — the programs `xargs` may hand its input to (upstream `v3t`).
 *
 * NOT transcribed, each a stated gap rather than a silent one: `sed` (upstream vets the sed SCRIPT with a
 * dedicated analyzer; without it a `sed` is not read-only here — fail-closed), the Windows PowerShell table
 * and every Windows-only arm (UNC paths), and the two filesystem probes upstream runs beside the tables (a
 * bare-repository indicator check and a `.git` redirection check — a shell tool here has no filesystem seat).
 *
 * Every predicate over the remaining words receives the words AFTER the command's own (upstream's `t`),
 * dequoted. Upstream's substitution placeholders never appear here: a word carrying an expansion has
 * already taken the whole command out of the read-only reading before a table is consulted.
 */
import type { AssertAllKeysHandled } from "./ask-origin.js";
/** How many words a flag's VALUE takes, and what the value must look like (upstream `ni`): `none` — the flag
 *  takes no value (`--flag=x` is refused); `number` — one word of digits; `string` — one word, any text
 *  (a value that starts with `-` is refused: it is another flag); `char` — one word of length 1; `{}` and
 *  `EOF` — one word spelled exactly so (`xargs -I {}`, `xargs -E EOF`). Registered in docs/CLOSED-SETS.md. */
export declare const READ_ONLY_FLAG_ARITIES: readonly ["none", "number", "string", "char", "{}", "EOF"];
export type ReadOnlyFlagArity = (typeof READ_ONLY_FLAG_ARITIES)[number];
/** The disposition table over the arity set: does `value` satisfy the arity? (`none` accepts NO value.) */
export declare const FLAG_VALUE_ACCEPTS: {
    readonly none: () => boolean;
    readonly number: (value: string) => boolean;
    readonly string: () => boolean;
    readonly char: (value: string) => boolean;
    readonly "{}": (value: string) => boolean;
    readonly EOF: (value: string) => boolean;
};
/** Compile-time fence: `never` while every arity has a row. */
export type FlagArityTableCoversEveryArity = AssertAllKeysHandled<Exclude<ReadOnlyFlagArity, keyof typeof FLAG_VALUE_ACCEPTS>>;
/** One row of {@link READ_ONLY_COMMAND_TABLE}. */
export interface ReadOnlyCommandRow {
    /** Flag → the arity of its value. A flag not in the table refuses the command (a short cluster `-abc`
     *  is admitted only when every letter is a `none` flag). */
    readonly safeFlags: Readonly<Record<string, ReadOnlyFlagArity>>;
    /** `false`: a `--` word is skipped like any other rather than ending the flag walk (the words after it
     *  keep being vetted). Default: `--` ends the walk and the rest are operands. */
    readonly respectsDoubleDash?: false;
    /** Upstream carries a whole-text regex for this row; expressed here over the remaining words. */
    readonly wordsShape?: (args: readonly string[]) => boolean;
    /** Upstream's `additionalCommandIsDangerousCallback` over the remaining words: `true` refuses. */
    readonly dangerous?: (args: readonly string[]) => boolean;
}
export declare const dockerRetargetDanger: (args: readonly string[]) => boolean;
/**
 * The flag-vetted command table (upstream `w3t` and everything it spreads; `sed` withheld — see the module
 * note). Keys with a space are multi-word commands and are matched on the leading words.
 */
export declare const READ_ONLY_COMMAND_TABLE: Readonly<Record<string, ReadOnlyCommandRow>>;
/** Programs read-only under any LITERAL arguments (upstream `jpe`): `cat x`, `wc -l x`, `diff a b`, `sleep 3`…
 *  The two-word `docker ps` / `docker images` are matched on both words. */
export declare const READ_ONLY_BARE_PROGRAMS: readonly ["docker ps", "docker images", "cal", "uptime", "cat", "head", "tail", "wc", "stat", "strings", "hexdump", "od", "nl", "id", "uname", "free", "df", "du", "locale", "groups", "nproc", "basename", "dirname", "realpath", "cut", "paste", "tr", "column", "tac", "rev", "fold", "expand", "unexpand", "fmt", "comm", "cmp", "numfmt", "readlink", "diff", "true", "false", "sleep", "which", "type", "expr", "seq", "tsort", "pr"];
/** Programs a segment carrying a GLOB may still be read-only under (upstream `B3t`): the glob may name
 *  anything, so only a program that writes nothing whatever it is handed. */
export declare const READ_ONLY_GLOB_PROGRAMS: readonly ["ls", "cat", "head", "tail", "wc", "stat", "grep", "egrep", "fgrep", "diff", "du", "df", "echo", "strings", "hexdump", "od", "nl", "cut", "column", "tr", "tac", "rev", "cmp", "basename", "dirname", "realpath", "readlink", "sha256sum", "sha1sum", "md5sum", "cd"];
/** Whole-command forms admitted exactly as spelled (upstream `N3t`). */
export declare const READ_ONLY_EXACT_FORMS: readonly (readonly string[])[];
/** Programs admitted only BARE (upstream `D3t`: `pwd`, `whoami`, `alias` — with an operand `alias` DEFINES one). */
export declare const READ_ONLY_BARE_ONLY: readonly ["pwd", "whoami", "alias"];
/** `find` primaries that ACT — delete, execute, write a file (upstream `I3t`). */
export declare const FIND_ACTION_PRIMARIES: readonly ["-delete", "-exec", "-execdir", "-ok", "-okdir", "-fprint", "-fprint0", "-fls", "-fprintf", "-files0-from"];
/** `find` primaries that take ONE value word (the value is skipped, not vetted) (upstream `smt`). */
export declare const FIND_VALUE_PRIMARIES: readonly ["-name", "-iname", "-path", "-ipath", "-lname", "-ilname", "-regex", "-iregex", "-wholename", "-iwholename", "-samefile", "-newer", "-anewer", "-cnewer", "-mnewer", "-perm", "-user", "-group", "-uid", "-gid", "-size", "-type", "-xtype", "-fstype", "-inum", "-links", "-used", "-context", "-amin", "-cmin", "-mmin", "-atime", "-ctime", "-mtime", "-mindepth", "-maxdepth", "-printf", "-regextype", "-D", "-f", "-flags", "-Bnewer", "-Btime", "-Bmin", "-files0-from", "-xattrname"];
/** The `-newerXY` family, a value primary spelled by pattern (upstream `amt`). */
export declare const FIND_NEWER_PRIMARY: RegExp;
/** Environment variables a read-only command may be prefixed with (upstream `nH`): locale, colour, terminal
 *  and toolchain switches that change how output LOOKS, never what a program does to the filesystem. */
export declare const READ_ONLY_ENV_NAMES: readonly ["GOEXPERIMENT", "GOOS", "GOARCH", "CGO_ENABLED", "GO111MODULE", "RUST_BACKTRACE", "RUST_LOG", "NODE_ENV", "PYTHONUNBUFFERED", "PYTHONDONTWRITEBYTECODE", "PYTEST_DISABLE_PLUGIN_AUTOLOAD", "PYTEST_DEBUG", "ANTHROPIC_API_KEY", "LANG", "LANGUAGE", "LC_ALL", "LC_CTYPE", "LC_TIME", "CHARSET", "TERM", "COLORTERM", "NO_COLOR", "FORCE_COLOR", "TZ", "LS_COLORS", "LSCOLORS", "GREP_COLOR", "GREP_COLORS", "GCC_COLORS", "TIME_STYLE", "BLOCK_SIZE", "BLOCKSIZE", "COLUMNS", "LINES", "CLICOLOR", "CLICOLOR_FORCE", "CI", "DEBIAN_FRONTEND", "GIT_TERMINAL_PROMPT"];
/** The programs `xargs` may hand its input to and stay read-only (upstream `v3t`). */
export declare const XARGS_READ_ONLY_TARGETS: readonly ["echo", "printf", "wc", "grep", "egrep", "fgrep", "head", "tail"];