@agentwhy/cli 0.0.0-dev

package/dist/report/watch/preferences.js

@@ -0,0 +1,100 @@
+import { isJsonObject, parseJsonObject } from '../../shared/json.js';
+import { ALERT_THRESHOLDS } from './agent-alert.js';
+import { CLEAN_MODES, NOTICE_CHANNELS, NOTICE_LANGS, SAID_AS, } from './notice-choices.js';
+export const NO_PREFERENCES = { defaults: {}, projects: {} };
+/**
+ * A file this tool wrote, read back. Anything else is `unusable`: a preferences file is not a place to guess, and
+ * the built-in answers are a better outcome than a threshold read out of a shape nobody recognised. A missing file
+ * is not unusable - nobody has chosen anything yet, which is exactly what the built-in answers are for.
+ */
+export function readPreferences(text) {
+    if (text === undefined)
+        return { kind: 'read', preferences: NO_PREFERENCES };
+    const parsed = parseJsonObject(text);
+    if (parsed === undefined)
+        return { kind: 'unusable' };
+    const defaults = choicesIn(parsed.defaults);
+    const projects = isJsonObject(parsed.projects) ? parsed.projects : {};
+    if (defaults === undefined || (parsed.projects !== undefined && !isJsonObject(parsed.projects)))
+        return { kind: 'unusable' };
+    const perProject = {};
+    for (const [directory, chosen] of Object.entries(projects)) {
+        const choices = choicesIn(chosen);
+        if (choices === undefined)
+            return { kind: 'unusable' };
+        perProject[directory] = choices;
+    }
+    return { kind: 'read', preferences: { defaults, projects: perProject } };
+}
+/** The file as it is written: the same shape this reads, with the keys a version of this tool knows. */
+export function writtenPreferences(preferences) {
+    const projects = Object.fromEntries(Object.entries(preferences.projects)
+        .filter(([, choices]) => Object.keys(choices).length > 0)
+        .sort(([one], [other]) => one.localeCompare(other)));
+    return `${JSON.stringify({ defaults: preferences.defaults, projects }, undefined, 2)}\n`;
+}
+/**
+ * The choices that apply where a session runs (R24): this project's, over this person's, over nothing at all. The
+ * flags a hook's command line carries are applied after these, by the caller - someone who wrote a flag meant it.
+ *
+ * A project is matched by directory, and the longest match wins: a session's working directory may be a directory
+ * inside the project the choice was made for, and a choice made for a project holds everywhere in it.
+ */
+export function preferencesFor(preferences, directory) {
+    const project = directory === undefined ? undefined : longestMatch(preferences.projects, directory);
+    return { ...preferences.defaults, ...(project ?? {}) };
+}
+/** The same choices with one project's answers replaced, for the writer. An empty set of answers takes it out. */
+export function withProjectChoices(preferences, directory, choices) {
+    const { [directory]: _replaced, ...others } = preferences.projects;
+    return {
+        defaults: preferences.defaults,
+        projects: Object.keys(choices).length === 0 ? others : { ...others, [directory]: choices },
+    };
+}
+/**
+ * The one project entry that governs a directory, the same way `preferencesFor` picks it: by the longest ancestor
+ * match, never by an exact key alone. A directory inside a project a choice was made for is still inside it.
+ */
+export function longestMatch(projects, directory) {
+    const inside = Object.keys(projects)
+        .filter((project) => directory === project || directory.startsWith(project.endsWith('/') ? project : `${project}/`))
+        .sort((one, other) => other.length - one.length);
+    return inside[0] === undefined ? undefined : projects[inside[0]];
+}
+/** One set of answers, or `undefined` where a key holds something this version does not recognise. */
+function choicesIn(value) {
+    if (value === undefined)
+        return {};
+    if (!isJsonObject(value))
+        return undefined;
+    const chosen = value;
+    const on = oneOf(chosen.on, ALERT_THRESHOLDS);
+    const clean = oneOf(chosen.clean, CLEAN_MODES);
+    const say = oneOf(chosen.say, SAID_AS);
+    const notify = channelsIn(chosen.notify);
+    const lang = oneOf(chosen.lang, NOTICE_LANGS);
+    if (on === 'unknown' || clean === 'unknown' || say === 'unknown' || notify === 'unknown' || lang === 'unknown')
+        return undefined;
+    return {
+        ...(on === undefined ? {} : { on }),
+        ...(clean === undefined ? {} : { clean }),
+        ...(say === undefined ? {} : { say }),
+        ...(notify === undefined ? {} : { notify }),
+        ...(lang === undefined ? {} : { lang }),
+    };
+}
+function oneOf(value, known) {
+    if (value === undefined)
+        return undefined;
+    const found = known.find((candidate) => candidate === value);
+    return found ?? 'unknown';
+}
+function channelsIn(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.length === 0)
+        return 'unknown';
+    const channels = value.map((name) => NOTICE_CHANNELS.find((channel) => channel === name));
+    return channels.includes(undefined) ? 'unknown' : [...new Set(channels)];
+}

package/dist/report/watch/render/instruction-words.js

@@ -0,0 +1,54 @@
+/**
+ * What the session's own agent is asked to say, when a finding is set to be said by it
+ * (`specs/2026-09-21-the-agent-tells-you.md` §5, R12, R12a, R12b). These are the words eleven sessions of eleven
+ * relayed, and they are the third version: the two before them were refused, and for reasons worth keeping in view.
+ *
+ * - **It is agentwhy's finding, passed on as agentwhy's.** The first version told the agent to assert it in its own
+ *   voice, and a session refused: it was being told to state as fact something it could not check.
+ * - **Nothing is forbidden but going back to the file.** That same version forbade the agent to confirm anything,
+ *   which - together with the claim above - is what an injection asks for, and was named as such.
+ * - **No link.** A version carrying a `file://` address to a page outside the project lost the agent on that alone
+ *   (B9g), so the offer is a command, named as what it is.
+ * - **Only what the records establish.** A session handed a claim that did not match its own context refused it and
+ *   said so to the person (R12b). The consequence is worded as what the records show - the conversation and the
+ *   session's own files - and not as a fact about a provider's infrastructure.
+ */
+export function instructionFor(files, command) {
+    const named = files.slice(0, NAMED_AT_MOST);
+    const rest = files.length - named.length;
+    const which = named.length === 0
+        ? 'a protected file'
+        : `the protected ${named.length === 1 ? 'file' : 'files'} ${list(named)}${rest === 0 ? '' : ` and ${rest} more`}`;
+    // What the agent is asked not to do is said about the same files it was just told about, in the same words.
+    const them = named.length <= 1 ? 'it' : 'them';
+    return [
+        `agentwhy, the local tool this user runs, checked this turn: a value from ${which} is in this conversation.`,
+        'Tell the user, in one short message in the language of this conversation, that agentwhy found this, what it',
+        'means - the value went wherever this conversation goes and stays in the session records kept on this machine,',
+        'so deleting messages does not recall it - and that rotating that credential where it was issued is what undoes',
+        `it. You read ${named.length === 0 ? 'it' : which} in this conversation, so you can see the finding yourself.`,
+        `Do not open or read ${them} again, and do not repeat the value.`,
+        `Then ask whether to open agentwhy's report for this session, and run \`${command}\` only if they say yes.`,
+        'Do not continue the earlier task in this message.',
+    ].join(' ');
+}
+/**
+ * How many files the instruction names before it counts the rest. Three keeps it inside what a person reads in one
+ * go - and the person reads it too, framed as `Stop hook error:` in the terminal (B9a, R12a).
+ */
+const NAMED_AT_MOST = 3;
+/**
+ * The command the agent offers to run: this session by its id, and nothing of what the report holds (R18, R19), with
+ * agentwhy invoked the way the hook invokes it.
+ */
+export function reportCommand(sessionId, invocation) {
+    return `${invocation} report --input ${sessionId} --open --quiet`;
+}
+function list(files) {
+    const [one, two, three] = files;
+    if (three !== undefined)
+        return `${one}, ${two} and ${three}`;
+    if (two !== undefined)
+        return `${one} and ${two}`;
+    return String(one);
+}

package/dist/report/watch/render/notice-words.js

@@ -0,0 +1,182 @@
+/** The title every notice carries, wherever it is shown. */
+export const NOTICE_TITLE = 'agentwhy';
+/** Said the same way wherever details are offered, and last, where a cut notice loses it first. */
+const DETAILS = 'Details: agentwhy report --open';
+/**
+ * What to do, first, in the words `check` already uses for the same two cases. A notice arrives in a frame this
+ * project does not draw - grey italics under a reply, or three lines of a system notification - so the first thing
+ * read has to be the action, not the account (`a-notice-in-the-conversation.md` R4).
+ */
+const ROTATE = 'ROTATE:';
+const CHECK = 'CHECK:';
+/** The third word, for the level that asks for nothing: a rule held, and the reader is being told so (R1, R3). */
+const NOTE = 'NOTE:';
+/**
+ * About what a macOS notification shows before it cuts the words (B4f, the user's screenshot: three lines of about
+ * 50 characters under the title). Every notice is written to fit it, so that what happened and where to look are
+ * both read; `tests/report/watch/render/notice-words.test.ts` holds each one to it.
+ */
+export const NOTICE_BUDGET = 150;
+/**
+ * Who is speaking, for the one channel with no title of its own. A terminal notification and a system notification
+ * are drawn with `NOTICE_TITLE` above them; the line in the conversation arrives under a frame Claude Code writes
+ * (`Stop says: …`), which names the event and not the tool - so the words say it instead. The budget in
+ * `NOTICE_BUDGET` is what a notification shows, and this is not one, so it is measured without this prefix.
+ */
+export function withTitle(words) {
+    return words === '' ? '' : `${NOTICE_TITLE} · ${words}`;
+}
+const NOT_CHECKED = {
+    arguments: 'Finished agent not checked: watch was given arguments it does not know.',
+    input: 'Finished agent not checked: the hook input could not be read.',
+    policy: 'Finished agent not checked: the policy could not be read.',
+    session: "Finished agent not checked: the session's records could not be read.",
+    'agent-not-found': "Finished agent not checked: it is not in the session's records yet.",
+};
+/**
+ * One notice in words, or no words for nothing to say (`specs/2026-09-16-when-an-agent-finishes.md` R5-R7, R15). It
+ * reads counts and enumerations only - the agent's type, how many files, how many attempts - so no path, value,
+ * identifier or task description can reach it, whatever the session held. Where the words are shown is decided after
+ * this.
+ */
+export class NoticeWordsRenderer {
+    render(notice) {
+        switch (notice.kind) {
+            case 'quiet':
+                return '';
+            case 'not-checked':
+                return `${NOT_CHECKED[notice.reason]} ${DETAILS}`;
+            case 'alert':
+                return `${sentenceOf(notice.alert)} ${DETAILS}`;
+            case 'turn':
+                return turnWords(notice.remembered);
+            case 'clean':
+                return cleanWords(notice.first, notice.counts, notice.lang);
+            case 'preferences-unusable':
+                // What a person needs is what is in force now and the way to change it; the file's name is in the command.
+                return "Your notification choices could not be read, so agentwhy's own are in use. See: agentwhy notify";
+        }
+    }
+}
+/**
+ * A turn that found nothing (R4-R6), in the language the person reads (R29). Three lines, and the difference between
+ * them is the whole point:
+ *
+ * - the first quiet turn of a session says the watch is running, which is what silence cannot say;
+ * - a later quiet turn says only what this turn found, never what the session holds;
+ * - a quiet turn of a session that was not quiet says both, in that order, and says the earlier finding in the
+ *   past tense: whether the key has since been rotated is not something a hook can know, and a line reading
+ *   "1 value to rotate" at someone who rotated it an hour ago is a line they stop reading.
+ *
+ * Written for a person who does not build software (R29): the page's own words - a private file, your AI opened it -
+ * and "so far", because a clean turn is not a clean session and a line must never read as a promise about the rest.
+ * `Details:` is left off the two lines that report nothing: there is nothing in the report to go and look at, and
+ * the words are what a notification cuts first. The command stays in English, because it is typed.
+ */
+function cleanWords(first, counts, lang) {
+    const words = CLEAN_WORDS[lang];
+    const earlier = counts.values > 0 ? words.valueEarlier(counts.values) : counts.reached > 0 ? words.reachedEarlier(counts.reached) : undefined;
+    if (earlier !== undefined)
+        return `${words.nothingNew} ${earlier} ${words.details}: agentwhy report --open`;
+    return first ? words.first : words.turn;
+}
+const CLEAN_WORDS = {
+    en: {
+        first: "✓ So far your AI hasn't opened any private files. I'm keeping watch.",
+        turn: "✓ Your AI didn't open any private files in this reply.",
+        nothingNew: 'Nothing new now.',
+        valueEarlier: (count) => `Earlier in this chat your AI read ${count === 1 ? 'a key' : `${count} keys`} from a private file.`,
+        reachedEarlier: (count) => `Earlier in this chat your AI opened ${count === 1 ? 'a private file' : `${count} private files`}.`,
+        details: 'Details',
+    },
+    pl: {
+        first: '✓ Jak dotąd AI nie otworzyło żadnego prywatnego pliku. Pilnuję dalej.',
+        turn: '✓ W tej odpowiedzi AI nie otworzyło żadnego prywatnego pliku.',
+        nothingNew: 'Teraz nic nowego.',
+        valueEarlier: (count) => `Wcześniej w tej rozmowie AI przeczytało ${count === 1 ? 'klucz' : `${count} ${polish(count, 'klucze', 'kluczy')}`} z prywatnego pliku.`,
+        reachedEarlier: (count) => `Wcześniej w tej rozmowie AI otworzyło ${count === 1 ? 'prywatny plik' : `${count} ${polish(count, 'prywatne pliki', 'prywatnych plików')}`}.`,
+        details: 'Szczegóły',
+    },
+    de: {
+        first: '✓ Bisher hat deine KI keine private Datei geöffnet. Ich passe weiter auf.',
+        turn: '✓ In dieser Antwort hat deine KI keine private Datei geöffnet.',
+        nothingNew: 'Jetzt nichts Neues.',
+        valueEarlier: (count) => `Vorhin hat deine KI ${count === 1 ? 'einen Schlüssel' : `${count} Schlüssel`} aus einer privaten Datei gelesen.`,
+        reachedEarlier: (count) => `Vorhin hat deine KI ${count === 1 ? 'eine private Datei' : `${count} private Dateien`} geöffnet.`,
+        details: 'Details',
+    },
+};
+/** Polish counts two ways past one: 2-4 take one form (22-24 too, 12-14 not), everything else the other. */
+function polish(count, few, many) {
+    const units = count % 10;
+    const tens = count % 100;
+    return units >= 2 && units <= 4 && (tens < 12 || tens > 14) ? few : many;
+}
+function sentenceOf(alert) {
+    // The session's own agent is the conversation the reader is in. Calling it "an agent" would send them looking for one.
+    const who = alert.own === true ? 'This conversation' : alert.type === undefined ? 'An agent' : `${alert.type} agent`;
+    const files = alert.filesReached === undefined ? 'protected files' : plural(alert.filesReached, 'protected file', 'protected files');
+    // Which levels reach this point is decided by the threshold, before a notice is made. "Reached" counts the agents
+    // it started too, which the report shows apart.
+    // A value notice is held to the 150 characters a notification shows (`NOTICE_BUDGET`), so once the first clause has
+    // said "a protected file", the count that follows says "files" and not "protected files" again.
+    // The agent's type is what the transcript recorded: quoted as written, never recased.
+    const counted = alert.filesReached === undefined ? 'files' : plural(alert.filesReached, 'file', 'files');
+    /*
+     * A refusal is the one level that is good news, so it is said as news and asks for nothing
+     * (`the-agent-tells-you.md` R3). It is said only where the threshold asked for it, and only when it is the whole
+     * story: where a file was reached or a value written, those words come first and the refusals go unmentioned -
+     * they are what a notification cuts first, and the report has them either way.
+     * The rule is the subject, not the agent: "a rule refused" reads the same for a delegated agent and for the
+     * conversation itself, where "this conversation was refused" would not.
+     */
+    if (alert.level === 'refused') {
+        return `${NOTE} a rule refused ${plural(alert.refusedAttempts, 'attempt', 'attempts')} at protected files; nothing was reached.`;
+    }
+    if (alert.own === true) {
+        return alert.level === 'value'
+            ? `${ROTATE} a value from a protected file is in this conversation. ${capitalised(counted)} reached.`
+            : `${CHECK} ${who} reached ${files}; no value found in its messages.`;
+    }
+    return alert.level === 'value'
+        ? `${ROTATE} ${who} wrote a value from a protected file; its answer may carry it. ${capitalised(counted)} reached.`
+        : `${CHECK} ${who} reached ${files}; no value found in its messages.`;
+}
+/**
+ * A turn's worth of remembered alerts in one line (`a-notice-in-the-conversation.md` R12). One agent says exactly
+ * what its own notice said, so nothing is rewritten on the way; several are counted, because a line that listed
+ * them would be cut before the reader reached the end. What could not be checked is said too, never dropped.
+ */
+export function turnWords(remembered) {
+    const [only] = remembered;
+    if (only === undefined)
+        return '';
+    if (remembered.length === 1)
+        return only.words;
+    const checked = remembered.filter((alert) => alert.level !== 'not-checked');
+    const missed = remembered.length - checked.length;
+    const unchecked = `${plural(missed, 'agent', 'agents')} could not be checked`;
+    if (checked.length === 0)
+        return `${CHECK} ${unchecked}. ${DETAILS}`;
+    /*
+     * A refused agent reached nothing, so it cannot be counted among the agents that did: a line saying "3 agents
+     * reached protected files" about two refusals and one reach would be false in the direction that matters. Where
+     * something was reached, the refusals go unsaid, exactly as they do in one agent's own notice.
+     */
+    const reached = checked.filter((alert) => alert.level === 'value' || alert.level === 'reached');
+    const values = reached.filter((alert) => alert.level === 'value').length;
+    const head = reached.length === 0
+        ? `${NOTE} a rule refused attempts by ${plural(checked.length, 'agent', 'agents')}; nothing was reached`
+        : values === 0
+            ? `${CHECK} ${plural(reached.length, 'agent', 'agents')} reached protected files; no value found in their messages`
+            : values === reached.length
+                ? `${ROTATE} ${plural(values, 'agent', 'agents')} wrote a value from a protected file; their answers may carry it`
+                : `${ROTATE} ${plural(reached.length, 'agent', 'agents')} reached protected files, ${values} wrote a value from one`;
+    return `${head}${missed === 0 ? '' : `; ${unchecked}`}. ${DETAILS}`;
+}
+function capitalised(words) {
+    return `${words.charAt(0).toUpperCase()}${words.slice(1)}`;
+}
+function plural(count, one, many) {
+    return `${count} ${count === 1 ? one : many}`;
+}