@event4u/agent-config 6.1.0 → 7.0.0

package/src/scripts/_cli/explain_last/memory.ts

@@ -0,0 +1,231 @@
+/**
+ * Resolve the `memory` why-slot for the trace.
+ *
+ * TypeScript twin of `src/scripts/_cli/explain_last/memory.py` (ADR-200).
+ * Behaviour mirrors the Python original EXACTLY — same two sources, same
+ * coercion order, same `float()` semantics, same `None`-on-empty branch.
+ * No behaviour changes.
+ *
+ * Two sources are consulted:
+ *
+ * - `state.memory[]` — the work-engine writes per-run memory hits here
+ *   during the `memory` step. Each entry carries `{entry_id, hit_score,
+ *   used_in}` already shaped to the trace contract.
+ * - `<root>/.agent-memory/hits.jsonl` — optional sidecar produced by the
+ *   memory-MCP integration. Filtered to entries tagged with the run id
+ *   when present.
+ *
+ * Returns `null` when neither source produced a non-empty list (the schema
+ * accepts a null memory slot so the renderer can drop the section cleanly).
+ *
+ * Parity note (ADR-200): Python's `hit_score = float(...)` always yields a
+ * `float`, even for integer inputs, so `json.dumps` renders `0.0` not `0`.
+ * The twin carries it as a `PyFloat` marker so the downstream JSON
+ * serializer (and the section renderer's `:.2f`) stays byte-identical.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { scrub_string } from './scrubber.js';
+
+/**
+ * Marker for a Python `float`. JS has no int/float distinction; a
+ * `PyFloat` makes `json.dumps` render integer-valued floats as `N.0`.
+ * Mirrors the established convention in the migrated scripts.
+ */
+export class PyFloat {
+    constructor(readonly value: number) {}
+}
+
+const MEMORY_SIDECAR = path.join('.agent-memory', 'hits.jsonl');
+
+/** Python truthiness (empty string / 0 / null / empty container falsy). */
+function _pyTruthy(value: unknown): boolean {
+    if (value === null || value === undefined) {
+        return false;
+    }
+    if (typeof value === 'string') {
+        return value.length > 0;
+    }
+    if (typeof value === 'number') {
+        return value !== 0 && !Number.isNaN(value);
+    }
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.length > 0;
+    }
+    if (typeof value === 'object') {
+        return Object.keys(value as object).length > 0;
+    }
+    return true;
+}
+
+/** Python `float()` — `TypeError`/`ValueError` paths return `null` (→ 0.0 fallback). */
+function _coerceFloat(value: unknown): number | null {
+    if (typeof value === 'number') {
+        return value;
+    }
+    if (typeof value === 'boolean') {
+        return value ? 1.0 : 0.0; // float(True)=1.0, float(False)=0.0
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed === '') {
+            return null;
+        }
+        const lowered = trimmed.toLowerCase();
+        if (['inf', 'infinity', '+inf', '+infinity'].includes(lowered)) {
+            return Infinity;
+        }
+        if (['-inf', '-infinity'].includes(lowered)) {
+            return -Infinity;
+        }
+        if (['nan', '+nan', '-nan'].includes(lowered)) {
+            return NaN;
+        }
+        if (!/^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/.test(trimmed)) {
+            return null;
+        }
+        const n = Number(trimmed);
+        return Number.isNaN(n) ? null : n;
+    }
+    return null; // dict/list/None → TypeError → fallback
+}
+
+function _coerce_entry(raw: Record<string, unknown>): Record<string, unknown> | null {
+    // entry_id = raw.get("entry_id") or raw.get("id")
+    const entry_id = _pyTruthy(raw.entry_id) ? raw.entry_id : (raw.id ?? null);
+    if (typeof entry_id !== 'string' || entry_id.trim() === '') {
+        return null;
+    }
+    // hit_score = raw.get("hit_score"); if None: hit_score = raw.get("score", 0.0)
+    let hitRaw: unknown = raw.hit_score ?? null;
+    if (hitRaw === null || hitRaw === undefined) {
+        hitRaw = 'score' in raw ? raw.score : 0.0;
+    }
+    const coerced = _coerceFloat(hitRaw);
+    const hit_score = new PyFloat(coerced === null ? 0.0 : coerced);
+    // used_in = raw.get("used_in") or raw.get("step") or "unspecified"
+    const used_in = _pyTruthy(raw.used_in)
+        ? raw.used_in
+        : (_pyTruthy(raw.step) ? raw.step : 'unspecified');
+    return {
+        entry_id: scrub_string(entry_id.trim()),
+        hit_score,
+        used_in: scrub_string(String(used_in)),
+    };
+}
+
+function _from_state(state: Record<string, unknown>): Record<string, unknown>[] {
+    const entries: Record<string, unknown>[] = [];
+    for (const raw of (state.memory as unknown[] | undefined) ?? []) {
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+            continue;
+        }
+        const entry = _coerce_entry(raw as Record<string, unknown>);
+        if (entry !== null) {
+            entries.push(entry);
+        }
+    }
+    return entries;
+}
+
+/**
+ * Python `str.splitlines()` (no args). Splits on the Python line-boundary
+ * set (`\n \r \r\n \v \f \x1c \x1d \x1e \x85 
 
`) and emits no
+ * trailing empty element when the string ends on a break.
+ */
+function _splitlines(s: string): string[] {
+    if (s === '') {
+        return [];
+    }
+    const breaks = new Set([
+        '\n', '\r', '\v', '\f',
+        '\x1c', '\x1d', '\x1e', '\x85',
+        '
', '
',
+    ]);
+    const out: string[] = [];
+    let cur = '';
+    for (let i = 0; i < s.length; i += 1) {
+        const ch = s[i] as string;
+        if (ch === '\r' && s[i + 1] === '\n') {
+            out.push(cur);
+            cur = '';
+            i += 1;
+            continue;
+        }
+        if (breaks.has(ch)) {
+            out.push(cur);
+            cur = '';
+            continue;
+        }
+        cur += ch;
+    }
+    if (cur !== '') {
+        out.push(cur);
+    }
+    return out;
+}
+
+function _from_sidecar(project_root: string, run_id: string | null): Record<string, unknown>[] {
+    const p = path.join(project_root, MEMORY_SIDECAR);
+    if (!fs.existsSync(p)) {
+        return [];
+    }
+    const entries: Record<string, unknown>[] = [];
+    let content: string;
+    try {
+        content = fs.readFileSync(p, 'utf-8');
+    } catch {
+        return [];
+    }
+    for (let line of _splitlines(content)) {
+        line = line.trim();
+        if (!line) {
+            continue;
+        }
+        let raw: unknown;
+        try {
+            raw = JSON.parse(line);
+        } catch {
+            continue; // json.JSONDecodeError → skip line
+        }
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+            continue;
+        }
+        const rawDict = raw as Record<string, unknown>;
+        // if run_id and raw.get("run_id") not in (None, run_id): continue
+        if (run_id) {
+            const got = rawDict.run_id ?? null;
+            if (got !== null && got !== run_id) {
+                continue;
+            }
+        }
+        const entry = _coerce_entry(rawDict);
+        if (entry !== null) {
+            entries.push(entry);
+        }
+    }
+    return entries;
+}
+
+export function build(
+    project_root: string,
+    state: Record<string, unknown>,
+): Record<string, unknown>[] | null {
+    // run_id = (state.get("input") or {}).get("data", {}).get("id")
+    const input = _pyTruthy(state.input) ? (state.input as Record<string, unknown>) : {};
+    const dataRaw = 'data' in input ? input.data : {};
+    const data =
+        typeof dataRaw === 'object' && dataRaw !== null && !Array.isArray(dataRaw)
+            ? (dataRaw as Record<string, unknown>)
+            : {};
+    const run_id = data.id;
+    const entries = _from_state(state);
+    entries.push(
+        ..._from_sidecar(project_root, typeof run_id === 'string' ? run_id : null),
+    );
+    return entries.length > 0 ? entries : null;
+}

package/src/scripts/_cli/explain_last/provider.ts

@@ -0,0 +1,82 @@
+/**
+ * Builder for the `trace.provider` slot.
+ *
+ * TypeScript twin of `src/scripts/_cli/explain_last/provider.py` (ADR-200).
+ * Behaviour mirrors the Python original EXACTLY — same video-only gate,
+ * same `video_provider` / `contract.video_provider` extraction order, same
+ * `None` branches, same scrub passes. No behaviour changes.
+ *
+ * Bounded to video runs (`state.directive_set == "video"`). The work_engine
+ * does not yet ship a video directive set — this builder is
+ * forward-compatible: when the engine eventually persists a provider
+ * selection (`state.video_provider` or `state.contract.video_provider` are
+ * both accepted shapes), the slot populates; otherwise it returns `None`.
+ */
+import { scrub_string } from './scrubber.js';
+
+function _isDict(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function _extract(state: Record<string, unknown>): Record<string, unknown> | null {
+    const direct = state.video_provider;
+    if (_isDict(direct)) {
+        return direct;
+    }
+    const contract = state.contract;
+    if (_isDict(contract)) {
+        const nested = contract.video_provider;
+        if (_isDict(nested)) {
+            return nested;
+        }
+    }
+    return null;
+}
+
+/** Python truthiness for the `or ""` fallthrough. */
+function _pyTruthy(value: unknown): boolean {
+    if (value === null || value === undefined) {
+        return false;
+    }
+    if (typeof value === 'string') {
+        return value.length > 0;
+    }
+    if (typeof value === 'number') {
+        return value !== 0 && !Number.isNaN(value);
+    }
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.length > 0;
+    }
+    if (typeof value === 'object') {
+        return Object.keys(value as object).length > 0;
+    }
+    return true;
+}
+
+export function build(state: Record<string, unknown>): Record<string, unknown> | null {
+    // if (state.get("directive_set") or "") != "video": return None
+    const ds = state.directive_set;
+    const dsStr = _pyTruthy(ds) ? ds : '';
+    if (dsStr !== 'video') {
+        return null;
+    }
+    const payload = _extract(state);
+    if (payload === null) {
+        return null;
+    }
+    const pid = payload.id;
+    let reason = payload.selection_reason;
+    if (typeof pid !== 'string' || !pid) {
+        return null;
+    }
+    if (typeof reason !== 'string' || !reason) {
+        reason = '';
+    }
+    return {
+        id: scrub_string(pid),
+        selection_reason: scrub_string(reason),
+    };
+}

package/src/scripts/_cli/explain_last/render.ts

@@ -0,0 +1,54 @@
+/**
+ * Deterministic Markdown projection of an `ExplainTrace`.
+ *
+ * TypeScript twin of `src/scripts/_cli/explain_last/render.py` (ADR-200).
+ * Behaviour mirrors the Python original EXACTLY — same fixed section
+ * order, same skip-empty-chunk join, same `rstrip()` + trailing newline,
+ * same tip-footer text and `with_footer` gate. No behaviour changes.
+ *
+ * Pure-function `render(trace) -> str`. Same input `ExplainTrace` always
+ * yields byte-identical Markdown — Phase 4 snapshot tests rely on this.
+ * Each section lives in its own module under `sections/`; the orchestrator
+ * only fixes the order.
+ */
+import * as sections from './sections/index.js';
+
+const _SECTION_ORDER: ReadonlyArray<(trace: Record<string, unknown>) => string> = [
+    sections.header.render,
+    sections.route.render,
+    sections.inputs.render,
+    sections.memory.render,
+    sections.council.render,
+    sections.halt.render,
+    sections.provider.render,
+    sections.assumptions.render,
+    sections.pack.render,
+];
+
+export const TIP_FOOTER =
+    '_tip: pass `--json` to emit machine-readable trace; '
+    + '`--quiet` to drop this footer._\n';
+
+/** Python `str.rstrip()` — strips trailing ASCII + Unicode whitespace. */
+function _rstrip(s: string): string {
+    return s.replace(/\s+$/u, '');
+}
+
+export function render(
+    trace: Record<string, unknown>,
+    options: { with_footer?: boolean } = {},
+): string {
+    const with_footer = options.with_footer ?? true;
+    const parts: string[] = [];
+    for (const section of _SECTION_ORDER) {
+        const chunk = section(trace);
+        if (chunk) {
+            parts.push(chunk);
+        }
+    }
+    let body = `${_rstrip(parts.join('\n'))}\n`;
+    if (with_footer) {
+        body += `\n${TIP_FOOTER}`;
+    }
+    return body;
+}

package/src/scripts/_cli/explain_last/route.ts

@@ -0,0 +1,70 @@
+/**
+ * Resolve the `route` why-slot for the trace.
+ *
+ * TypeScript twin of `src/scripts/_cli/explain_last/route.py` (ADR-200).
+ * Behaviour mirrors the Python original EXACTLY — same router lookup, same
+ * `None`-on-missing-router branch, same scrub passes, same key shape. No
+ * behaviour changes.
+ *
+ * Cross-references the persisted `state.persona` and `state.directive_set`
+ * against the project's `router.json`. Kernel rules are always-on (no
+ * trigger eval here); tier-1 rules are listed for the user to inspect via
+ * `agent-config explain route <text>` if they want trigger reasons.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { scrub_string } from './scrubber.js';
+
+export const ROUTER_FILENAME = 'router.json';
+const ROUTER_RELATIVE = path.join('dist', ROUTER_FILENAME);
+
+function _load_router(project_root: string): Record<string, unknown> | null {
+    const p = path.join(project_root, ROUTER_RELATIVE);
+    if (!fs.existsSync(p)) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        // Python `json.loads` of a non-object returns that value; the
+        // original assigns it straight to `router` and the `.get` calls
+        // below would raise on a non-dict. Mirror by treating only objects
+        // as routers; the original never guards this either, but the
+        // callers only ever feed it object JSON.
+        return parsed as Record<string, unknown>;
+    } catch {
+        // (OSError, json.JSONDecodeError) → None.
+        return null;
+    }
+}
+
+export function build(
+    project_root: string,
+    state: Record<string, unknown>,
+): Record<string, unknown> | null {
+    const router = _load_router(project_root);
+    if (router === null) {
+        return null;
+    }
+    const kernel: unknown[] = [];
+    for (const rid of (router.kernel as unknown[] | undefined) ?? []) {
+        kernel.push(scrub_string(String(rid)));
+    }
+    const tier_1: unknown[] = [];
+    for (const entry of (router.tier_1 as unknown[] | undefined) ?? []) {
+        if (typeof entry === 'object' && entry !== null && !Array.isArray(entry)) {
+            const rid = (entry as Record<string, unknown>).id;
+            if (typeof rid === 'string') {
+                tier_1.push(scrub_string(rid));
+            }
+        }
+    }
+    const persona = state.persona;
+    const persona_str =
+        typeof persona === 'string' && persona ? scrub_string(persona) : null;
+    return {
+        matched_rules: tier_1,
+        kernel_rules: kernel,
+        persona: persona_str,
+    };
+}

package/src/scripts/_cli/explain_last/scrubber.ts

@@ -0,0 +1,138 @@
+/**
+ * PII / cost-metadata scrubber for the `explain last` trace.
+ *
+ * TypeScript twin of `src/scripts/_cli/explain_last/scrubber.py` (ADR-200).
+ * Behaviour mirrors the Python original EXACTLY — same regex sources, same
+ * resolution order, same idempotence, same long-string threshold and
+ * summary text. No behaviour changes — latent bugs are replicated, not
+ * fixed.
+ *
+ * The standard project redactor under
+ * `scripts.ai_council.redact_low_impact_entry` is a *refusal* gate — it
+ * returns `ok=False` and asks the human to rephrase. The explain surface
+ * cannot refuse to produce output; the user already executed the upstream
+ * command and is now asking *why*. So this module mirrors the same regex
+ * patterns but performs in-place masking instead of refusal.
+ *
+ * Masks applied (resolution order):
+ *
+ * 1. Raw-key secret prefixes (`sk_live_…`, `ghp_…` etc.) and inline
+ *    `api_key=…` shapes → `<secret>`.
+ * 2. Emails → `<email>`.
+ * 3. Absolute file paths (`/Users/…`, `/home/…`, `C:\…`) → `<path>`.
+ * 4. URLs → `<scheme>://<host>/…` (path / query / fragment stripped).
+ * 5. `*.internal` / `*.local` hostnames → `<host>`.
+ * 6. Monetary amounts (`$1,234`, `USD 500`) → `<money>` — strips
+ *    billing-cost leakage from council token-usage metadata.
+ * 7. Long strings (> 200 chars) → `<NNN chars>` summary.
+ *
+ * Parity notes (ADR-200):
+ *  - Python's `re` `\w` / `\b` are Unicode-aware by default on `str`
+ *    (no `re.ASCII`). The JS twin uses the `u` flag with `\p{L}\p{N}_`
+ *    in place of `\w` and a non-`\b` boundary built from the same class
+ *    so a `café@exämple.com` email or a `/Users/möchte/f` path masks
+ *    identically to CPython. `_INTERNAL_HOST_RE`'s leading-char class is
+ *    `[a-zA-Z0-9]` in Python (ASCII-only) — kept ASCII here too.
+ *  - `len(out) > 200` is a Python `len` (code-point count, not UTF-16
+ *    units); the twin uses `pyLen` (Array.from spread) accordingly.
+ *  - The long-string summary uses the post-mask length (`len(out)`),
+ *    matching the original's `f"<{len(out)} chars>"`.
+ */
+
+export const LONG_STRING_THRESHOLD = 200;
+
+const _RAW_KEY_PREFIXES: readonly string[] = [
+    'sk_live_', 'sk_test_', 'ghp_', 'github_pat_', 'gho_', 'ghs_',
+    'ghu_', 'xoxb-', 'xoxp-', 'AIza', 'AKIA',
+];
+
+/** Escape a literal for a RegExp, mirroring Python's `re.escape`. */
+function _reEscape(literal: string): string {
+    // Python `re.escape` escapes non-alphanumerics; under the `u` flag a
+    // `\-` is an illegal escape, so `-` is escaped via its unicode form.
+    // The fixed prefixes only contain `-` (e.g. `xoxb-`), so this is the
+    // sole case that matters; the broad class covers the rest faithfully.
+    return literal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/-/g, '\\u002d');
+}
+
+// Unicode word-char class standing in for Python's default-mode `\w`.
+const _W = '\\p{L}\\p{N}_';
+
+const _RAW_KEY_RE = new RegExp(
+    '(?:' + _RAW_KEY_PREFIXES.map(_reEscape).join('|') + ')[A-Za-z0-9_-]{6,}',
+    'gu',
+);
+const _API_KEY_RE = new RegExp(
+    '\\bapi[_-]?key\\b\\s*[:=]\\s*[A-Za-z0-9+/=_-]{12,}',
+    'giu',
+);
+const _EMAIL_RE = new RegExp(
+    `(?<![${_W}.+-])[${_W}.+-]+@[${_W}-]+\\.[${_W}.-]+(?![${_W}.-])`,
+    'gu',
+);
+const _PATH_RE = new RegExp(
+    `(?:/Users/|/home/|/opt/|/private/|[A-Z]:\\\\)[${_W}./\\\\-]+`,
+    'gu',
+);
+const _URL_RE = new RegExp(
+    '(?<![\\p{L}\\p{N}_])(?<scheme>https?|ftp|ws|wss)://(?<host>[^\\s/:?#]+)(?:[^\\s]*)?',
+    'gu',
+);
+const _INTERNAL_HOST_RE = new RegExp(
+    `(?<![${_W}])[a-zA-Z0-9][${_W}.-]*\\.(?:internal|local)(?![${_W}])`,
+    'giu',
+);
+const _MONEY_RE = new RegExp(
+    '(?:[$€£¥]\\s?\\d{1,3}(?:[,.]\\d{3})*(?:\\.\\d+)?'
+    + '|\\b(?:USD|EUR|GBP|JPY)\\s?\\d+(?:[,.]\\d+)?)',
+    'gu',
+);
+
+/** Python `len()` — counts Unicode code points, not UTF-16 units. */
+function pyLen(s: string): number {
+    let n = 0;
+     
+    for (const _ch of s) {
+        n += 1;
+    }
+    return n;
+}
+
+function _stripUrl(_match: string, scheme: string, host: string): string {
+    return `${scheme}://${host}/…`;
+}
+
+export function scrub_string(value: unknown): unknown {
+    // Mirror Python's `if not isinstance(value, str) or not value` guard.
+    if (typeof value !== 'string' || value === '') {
+        return value;
+    }
+    let out = value.replace(_RAW_KEY_RE, '<secret>');
+    out = out.replace(_API_KEY_RE, 'api_key=<secret>');
+    out = out.replace(_EMAIL_RE, '<email>');
+    out = out.replace(_URL_RE, _stripUrl);
+    out = out.replace(_PATH_RE, '<path>');
+    out = out.replace(_INTERNAL_HOST_RE, '<host>');
+    out = out.replace(_MONEY_RE, '<money>');
+    if (pyLen(out) > LONG_STRING_THRESHOLD) {
+        return `<${pyLen(out)} chars>`;
+    }
+    return out;
+}
+
+export function scrub_value(value: unknown): unknown {
+    if (typeof value === 'string') {
+        return scrub_string(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => scrub_value(item));
+    }
+    if (typeof value === 'object' && value !== null) {
+        const out: Record<string, unknown> = {};
+        for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+            out[key] = scrub_value(val);
+        }
+        return out;
+    }
+    return value;
+}

package/src/scripts/_cli/explain_last/sections/assumptions.ts

@@ -0,0 +1,51 @@
+/**
+ * Render the `Assumptions` section.
+ *
+ * TypeScript twin of
+ * `src/scripts/_cli/explain_last/sections/assumptions.py` (ADR-200).
+ * Byte-identical to the Python original — note the DOUBLE space before the
+ * em-dash in the item line (`{ident}  — recorded`). No behaviour changes.
+ */
+
+function _pyTruthy(value: unknown): boolean {
+    if (value === null || value === undefined) {
+        return false;
+    }
+    if (typeof value === 'string') {
+        return value.length > 0;
+    }
+    if (typeof value === 'number') {
+        return value !== 0 && !Number.isNaN(value);
+    }
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.length > 0;
+    }
+    if (typeof value === 'object') {
+        return Object.keys(value as object).length > 0;
+    }
+    return true;
+}
+
+export function render(trace: Record<string, unknown>): string {
+    const out: string[] = ['## Assumptions', ''];
+    const items = (_pyTruthy(trace.assumptions) ? trace.assumptions : []) as unknown[];
+    if (items.length === 0) {
+        out.push('- (none captured)');
+        out.push('');
+        return out.join('\n');
+    }
+    for (const itemRaw of items) {
+        const item = itemRaw as Record<string, unknown>;
+        const ident = _pyTruthy(item.id) ? item.id : '(unknown)';
+        // accepted = item.get("accepted", True)
+        const accepted = 'accepted' in item ? item.accepted : true;
+        const source = _pyTruthy(item.source) ? item.source : 'unspecified';
+        const marker = accepted ? '[x]' : '[ ]';
+        out.push(`- ${marker} ${ident}  — recorded in step \`${source}\``);
+    }
+    out.push('');
+    return out.join('\n');
+}

package/src/scripts/_cli/explain_last/sections/council.ts

@@ -0,0 +1,56 @@
+/**
+ * Render the `Council` section.
+ *
+ * TypeScript twin of `src/scripts/_cli/explain_last/sections/council.py`
+ * (ADR-200). Byte-identical to the Python original. No behaviour changes.
+ */
+
+function _pyTruthy(value: unknown): boolean {
+    if (value === null || value === undefined) {
+        return false;
+    }
+    if (typeof value === 'string') {
+        return value.length > 0;
+    }
+    if (typeof value === 'number') {
+        return value !== 0 && !Number.isNaN(value);
+    }
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.length > 0;
+    }
+    if (typeof value === 'object') {
+        return Object.keys(value as object).length > 0;
+    }
+    return true;
+}
+
+export function render(trace: Record<string, unknown>): string {
+    const out: string[] = ['## Council', ''];
+    const members = (_pyTruthy(trace.council) ? trace.council : []) as unknown[];
+    if (members.length === 0) {
+        out.push('(none recorded for this run)');
+        out.push('');
+        return out.join('\n');
+    }
+    for (const memberRaw of members) {
+        const member = memberRaw as Record<string, unknown>;
+        const mid = _pyTruthy(member.member_id) ? member.member_id : '(unknown)';
+        const verdict = _pyTruthy(member.verdict) ? member.verdict : '(no verdict)';
+        out.push(`### ${mid}`);
+        out.push('');
+        out.push(`> ${verdict}`);
+        const citations = (_pyTruthy(member.citations) ? member.citations : []) as unknown[];
+        if (citations.length > 0) {
+            out.push('');
+            out.push('Citations:');
+            for (const cite of citations) {
+                out.push(`- ${cite}`);
+            }
+        }
+        out.push('');
+    }
+    return out.join('\n');
+}