@event4u/agent-config 6.0.0 → 7.0.0

package/src/scripts/ai_council/events_log.ts

@@ -0,0 +1,327 @@
+/**
+ * Persistent council events log (step-8 phase 3).
+ *
+ * TypeScript twin of `src/scripts/ai_council/events_log.py` (ADR-200 —
+ * Python→TS migration, Phase 1). Appends one JSON line per council event to
+ * `<project_root>/agents/runtime/council/events.log`. Schema v1 carries the
+ * minimum needed to answer the "why did the council skip / block this?"
+ * question at retro time without leaking prompt content.
+ *
+ * Privacy floor:
+ *     `original_ask` is never written verbatim — the caller passes the raw
+ *     string, and `appendEvent` writes `sha256(value)[:12]` as
+ *     `original_ask_hash`.
+ *
+ * Kill-switch:
+ *     `AGENT_CONFIG_NO_EVENTS_LOG=1` short-circuits `appendEvent` to a no-op.
+ *
+ * Byte-parity:
+ *     The JSON line is `json.dumps(record, ensure_ascii=False,
+ *     separators=(",", ":"))` — no sort_keys (insertion order preserved),
+ *     raw (non-escaped) non-ASCII, `,` / `:` separators.
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const SCHEMA_VERSION = 1;
+
+export type EventAction = 'proceed' | 'skip_necessity' | 'block_quota';
+
+const _VALID_ACTIONS: ReadonlySet<string> = new Set([
+    'proceed',
+    'skip_necessity',
+    'block_quota',
+]);
+
+/**
+ * Environment-variable kill-switch. Truthy values disable all writes; the
+ * function silently returns.
+ */
+const _KILL_SWITCH_ENV = 'AGENT_CONFIG_NO_EVENTS_LOG';
+
+const _HERE = fileURLToPath(import.meta.url);
+// src/scripts/ai_council/events_log.py → parents[3] == repo root.
+const _REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..', '..');
+
+/**
+ * Default log path, resolved relative to the package root (two levels above
+ * `scripts/ai_council/` — `parents[3]` in Python). Callers can override via
+ * `logPath` for tests.
+ */
+const _DEFAULT_LOG_PATH = path.join(
+    _REPO_ROOT,
+    'agents',
+    'runtime',
+    'council',
+    'events.log',
+);
+
+/**
+ * Return sha256(original_ask)[:12] — the privacy-floor hash.
+ *
+ * Empty / missing input maps to a stable sentinel so the schema field is
+ * always populated.
+ */
+function _hash_original_ask(originalAsk: string): string {
+    if (!originalAsk) {
+        return '0'.repeat(12);
+    }
+    // Python: original_ask.encode("utf-8", errors="replace"). Node's utf-8
+    // encoding via Buffer matches for valid strings; lone surrogates map to
+    // U+FFFD under both errors="replace" and Buffer's WHATWG-ish behavior.
+    const bytes = Buffer.from(_encodeUtf8Replace(originalAsk), 'binary');
+    return crypto.createHash('sha256').update(bytes).digest('hex').slice(0, 12);
+}
+
+/**
+ * Encode a JS string to a UTF-8 byte string with `errors="replace"`
+ * semantics: lone surrogates become U+FFFD (3 bytes EF BF BD). Returned as a
+ * latin1/binary string so `Buffer.from(_, 'binary')` reproduces the bytes.
+ */
+function _encodeUtf8Replace(s: string): string {
+    let out = '';
+    for (let i = 0; i < s.length; i += 1) {
+        const code = s.charCodeAt(i);
+        let cp: number;
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = i + 1 < s.length ? s.charCodeAt(i + 1) : 0;
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                cp = (code - 0xd800) * 0x400 + (next - 0xdc00) + 0x10000;
+                i += 1;
+            } else {
+                cp = 0xfffd; // lone high surrogate → replacement
+            }
+        } else if (code >= 0xdc00 && code <= 0xdfff) {
+            cp = 0xfffd; // lone low surrogate → replacement
+        } else {
+            cp = code;
+        }
+        out += _utf8Bytes(cp);
+    }
+    return out;
+}
+
+/** Code point → UTF-8 bytes, as a binary string. */
+function _utf8Bytes(cp: number): string {
+    if (cp <= 0x7f) {
+        return String.fromCharCode(cp);
+    }
+    if (cp <= 0x7ff) {
+        return String.fromCharCode(0xc0 | (cp >> 6), 0x80 | (cp & 0x3f));
+    }
+    if (cp <= 0xffff) {
+        return String.fromCharCode(
+            0xe0 | (cp >> 12),
+            0x80 | ((cp >> 6) & 0x3f),
+            0x80 | (cp & 0x3f),
+        );
+    }
+    return String.fromCharCode(
+        0xf0 | (cp >> 18),
+        0x80 | ((cp >> 12) & 0x3f),
+        0x80 | ((cp >> 6) & 0x3f),
+        0x80 | (cp & 0x3f),
+    );
+}
+
+function _kill_switch_active(): boolean {
+    const value = process.env[_KILL_SWITCH_ENV] ?? '';
+    return !(value === '' || value === '0' || value === 'false' || value === 'False');
+}
+
+export interface AppendEventOptions {
+    /** Override for tests. Defaults to the canonical events-log path. */
+    logPath?: string | null;
+    /** Override the wall-clock timestamp (tests). Defaults to `new Date()`. */
+    now?: Date;
+}
+
+/**
+ * Append a single JSON event line to the council events log.
+ *
+ * Returns `true` when a line was written; `false` when the kill-switch
+ * suppressed the write. Never raises on missing parent dir — the function
+ * creates it on demand.
+ *
+ * Throws `Error` (Python `ValueError`) when `action` is not in the valid set.
+ *
+ * NOTE: mutates `event` (pops `original_ask`) — matches the Python
+ * `event.pop("original_ask", ...)` side effect.
+ */
+export function appendEvent(
+    event: Record<string, unknown>,
+    opts: AppendEventOptions = {},
+): boolean {
+    if (_kill_switch_active()) {
+        return false;
+    }
+
+    const action = event['action'];
+    if (typeof action !== 'string' || !_VALID_ACTIONS.has(action)) {
+        throw new Error(
+            `events_log: action=${_pyRepr(action)} not in ` +
+                `${_pyReprList(Array.from(_VALID_ACTIONS).sort())}.`,
+        );
+    }
+
+    // Python: event.pop("original_ask", "") if "original_ask" in event else ""
+    // The schema documents original_ask as a string; non-string / null is not
+    // a documented input — treat null/undefined as "" and coerce otherwise.
+    let rawAsk = '';
+    if ('original_ask' in event) {
+        const popped = event['original_ask'];
+        if (typeof popped === 'string') {
+            rawAsk = popped;
+        } else if (popped === undefined || popped === null) {
+            rawAsk = '';
+        } else {
+            rawAsk = String(popped);
+        }
+        delete event['original_ask'];
+    }
+
+    const now = opts.now ?? new Date();
+    const record: Record<string, unknown> = {
+        schema_version: SCHEMA_VERSION,
+        ts_utc: _isoSecondsZ(now),
+        lens: 'lens' in event ? event['lens'] : '',
+        invocation: 'invocation' in event ? event['invocation'] : '',
+        action,
+        verdict: 'verdict' in event ? event['verdict'] : '',
+        provider_caps: 'provider_caps' in event ? event['provider_caps'] : {},
+        original_ask_hash: _hash_original_ask(rawAsk),
+    };
+    // Pass-through for any caller-supplied diagnostic fields that are not in
+    // the schema-v1 reserved set. The schema-v1 fields above always win on
+    // collision.
+    const reserved = new Set([...Object.keys(record), 'original_ask']);
+    for (const [k, v] of Object.entries(event)) {
+        if (!reserved.has(k)) {
+            record[k] = v;
+        }
+    }
+
+    const target = opts.logPath != null ? opts.logPath : _DEFAULT_LOG_PATH;
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const line = _pyJsonDumpsCompact(record);
+    fs.appendFileSync(target, line + '\n', { encoding: 'utf-8' });
+    return true;
+}
+
+/** Return the canonical events-log path (callers / tests). */
+export function defaultLogPath(): string {
+    return _DEFAULT_LOG_PATH;
+}
+
+// ── helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Mirror Python `datetime.now(timezone.utc).isoformat(timespec="seconds")`
+ * with `+00:00` replaced by `Z`. → `YYYY-MM-DDTHH:MM:SSZ`.
+ */
+function _isoSecondsZ(d: Date): string {
+    const pad = (n: number, w = 2): string => String(n).padStart(w, '0');
+    return (
+        `${pad(d.getUTCFullYear(), 4)}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}` +
+        `T${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}Z`
+    );
+}
+
+/** Python repr() for an arbitrary scalar used in error messages. */
+function _pyRepr(v: unknown): string {
+    if (typeof v === 'string') {
+        return `'${v}'`;
+    }
+    if (v === null) {
+        return 'None';
+    }
+    if (v === undefined) {
+        // event.get("action") on a missing key → None in Python.
+        return 'None';
+    }
+    if (typeof v === 'boolean') {
+        return v ? 'True' : 'False';
+    }
+    return String(v);
+}
+
+/** Python repr() for a list of strings: ['a', 'b']. */
+function _pyReprList(items: string[]): string {
+    return `[${items.map((i) => `'${i}'`).join(', ')}]`;
+}
+
+/**
+ * Mirror Python `json.dumps(obj, ensure_ascii=False, separators=(",", ":"))`:
+ * insertion-order keys, no whitespace, raw (non-escaped) non-ASCII.
+ */
+function _pyJsonDumpsCompact(value: unknown): string {
+    if (value === null || value === undefined) {
+        return 'null';
+    }
+    switch (typeof value) {
+        case 'boolean':
+            return value ? 'true' : 'false';
+        case 'number':
+            return _pyJsonNumber(value);
+        case 'string':
+            return _pyJsonStringRaw(value);
+        case 'object':
+            break;
+        default:
+            throw new TypeError(`Object of type ${typeof value} is not JSON serializable`);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => _pyJsonDumpsCompact(v)).join(',')}]`;
+    }
+    const obj = value as Record<string, unknown>;
+    const parts: string[] = [];
+    for (const k of Object.keys(obj)) {
+        parts.push(`${_pyJsonStringRaw(k)}:${_pyJsonDumpsCompact(obj[k])}`);
+    }
+    return `{${parts.join(',')}}`;
+}
+
+/** Render a number like Python `json.dumps` (int vs float; JS has one type). */
+function _pyJsonNumber(n: number): string {
+    if (!Number.isFinite(n)) {
+        if (Number.isNaN(n)) {
+            return 'NaN';
+        }
+        return n > 0 ? 'Infinity' : '-Infinity';
+    }
+    return String(n);
+}
+
+/**
+ * Escape a string like Python `json.dumps(..., ensure_ascii=False)`:
+ * short escapes for `"` `\` and the C0 control chars, but non-ASCII passes
+ * through raw (not `\uXXXX`).
+ */
+function _pyJsonStringRaw(s: string): string {
+    let out = '"';
+    for (const ch of s) {
+        const code = ch.codePointAt(0) ?? 0;
+        if (ch === '"') {
+            out += '\\"';
+        } else if (ch === '\\') {
+            out += '\\\\';
+        } else if (ch === '\b') {
+            out += '\\b';
+        } else if (ch === '\f') {
+            out += '\\f';
+        } else if (ch === '\n') {
+            out += '\\n';
+        } else if (ch === '\r') {
+            out += '\\r';
+        } else if (ch === '\t') {
+            out += '\\t';
+        } else if (code < 0x20) {
+            out += `\\u${code.toString(16).padStart(4, '0')}`;
+        } else {
+            out += ch;
+        }
+    }
+    return out + '"';
+}

package/src/scripts/ai_council/learn_low_impact_preview.ts

@@ -0,0 +1,317 @@
+/**
+ * Preview builder for `/memory learn-low-impact` (step-9 Phase 7).
+ *
+ * TypeScript twin of `src/scripts/ai_council/learn_low_impact_preview.py`
+ * (ADR-200 — Python→TS migration, Phase 1).
+ *
+ * Default invocation is `--preview`: build a structured plan describing
+ * which Validated entries would be upstreamed to the package seed without
+ * opening a PR. `--apply` (handled by the agent, not this module) is the
+ * explicit opt-in that triggers the actual upstream-contribute PR flow.
+ *
+ * The module is import-light by design — pure parsing + redaction + diff
+ * rendering. PR creation lives in the `upstream-contribute` skill;
+ * this module only hands the agent the material to surface.
+ */
+
+import * as fs from 'node:fs';
+
+import { parse_corpus_strict } from './low_impact_corpus.js';
+import {
+    type RedactionViolation,
+    redact_low_impact_entry,
+} from './redact_low_impact_entry.js';
+
+// Python: re.compile(r"^last-upstreamed:\s*([0-9a-f]{6,40}|0+)\s*$",
+//                     re.IGNORECASE | re.MULTILINE)
+// \s is Unicode in Python; emulate via the explicit Unicode whitespace class.
+const _SP = '[ \\t\\f\\v\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff\\u0085]';
+const _PROVENANCE_RE = new RegExp(
+    `^last-upstreamed:${_SP}*([0-9a-f]{6,40}|0+)${_SP}*$`,
+    'imu',
+);
+
+/** One Validated bullet that would be upstreamed. */
+export interface PreviewEntry {
+    readonly phrase: string;
+    readonly normalised: string;
+    readonly line_no: number;
+}
+
+/** A Validated bullet the redactor refused — never upstreams. */
+export class RefusedEntry {
+    readonly phrase: string;
+    readonly line_no: number;
+    readonly violations: readonly RedactionViolation[];
+
+    constructor(phrase: string, line_no: number, violations: readonly RedactionViolation[]) {
+        this.phrase = phrase;
+        this.line_no = line_no;
+        this.violations = violations;
+    }
+
+    reason(): string {
+        // Python: "; ".join(f"{v.category}: {v.snippet}" for v in self.violations)
+        return this.violations.map((v) => `${v.category}: ${v.snippet}`).join('; ');
+    }
+}
+
+/**
+ * Structured preview for `/memory learn-low-impact --preview`.
+ *
+ * Consumed by the agent which renders the human-facing preview block,
+ * then waits for explicit `--apply` before invoking `upstream-contribute`.
+ */
+export class LearnLowImpactPreview {
+    readonly promoted: readonly PreviewEntry[];
+    readonly refused: readonly RefusedEntry[];
+    readonly already_seeded: readonly string[];
+    readonly last_upstreamed_sha: string;
+    readonly seed_path: string;
+    readonly corpus_path: string;
+    readonly repo_slug: string;
+    readonly warnings: readonly string[];
+
+    constructor(opts: {
+        promoted: readonly PreviewEntry[];
+        refused: readonly RefusedEntry[];
+        already_seeded: readonly string[];
+        last_upstreamed_sha: string;
+        seed_path: string;
+        corpus_path: string;
+        repo_slug?: string;
+        warnings?: readonly string[];
+    }) {
+        this.promoted = opts.promoted;
+        this.refused = opts.refused;
+        this.already_seeded = opts.already_seeded;
+        this.last_upstreamed_sha = opts.last_upstreamed_sha;
+        this.seed_path = opts.seed_path;
+        this.corpus_path = opts.corpus_path;
+        this.repo_slug = opts.repo_slug ?? '';
+        this.warnings = opts.warnings ?? [];
+    }
+
+    get has_work(): boolean {
+        return this.promoted.length > 0 || this.refused.length > 0;
+    }
+
+    /**
+     * True when `--apply` would actually open a PR.
+     *
+     * Iron Law: any redactor refusal blocks the PR — the author must
+     * rephrase or drop the offending entry locally and re-run.
+     */
+    get would_open_pr(): boolean {
+        return this.promoted.length > 0 && this.refused.length === 0;
+    }
+
+    /**
+     * Human-readable preview block.
+     *
+     * Mirrors the rendering convention from `/memory mine-session`:
+     * a leading title line, then bucketed entries.
+     */
+    render(): string {
+        const lines: string[] = [];
+        lines.push(
+            '## learn-low-impact preview' +
+                (this.repo_slug ? ` — repo=${this.repo_slug}` : ''),
+        );
+        lines.push(`last-upstreamed: ${this.last_upstreamed_sha}`);
+        lines.push(`seed: ${this.seed_path}`);
+        lines.push('');
+        if (this.promoted.length > 0) {
+            lines.push(`### Promoted (${this.promoted.length})`);
+            for (const e of this.promoted) {
+                lines.push(`- "${e.phrase}"  (line ${e.line_no})`);
+            }
+            lines.push('');
+        }
+        if (this.refused.length > 0) {
+            lines.push(`### Refused (${this.refused.length}) — redactor blocked`);
+            for (const r of this.refused) {
+                lines.push(`- "${r.phrase}"  (line ${r.line_no}) — ${r.reason()}`);
+            }
+            lines.push('');
+        }
+        if (this.already_seeded.length > 0) {
+            lines.push(`### Already seeded (${this.already_seeded.length})`);
+            for (const phrase of this.already_seeded) {
+                lines.push(`- "${phrase}"`);
+            }
+            lines.push('');
+        }
+        if (!this.has_work) {
+            lines.push('> No new validated entries to upstream.');
+            lines.push('');
+        }
+        if (this.refused.length > 0) {
+            lines.push(
+                '> Refusals block the PR. Rephrase the entries locally' +
+                    ' (or drop them) and re-run.',
+            );
+        } else if (this.promoted.length > 0) {
+            lines.push(
+                '> Re-run with `--apply` to open the draft PR via' +
+                    ' `upstream-contribute`.',
+            );
+        }
+        // Python: "\n".join(lines).rstrip() + "\n"
+        return _rstrip(lines.join('\n')) + '\n';
+    }
+
+    /**
+     * Source-project-stripped diff that `--apply` would propose.
+     *
+     * Emits unified-diff-style `+` lines for each promoted phrase under the
+     * seed file's `## Validated` section. The agent uses this as the
+     * `upstream-contribute` patch body.
+     */
+    render_diff(): string {
+        if (this.promoted.length === 0) {
+            return '';
+        }
+        const lines = [`--- ${this.seed_path}`, `+++ ${this.seed_path}`];
+        for (const e of this.promoted) {
+            lines.push(`+- "${e.phrase}"`);
+        }
+        return lines.join('\n') + '\n';
+    }
+
+    /** Draft PR body for the upstream contribute flow. */
+    render_pr_body(): string {
+        const n = this.promoted.length;
+        const slug = this.repo_slug || '<repo-slug>';
+        const title = `feat(low-impact-seed): add ${n} validated entries from ${slug}`;
+        const bodyLines: string[] = [
+            `# ${title}`,
+            '',
+            'Upstream from `/memory learn-low-impact --apply`.',
+            '',
+            '## Entries',
+            '',
+        ];
+        for (const e of this.promoted) {
+            bodyLines.push(`- "${e.phrase}"`);
+        }
+        bodyLines.push('');
+        bodyLines.push(`Provenance baseline: \`${this.last_upstreamed_sha}\`.`);
+        bodyLines.push('');
+        bodyLines.push(
+            'Per `low-impact-corpus-privacy-floor`, every entry above' +
+                ' cleared the redactor on intake and again at upstream.',
+        );
+        return bodyLines.join('\n') + '\n';
+    }
+}
+
+/** Python `str.rstrip()`. */
+function _rstrip(s: string): string {
+    // Python str.rstrip() strips Unicode whitespace from the end. Use the
+    // explicit Python str.isspace() set (ASCII + Unicode space separators +
+    // line/para separators + NEL); JS \s under /u is close but Python also
+    // treats a handful of separators as space.
+    const WS =
+        '\\t\\n\\v\\f\\r \\u001c\\u001d\\u001e\\u001f\\u0085\\u00a0' +
+        '\\u1680\\u2000\\u2001\\u2002\\u2003\\u2004\\u2005\\u2006\\u2007' +
+        '\\u2008\\u2009\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000';
+    const re = new RegExp(`[${WS}]+$`, 'u');
+    return s.replace(re, '');
+}
+
+/**
+ * Return the set of normalised phrases already in the seed file.
+ *
+ * Missing seed file is not an error — it returns an empty set so the
+ * first-ever upstream PR can seed the whole corpus. Reuses the strict
+ * parser so the seed itself is contract-validated.
+ */
+function _readSeedPhrases(seedPath: string): Set<string> {
+    if (!fs.existsSync(seedPath)) {
+        return new Set();
+    }
+    const result = parse_corpus_strict(seedPath);
+    return new Set(result.validated.map((e) => e.normalised));
+}
+
+function _readProvenance(corpusPath: string): string {
+    if (!fs.existsSync(corpusPath)) {
+        return '0'.repeat(40);
+    }
+    const text = fs.readFileSync(corpusPath, { encoding: 'utf-8' });
+    const m = _PROVENANCE_RE.exec(text);
+    return m ? (m[1] as string).toLowerCase() : '0'.repeat(40);
+}
+
+export interface BuildPreviewOptions {
+    repoRoot?: string | null;
+    privateDomains?: Iterable<string>;
+    customerNames?: Iterable<string>;
+    sqlIdentifiers?: Iterable<string>;
+    repoSlug?: string;
+}
+
+/**
+ * Build the preview plan without performing any PR side-effects.
+ *
+ * Steps mirror the command doc:
+ *
+ * 1. Parse the local corpus (strict — drift surfaces as ParseError).
+ *    Step-10: the preview deliberately stays on the Markdown parser
+ *    (not the YAML lockfile) because it runs *before* `task sync`
+ *    rebuilds the lockfile from a user's local corpus edits.
+ * 2. Diff Validated entries against the upstream seed.
+ * 3. Run the redactor on every candidate.
+ * 4. Bucket into promoted / refused / already-seeded.
+ */
+export function build_preview(
+    corpusPath: string,
+    seedPath: string,
+    opts: BuildPreviewOptions = {},
+): LearnLowImpactPreview {
+    const repoRoot = opts.repoRoot ?? null;
+    const privateDomains = opts.privateDomains ?? [];
+    const customerNames = opts.customerNames ?? [];
+    const sqlIdentifiers = opts.sqlIdentifiers ?? [];
+    const repoSlug = opts.repoSlug ?? '';
+
+    const corpusP = String(corpusPath);
+    const seedP = String(seedPath);
+    const parsed = parse_corpus_strict(corpusP);
+    const seeded = _readSeedPhrases(seedP);
+    const promoted: PreviewEntry[] = [];
+    const refused: RefusedEntry[] = [];
+    const already: string[] = [];
+    for (const entry of parsed.validated) {
+        if (seeded.has(entry.normalised)) {
+            already.push(entry.phrase);
+            continue;
+        }
+        const result = redact_low_impact_entry(entry.phrase, {
+            repoRoot,
+            privateDomains,
+            customerNames,
+            sqlIdentifiers,
+        });
+        if (result.ok) {
+            promoted.push({
+                phrase: entry.phrase,
+                normalised: entry.normalised,
+                line_no: entry.line_no,
+            });
+        } else {
+            refused.push(new RefusedEntry(entry.phrase, entry.line_no, result.violations));
+        }
+    }
+    return new LearnLowImpactPreview({
+        promoted,
+        refused,
+        already_seeded: already,
+        last_upstreamed_sha: _readProvenance(corpusP),
+        seed_path: seedP,
+        corpus_path: corpusP,
+        repo_slug: repoSlug,
+        warnings: parsed.warnings,
+    });
+}