@gaunt-sloth/core 2.0.0-alpha.9 → 2.0.0-beta.0

package/dist/core/shell/escalationSeverity.js

@@ -0,0 +1,89 @@
+/**
+ * The label above the framed reason.
+ *
+ * The heading now carries a sentence of the gate's own, so without this the model-authored prose
+ * beneath it could be read as a continuation of what the gate said. §6 wants the opposite: the
+ * reason is the rater's, quoted, and it is framed exactly like the command for the same reason.
+ */
+export const RATER_REASON_LABEL = "    the rater's own words:";
+const OUTCOME_DISPLAY = {
+    safe: {
+        heading: '✓ Auto-rater (safe): no harmful effect found — you are being asked for another reason.',
+        tone: 'notice',
+    },
+    destructive: {
+        heading: '⚠ Auto-rater (destructive): this can destroy work or data, but undoing it is possible from ' +
+            'inside this session.',
+        tone: 'warn',
+    },
+    catastrophic: {
+        heading: '⛔ Auto-rater (catastrophic): undoing this would need something OUTSIDE this session — ' +
+            'rescue media, a backup, a re-provision, or a restore from someone else.',
+        tone: 'danger',
+    },
+    attack: {
+        heading: "⛔ Auto-rater (attack): this command's own STRUCTURE looks hostile — it is shaped to " +
+            'deceive you, take credentials, weaken permissions or persist itself.',
+        tone: 'danger',
+    },
+};
+/** How to render {@link RaterOutcome} on an approval dialog. */
+export function describeRaterOutcome(outcome) {
+    return OUTCOME_DISPLAY[outcome];
+}
+/**
+ * [[TUI-C68]] §6.1 — **the phrase that runs an `attack`-rated command anyway.** The only string on
+ * the banner that is not a refusal.
+ *
+ * A typed phrase rather than a key, because an irreversible decision must not be reachable by the
+ * muscle memory built answering routine prompts. A key merely *disjoint from today's menu* stops
+ * being disjoint the moment someone binds one; a phrase is immune to any future binding. `run`
+ * alone was considered and rejected as the leading token of half of what anyone types into a
+ * terminal.
+ *
+ * The label is never `bypass`: that is a rung (§2.5) and a far broader thing — it turns off the
+ * rater, the escalation and the halt together, for every command, for the whole run — and a user
+ * must never read this banner as switching to it.
+ */
+export const RUN_ANYWAY_PHRASE = 'run anyway';
+/**
+ * §6.1 — does what the human typed grant this one command?
+ *
+ * **The whole matching rule, in one place both surfaces call**, so what the banner *says* is
+ * answerable and what a surface *accepts* cannot drift. Trimmed, lower-cased, compared whole:
+ * `RUN ANYWAY` and a phrase with surrounding spaces grant; `run`, `runanyway`, `run anyway please`
+ * and the phrase with a doubled inner space do not. No prefix, no initial, no `y`, no alias.
+ *
+ * **Everything that is not the phrase is a refusal, and that is the property the banner rests on.**
+ * An approval prompt grants only on an offered key and treats every other keystroke as a rejection;
+ * a text buffer inverts that by accumulating keystrokes instead of rejecting them, and a matcher
+ * this narrow is what puts it back — the buffer may hold anything at all, and only one value of it
+ * runs the command.
+ *
+ * Deliberately NOT whitespace-normalising the middle: a rule that repairs what the user typed is a
+ * rule that grants on something they did not type, and retyping a phrase costs nothing next to
+ * running this command by accident.
+ */
+export function grantsRunAnyway(typed) {
+    return typed.trim().toLowerCase() === RUN_ANYWAY_PHRASE;
+}
+/**
+ * §6.1 — the banner copy. A function rather than an exported object so one surface cannot mutate
+ * the strings another is about to paint.
+ */
+export function attackBannerCopy() {
+    return {
+        title: '⛔ RUN HALTED — the auto-rater rated this command an ATTACK',
+        heading: OUTCOME_DISPLAY.attack.heading,
+        irreversible: 'If you run it anyway, the consequences may be IRREVERSIBLE.',
+        controls: [
+            `To run this ONE command: type   ${RUN_ANYWAY_PHRASE}   and press Enter.`,
+            'Anything else stops the run: any other text, or Enter on its own.',
+            'Nothing is remembered either way — this command is rated again next time.',
+        ],
+        prompt: 'Your answer: ',
+        granted: 'Running this ONE command. The rung is unchanged, nothing was added to the allow-list, ' +
+            'and the next identical command is rated and halted again.',
+    };
+}
+//# sourceMappingURL=escalationSeverity.js.map

package/dist/core/shell/escalationSeverity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escalationSeverity.js","sourceRoot":"","sources":["../../../src/core/shell/escalationSeverity.ts"],"names":[],"mappings":"AA6DA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,4BAA4B,CAAC;AAE/D,MAAM,eAAe,GAA8C;IACjE,IAAI,EAAE;QACJ,OAAO,EACL,wFAAwF;QAC1F,IAAI,EAAE,QAAQ;KACf;IACD,WAAW,EAAE;QACX,OAAO,EACL,6FAA6F;YAC7F,sBAAsB;QACxB,IAAI,EAAE,MAAM;KACb;IACD,YAAY,EAAE;QACZ,OAAO,EACL,wFAAwF;YACxF,yEAAyE;QAC3E,IAAI,EAAE,QAAQ;KACf;IACD,MAAM,EAAE;QACN,OAAO,EACL,sFAAsF;YACtF,sEAAsE;QACxE,IAAI,EAAE,QAAQ;KACf;CACF,CAAC;AAEF,gEAAgE;AAChE,MAAM,UAAU,oBAAoB,CAAC,OAAqB;IACxD,OAAO,eAAe,CAAC,OAAO,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,YAAY,CAAC;AAE9C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,iBAAiB,CAAC;AAC1D,CAAC;AAqCD;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO;QACL,KAAK,EAAE,4DAA4D;QACnE,OAAO,EAAE,eAAe,CAAC,MAAM,CAAC,OAAO;QACvC,YAAY,EAAE,6DAA6D;QAC3E,QAAQ,EAAE;YACR,mCAAmC,iBAAiB,qBAAqB;YACzE,mEAAmE;YACnE,2EAA2E;SAC5E;QACD,MAAM,EAAE,eAAe;QACvB,OAAO,EACL,wFAAwF;YACxF,2DAA2D;KAC9D,CAAC;AACJ,CAAC"}

package/dist/core/shell/framing.d.ts

@@ -0,0 +1,190 @@
+/** Column count assumed when the surface cannot report one (not a TTY, a test, a pipe). */
+export declare const DEFAULT_FRAME_WIDTH = 80;
+/**
+ * Narrowest frame the gutter will produce, however small the terminal claims to be.
+ *
+ * Below it the gutter eats the row and the command becomes unreadable, which is its own way of
+ * hiding a payload — so a terminal narrower than this gets a frame it cannot fit rather than no
+ * frame at all. That trade costs the column-0 guarantee, and {@link narrowTerminalNotice} is what
+ * stops it costing it silently.
+ */
+export declare const MIN_FRAME_WIDTH = 20;
+/**
+ * The width to frame at on a terminal reporting `columns`.
+ *
+ * One column is held back because a row that fills the last cell wraps on some terminals, and the
+ * result is floored at {@link MIN_FRAME_WIDTH}. Both surfaces resolve their width here so they
+ * cannot come to disagree about how much of a command a human was shown.
+ */
+export declare function frameWidthFor(columns: number | undefined): number;
+/**
+ * The line a surface must paint when the terminal is too narrow for the frame to fit in it, or
+ * `undefined` when it fits.
+ *
+ * A guarantee that quietly stops holding is worse than one that says it stopped: below the floor
+ * {@link frameWidthFor} keeps the frame readable at the cost of rows wider than the terminal, the
+ * terminal wraps them, and a wrapped row puts untrusted text at column 0 — exactly what the gutter
+ * exists to prevent. The human is told rather than shown a dialog that still looks like it is
+ * guarding them.
+ *
+ * **Deliberately short, and only the consequence.** It is painted on a terminal of twenty columns
+ * or fewer, so it wraps to a few rows however it is worded and every word it does not need is
+ * another row of chrome between the reader and the command they are ruling on. It names what goes
+ * wrong rather than the width that caused it, because the width is not what the reader has to
+ * decide about; the reasoning belongs here, where it has room.
+ */
+export declare function narrowTerminalNotice(columns: number | undefined): string | undefined;
+/**
+ * Body lines shown before {@link frameUntrustedCommand} starts eliding.
+ *
+ * Sized so the extracted-site notices, the body and the menu are on screen **together** on a
+ * conventional 24-row terminal. That matters more than it looks: rule 3 puts the sites above the
+ * body specifically so the eye lands on them, and a body long enough to scroll them off the top
+ * defeats it. Bounding the body is safe here in a way the superseded single-line clamp was not,
+ * because what is elided is chosen *around the flagged sites* and the count of hidden lines is
+ * stated — the payload is what survives, not what is dropped.
+ */
+export declare const DEFAULT_FRAME_MAX_LINES = 20;
+/**
+ * Rows either of the escalation menu's sticky blocks may occupy — what *approve for this session /
+ * always* would remember, and what *always reject* would record.
+ *
+ * Exported so both surfaces bound them identically: two prompts that disagree about how much of a
+ * grant a human was shown is the drift one shared renderer exists to prevent.
+ *
+ * Four, because that is enough for the ordinary case — a one-line command is one row, its JSON
+ * entry two — while keeping an eighteen-line command from printing itself twice more underneath
+ * its own frame and pushing the menu off the screen. See {@link clampRows} for the measurement.
+ */
+export declare const STICKY_PREVIEW_MAX_ROWS = 4;
+/**
+ * Smallest content width the gutter will leave, whatever the terminal claims.
+ *
+ * Exported alongside {@link wrapToWidth}, so the tests that pin the wrap's floor can state this
+ * term rather than repeat the number and quietly drift from it.
+ */
+export declare const MIN_CONTENT_WIDTH = 4;
+/** What made the gate unable to resolve a command statically, at one position in it. */
+export type UntrustedSiteKind = 'command substitution' | 'composition';
+/** One extracted decision-relevant position in a command. */
+export interface UntrustedSite {
+    /** 1-based line number, matching the gutter the body renders with. */
+    line: number;
+    /** 1-based display column within that line. */
+    column: number;
+    kind: UntrustedSiteKind;
+    /** The literal token that was found — `$(`, a backtick, `&&`, `||`, `;` or `|`. */
+    token: string;
+    /** Neutralised text from the site onward, clipped for the notice line. */
+    excerpt: string;
+}
+export interface FrameOptions {
+    /** Terminal columns available. Rows are wrapped to fit; defaults to {@link DEFAULT_FRAME_WIDTH}. */
+    width?: number;
+    /** Body lines before elision; defaults to {@link DEFAULT_FRAME_MAX_LINES}. */
+    maxLines?: number;
+    /**
+     * Terminal ROWS this block may occupy, after wrapping. Unbounded when absent.
+     *
+     * Different from {@link maxLines}, and the difference is the whole reason it exists: `maxLines`
+     * bounds the block's *logical* lines, so a single line long enough to wrap forty times is one
+     * line and passes the budget untouched. What a screen has is rows.
+     *
+     * **It bounds `lines` only — `notices` are outside it**, so a block with extracted sites occupies
+     * this many rows plus its notices. That is not a gap today: `maxRows` is reached through
+     * {@link frameUntrustedText}, which extracts no sites, so those blocks have no notices to bound.
+     * A caller passing it to {@link frameUntrustedCommand} instead would get a bound that does not
+     * bound the whole block, and needs to widen this rather than assume the name.
+     */
+    maxRows?: number;
+}
+/** A block of untrusted text, ready to paint. */
+export interface FramedUntrustedText {
+    /**
+     * Renderer-owned lines to paint **above** the body — the extracted sites, and the statement of
+     * anything the elision hid. Empty when there is nothing to say.
+     */
+    notices: string[];
+    /**
+     * The body, one terminal row per element, each already carrying its gutter. A surface paints
+     * these verbatim and must not re-wrap them: the gutter is the column-0 guarantee, and a second
+     * wrap would put untrusted bytes back at column 0.
+     */
+    lines: string[];
+    /** Every site {@link findUnresolvableSites} found, whether or not its line survived elision. */
+    sites: UntrustedSite[];
+}
+/**
+ * Replace every control and format character with a visible, printable escape.
+ *
+ * Covers the C0 and C1 control ranges (`\p{Cc}` — which is NUL, BEL, BS, TAB, LF, CR, ESC, DEL and
+ * the 0x80–0x9F block including the one-byte CSI), the format characters (`\p{Cf}` — the bidi
+ * overrides that reorder what a reader sees, the zero-width joiners, the BOM), and the line and
+ * paragraph separators (`\p{Zl}`, `\p{Zp}`). Everything else is left exactly as written: this
+ * neutralises, it never sanitises, so the text a human rules on is the text that was proposed.
+ *
+ * The output alphabet is `\`, `x`, `u`, `{`, `}` and hex digits, none of which is a shell
+ * substitution or composition token — so escaping can neither create nor destroy a site that
+ * {@link findUnresolvableSites} would report.
+ */
+export declare function neutralizeUntrustedText(text: string): string;
+/**
+ * Collapse untrusted text to a single safe line, for the line-structured blocks that carry their
+ * meaning in their line breaks (the §5 negotiation transcript, the rating prompt's own transcript).
+ *
+ * Neutralisation runs **first**: JavaScript's `\s` covers LF, CR and TAB but not ESC, BEL, NUL, the
+ * C1 range or the bidi overrides, so collapsing whitespace alone leaves a screen-clearing sequence
+ * intact on a line that merely looks tidy.
+ */
+export declare function neutralizeToOneLine(text: string): string;
+/**
+ * Every position in `command` at which the gate could not statically resolve it: each command
+ * substitution (`$(` and a backtick) and each composition boundary (`;`, `&&`, `||`, `|`).
+ *
+ * **Deliberately not quote-aware.** A shell-accurate scanner would skip a `$(` inside single quotes
+ * — and the command that motivated this whole surface hid its payload in backticks inside *double*
+ * quotes, where the shell expands it. Over-reporting costs a line of notice; under-reporting is the
+ * incident. The scan is the same order of simplicity as the ambiguity preflight that actually caught
+ * that command, and for the same reason.
+ *
+ * Scanned over the neutralised lines so the reported line and column are the ones the reader can
+ * count to on the screen.
+ */
+export declare function findUnresolvableSites(command: string): UntrustedSite[];
+/**
+ * Frame the command the agent proposed: neutralised, gutter-numbered, wrapped to the terminal, its
+ * unresolvable sites listed above it, and elided around those sites if it is too long to show whole.
+ */
+export declare function frameUntrustedCommand(command: string, options?: FrameOptions): FramedUntrustedText;
+/**
+ * Frame a block of untrusted prose — the auto-rater's `reason`, or what a sticky choice will store.
+ *
+ * The same gutter and the same neutralisation as a command, and for the same reason: the rater's
+ * explanation is model-authored text on a dialog whose chrome it must not be able to forge. Site
+ * extraction does not run, because prose has no composition boundaries to point at; a block with no
+ * sites that overruns {@link FrameOptions.maxLines} keeps its head and states what it dropped.
+ */
+export declare function frameUntrustedText(text: string, options?: FrameOptions): FramedUntrustedText;
+/**
+ * Split one logical line into terminal rows of at most `width` columns.
+ *
+ * The wrap belongs here rather than to the terminal because a terminal's own wrap starts the
+ * continuation at column 0, which is the forgery this module exists to prevent: a single line long
+ * enough to wrap can otherwise lay attacker-chosen bytes flush-left, gutter and all bypassed.
+ *
+ * Measured and cut with the display-width helpers, never `.length` — a CJK ideograph or an emoji is
+ * one code point in two columns, and a row measured as fitting that does not fit is a row the
+ * terminal wraps back to column 0. Conservatively, so the same holds on a terminal that renders
+ * Ambiguous characters wide.
+ *
+ * The budget is floored at {@link MIN_CONTENT_WIDTH} here rather than taken on trust. The
+ * over-wide-cluster branch below escapes a cluster it cannot draw and re-measures it, which
+ * advances only if the budget can hold at least one escape character; at a budget of zero it
+ * re-escapes its own backslashes forever and the row never terminates. {@link frame} does pass a
+ * floored width, but a loop that terminates because of what its only caller happens to do is one
+ * the next caller silently breaks.
+ *
+ * Exported for tests, which pin that termination at a degenerate width — the one width the public
+ * entry points cannot produce.
+ */
+export declare function wrapToWidth(text: string, width: number): string[];