@event4u/agent-config 8.4.0 → 8.4.1

package/src/agent-src/templates/scripts/work_engine/hooks/runner.ts

@@ -0,0 +1,90 @@
+/**
+ * `HookRunner` — single emit point for hook callbacks.
+ *
+ * TypeScript twin of `work_engine/hooks/runner.py` (ADR-200 py2ts —
+ * work_engine.hooks subpackage). Implements the three-tier error contract
+ * documented in `exceptions.ts`:
+ *
+ * - `HookError` from a callback → caught, a warning is emitted, the runner
+ *   continues with the next callback for the same event. Returns `null`
+ *   once the event is fully drained.
+ * - `HookHalt` from a callback → caught, **returned** to the caller with
+ *   no further callbacks invoked for this event. The caller decides how to
+ *   surface the halt. Never re-raised through the dispatch loop.
+ * - any other `Error` → propagates unchanged. Treated as a hook bug;
+ *   dispatch unwinds.
+ *
+ * Python parity note (intentional, documented): the original emits the
+ * non-fatal warning via `warnings.warn`, whose surface format
+ * (`<file>:<line>: UserWarning: …`) and per-location de-duplication are
+ * interpreter-internal and not portable. This twin emits the same message
+ * to `process.stderr` through the `warn` seam. The observable contract —
+ * the HookError is swallowed and dispatch continues — is preserved; the
+ * exact stderr warning text is normalised in the golden harness.
+ */
+import type { HookContext } from './context.js';
+import type { HookEvent } from './events.js';
+import { HookError, HookHalt } from './exceptions.js';
+import { HookRegistry } from './registry.js';
+
+/**
+ * Emit hook events through a {@link HookRegistry}.
+ *
+ * Construct once per CLI invocation, share between the CLI and the
+ * dispatcher. `emit` is the only public method on the hot path.
+ */
+export class HookRunner {
+    private _registry: HookRegistry;
+
+    constructor(registry: HookRegistry | null = null) {
+        this._registry = registry !== null ? registry : new HookRegistry();
+    }
+
+    /**
+     * Return the underlying registry.
+     *
+     * Exposed so callers can register additional hooks after construction
+     * (e.g. in tests). Not used on the hot path.
+     */
+    get registry(): HookRegistry {
+        return this._registry;
+    }
+
+    /**
+     * Fire all callbacks registered for `event`.
+     *
+     * Returns `null` when every callback completed (with or without a
+     * swallowed {@link HookError}). Returns the first {@link HookHalt}
+     * raised, after which no further callbacks are invoked for this event.
+     * Any other error propagates.
+     */
+    emit(event: HookEvent, ctx: HookContext): HookHalt | null {
+        const callbacks = this._registry.for_event(event);
+        if (callbacks.length === 0) {
+            return null;
+        }
+        for (const callback of callbacks) {
+            try {
+                callback(ctx);
+            } catch (exc) {
+                if (exc instanceof HookHalt) {
+                    return exc;
+                }
+                if (exc instanceof HookError) {
+                    this.warn(`hook ${event} raised HookError: ${exc.message}`);
+                    continue;
+                }
+                throw exc;
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Emit a non-fatal hook warning. Test seam — overridable. Mirrors the
+     * role of `warnings.warn` in the Python original.
+     */
+    protected warn(message: string): void {
+        process.stderr.write(`${message}\n`);
+    }
+}

package/src/agent-src/templates/scripts/work_engine/hooks/settings.ts

@@ -0,0 +1,260 @@
+/**
+ * Read `hooks.*` from `.agent-settings.yml` into {@link HookSettings}.
+ *
+ * TypeScript twin of `work_engine/hooks/settings.py` (ADR-200 py2ts —
+ * work_engine.hooks subpackage). Mirror of the chat-history settings pattern:
+ *
+ * - The YAML read goes through `work_engine/_lib/agent_settings.load_agent_settings`,
+ *   which cascades the whitelisted DX-comfort keys from the user-global file.
+ * - Default-permissive: a missing file or missing `hooks:` block returns
+ *   {@link HookSettings} with `enabled=false` — every hook off, every golden
+ *   replay safe by construction.
+ * - Malformed YAML / unreadable file → defaults; degrade silently.
+ * - Chat-history hooks gate on **two** switches: `hooks.chat_history.enabled`
+ *   AND the global `chat_history.enabled`. Either off → no chat-history hook.
+ */
+import { load_agent_settings, type SettingsDict } from '../_lib/agent_settings.js';
+import {
+    DecisionEngineConfigError,
+    DecisionEngineSettings,
+    parse as _parse_decision_engine,
+} from '../scoring/decision_engine.js';
+
+export const DEFAULT_SETTINGS_FILE = '.agent-settings.yml';
+export const DEFAULT_CHAT_HISTORY_SCRIPT = 'scripts/chat_history.py';
+
+/** Arbitrary value, mirroring the Python `Any` fields. */
+type Any = unknown;
+
+/** Per-field init shape for {@link HookSettings} (mirrors the dataclass). */
+export interface HookSettingsInit {
+    enabled?: boolean;
+    trace?: boolean;
+    halt_surface_audit?: boolean;
+    state_shape_validation?: boolean;
+    directive_set_guard?: boolean;
+    decision_trace?: boolean;
+    memory_visibility?: boolean;
+    memory_visibility_off?: boolean;
+    memory_cadence?: string;
+    chat_history_enabled?: boolean;
+    chat_history_script?: string;
+    decision_engine?: DecisionEngineSettings;
+}
+
+/**
+ * Resolved view of the `hooks:` block.
+ *
+ * `enabled` is the master switch. When `false` the registry stays empty
+ * regardless of the per-hook fields; this is the default when no settings
+ * file exists or no `hooks` block is declared, and it is what keeps
+ * golden-replay tests byte-stable.
+ *
+ * `decision_engine` carries the parsed gate config so {@link DecisionGateHook}
+ * can read it without re-parsing `.agent-settings.yml`.
+ */
+export class HookSettings {
+    readonly enabled: boolean;
+    readonly trace: boolean;
+    readonly halt_surface_audit: boolean;
+    readonly state_shape_validation: boolean;
+    readonly directive_set_guard: boolean;
+    readonly decision_trace: boolean;
+    readonly memory_visibility: boolean;
+    readonly memory_visibility_off: boolean;
+    readonly memory_cadence: string;
+    readonly chat_history_enabled: boolean;
+    readonly chat_history_script: string;
+    readonly decision_engine: DecisionEngineSettings;
+
+    constructor(init: HookSettingsInit = {}) {
+        this.enabled = init.enabled ?? false;
+        this.trace = init.trace ?? false;
+        this.halt_surface_audit = init.halt_surface_audit ?? false;
+        this.state_shape_validation = init.state_shape_validation ?? false;
+        this.directive_set_guard = init.directive_set_guard ?? false;
+        this.decision_trace = init.decision_trace ?? false;
+        this.memory_visibility = init.memory_visibility ?? false;
+        this.memory_visibility_off = init.memory_visibility_off ?? false;
+        this.memory_cadence = init.memory_cadence ?? 'always';
+        this.chat_history_enabled = init.chat_history_enabled ?? false;
+        this.chat_history_script = init.chat_history_script ?? DEFAULT_CHAT_HISTORY_SCRIPT;
+        this.decision_engine = init.decision_engine ?? new DecisionEngineSettings();
+        Object.freeze(this);
+    }
+}
+
+const _DEFAULT = new HookSettings();
+
+/**
+ * Return {@link HookSettings} hydrated from `.agent-settings.yml`.
+ *
+ * `settings_path` defaults to `./.agent-settings.yml` relative to the
+ * current working directory. `user_global_path` defaults to
+ * `~/.event4u/agent-config/agent-settings.yml` and only cascades the
+ * whitelisted DX-comfort keys when the project file omits them.
+ */
+export function load_hook_settings(
+    settings_path: string | null = null,
+    user_global_path: string | null = null,
+): HookSettings {
+    const path = settings_path ? settings_path : DEFAULT_SETTINGS_FILE;
+    const raw = load_agent_settings({
+        project_path: path,
+        user_global_path,
+    });
+    if (!_pyTruthy(raw)) {
+        return _DEFAULT;
+    }
+    return _settings_from_raw(raw);
+}
+
+function _settings_from_raw(data: SettingsDict): HookSettings {
+    const hooks = data['hooks'];
+    if (!_isPlainDict(hooks)) {
+        return _DEFAULT;
+    }
+    const hooksDict = hooks as Record<string, Any>;
+    const enabled = _coerce_bool(hooksDict['enabled'], false);
+
+    const decision_engine_raw = data['decision_engine'];
+    let decision_engine_settings: DecisionEngineSettings;
+    try {
+        decision_engine_settings = _parse_decision_engine(decision_engine_raw);
+    } catch (exc) {
+        if (exc instanceof DecisionEngineConfigError) {
+            decision_engine_settings = new DecisionEngineSettings();
+        } else {
+            throw exc;
+        }
+    }
+
+    if (!enabled) {
+        return new HookSettings({
+            enabled: false,
+            decision_engine: decision_engine_settings,
+        });
+    }
+
+    const chat_section = hooksDict['chat_history'];
+    let chat_block_enabled: boolean;
+    let chat_script: string;
+    if (_isPlainDict(chat_section)) {
+        const cs = chat_section as Record<string, Any>;
+        chat_block_enabled = _coerce_bool(cs['enabled'], true);
+        chat_script = String(_pyOr(cs['script'], DEFAULT_CHAT_HISTORY_SCRIPT));
+    } else {
+        chat_block_enabled = true;
+        chat_script = DEFAULT_CHAT_HISTORY_SCRIPT;
+    }
+
+    const global_chat = data['chat_history'];
+    const global_chat_on =
+        _isPlainDict(global_chat) &&
+        _coerce_bool((global_chat as Record<string, Any>)['enabled'], false);
+
+    const decision_trace_on = decision_engine_settings.surface_traces;
+
+    const memory_section = data['memory'];
+    let visibility_off = false;
+    let memory_cadence = 'always';
+    if (_isPlainDict(memory_section)) {
+        const ms = memory_section as Record<string, Any>;
+        const rawVis = ms['visibility'];
+        if (typeof rawVis === 'string' && rawVis.trim().toLowerCase() === 'off') {
+            visibility_off = true;
+        } else if (typeof rawVis === 'boolean' && rawVis === false) {
+            visibility_off = true;
+        }
+        const cadence_raw = ms['cadence'];
+        if (cadence_raw !== null && cadence_raw !== undefined) {
+            memory_cadence = String(cadence_raw).trim().toLowerCase() || 'always';
+        }
+    }
+
+    const memory_hooks = hooksDict['memory_visibility'];
+    let memory_visibility_on: boolean;
+    if (_isPlainDict(memory_hooks)) {
+        memory_visibility_on = _coerce_bool(
+            (memory_hooks as Record<string, Any>)['enabled'],
+            true,
+        );
+    } else {
+        memory_visibility_on = true;
+    }
+
+    return new HookSettings({
+        enabled: true,
+        trace: _coerce_bool(hooksDict['trace'], false),
+        halt_surface_audit: _coerce_bool(hooksDict['halt_surface_audit'], true),
+        state_shape_validation: _coerce_bool(hooksDict['state_shape_validation'], true),
+        directive_set_guard: _coerce_bool(hooksDict['directive_set_guard'], true),
+        decision_trace: decision_trace_on,
+        memory_visibility: memory_visibility_on,
+        memory_visibility_off: visibility_off,
+        memory_cadence,
+        chat_history_enabled: chat_block_enabled && global_chat_on,
+        chat_history_script: chat_script,
+        decision_engine: decision_engine_settings,
+    });
+}
+
+function _coerce_bool(value: Any, dflt: boolean): boolean {
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    if (value === null || value === undefined) {
+        return dflt;
+    }
+    if (typeof value === 'string') {
+        const s = value.trim().toLowerCase();
+        if (s === 'true' || s === 'yes' || s === 'on' || s === '1') {
+            return true;
+        }
+        if (s === 'false' || s === 'no' || s === 'off' || s === '0') {
+            return false;
+        }
+    }
+    return dflt;
+}
+
+// ── Python-parity primitives ────────────────────────────────────────────
+
+/** Python `a or b` — returns `a` when truthy, else `b`. */
+function _pyOr(a: Any, b: Any): Any {
+    return _pyTruthy(a) ? a : b;
+}
+
+/** Python `isinstance(x, dict)` — only a plain object (not array, not null). */
+function _isPlainDict(value: Any): boolean {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Python `bool(x)` truthiness: `None`/`undefined`, `False`, `0`, `""`,
+ * empty list/dict are falsy; everything else truthy.
+ */
+function _pyTruthy(value: Any): boolean {
+    if (value === null || value === undefined || value === false) {
+        return false;
+    }
+    if (value === true) {
+        return true;
+    }
+    if (typeof value === 'number') {
+        return value !== 0;
+    }
+    if (typeof value === 'string') {
+        return value.length > 0;
+    }
+    if (Array.isArray(value)) {
+        return value.length > 0;
+    }
+    if (value instanceof Map || value instanceof Set) {
+        return value.size > 0;
+    }
+    if (typeof value === 'object') {
+        return Object.keys(value as Record<string, unknown>).length > 0;
+    }
+    return true;
+}

package/src/agent-src/templates/scripts/work_engine/input_builders.ts

@@ -0,0 +1,260 @@
+/**
+ * File-based input builders and the load-or-build dispatch helper.
+ *
+ * TypeScript twin of `work_engine/input_builders.py` (ADR-200 py2ts Phase 1 —
+ * work_engine TOP/integration layer). Public API names stay snake_case to
+ * mirror the Python module 1:1 (per ADR-200 — Python style is part of the
+ * contract).
+ *
+ * Extracted from `cli.py` in P2.3 of `road-to-post-pr29-optimize.md`. Owns the
+ * CLI's "first run" path: when no state file exists, build a fresh `WorkState`
+ * from `--ticket-file`, `--prompt-file`, `--diff-file` or `--file-file`. Every
+ * builder is byte-identical in behaviour to the pre-split version.
+ */
+
+import * as fs from 'node:fs';
+
+import { _FMT_V0, _FMT_V1, type ParsedArgs } from './cli_args.js';
+import { _CLIError } from './errors.js';
+import { populate_routing } from './intent/classify.js';
+import { DiffResolverError, build_envelope as _build_diff_envelope } from './resolvers/diff.js';
+import { FileResolverError, build_envelope as _build_file_envelope } from './resolvers/file.js';
+import { PromptResolverError, build_envelope as _build_prompt_envelope } from './resolvers/prompt.js';
+import { Input, WorkState, type Dict } from './state.js';
+import { _load, _maybe_raise_legacy_hint, _read_json } from './state_io.js';
+
+/**
+ * Return the WorkState to dispatch against plus its wire format.
+ *
+ * Either loaded from `state_file` (format-preserving) or freshly built from
+ * `--ticket-file` (R1), `--prompt-file` (R2), `--diff-file` (R3) or
+ * `--file-file` (R3). Fresh ticket files default to v0 wire format so newly
+ * captured Goldens stay byte-equal with the pre-Phase-4 baseline; the prompt /
+ * diff / file paths emit v1 directly (v0 has no envelope concept for these
+ * kinds). v1 round-trips for state files already on disk in v1 shape.
+ */
+export function _load_or_build(state_file: string, args: ParsedArgs): [WorkState, string] {
+    if (_exists(state_file)) {
+        return _load(state_file);
+    }
+    _maybe_raise_legacy_hint(state_file);
+    const inputs: Array<[string, string | null]> = [
+        ['--ticket-file', args.ticket_file],
+        ['--prompt-file', args.prompt_file],
+        ['--diff-file', args.diff_file],
+        ['--file-file', args.file_file],
+    ];
+    const supplied = inputs.filter(([, value]) => value !== null).map(([name]) => name);
+    if (supplied.length > 1) {
+        throw new _CLIError(
+            `${supplied.join(', ')} are mutually exclusive; pass exactly ` +
+                'one when building an initial state.',
+        );
+    }
+    if (supplied.length === 0) {
+        throw new _CLIError(
+            `No state file at ${state_file} and no --ticket-file, ` +
+                '--prompt-file, --diff-file, or --file-file given; cannot ' +
+                'build an initial state.',
+        );
+    }
+    if (args.prompt_file !== null) {
+        return [_build_from_prompt_file(args), _FMT_V1];
+    }
+    if (args.diff_file !== null) {
+        return [_build_from_diff_file(args), _FMT_V1];
+    }
+    if (args.file_file !== null) {
+        return [_build_from_file_file(args), _FMT_V1];
+    }
+    const ticket = _read_json(args.ticket_file as string);
+    if (!_isPlainDict(ticket)) {
+        throw new _CLIError(
+            `--ticket-file must carry a JSON object; got ${_pyTypeName(ticket)}.`,
+        );
+    }
+    const work = new WorkState({ input: new Input('ticket', ticket as Dict) });
+    if (args.persona) {
+        work.persona = args.persona;
+    }
+    populate_routing(work);
+    return [work, _FMT_V0];
+}
+
+/**
+ * Read `--prompt-file` as raw text and wrap it in a prompt envelope.
+ *
+ * The file is read verbatim (UTF-8) and handed to the prompt resolver, which
+ * validates non-emptiness and returns the canonical
+ * `Input(kind="prompt", data={raw, reconstructed_ac, assumptions})` envelope.
+ * Persona is honoured the same way as the ticket path.
+ */
+export function _build_from_prompt_file(args: ParsedArgs): WorkState {
+    let raw: string;
+    try {
+        raw = fs.readFileSync(args.prompt_file as string, 'utf-8');
+    } catch (exc) {
+        throw new _CLIError(`Cannot read ${args.prompt_file}: ${_osErrorText(exc, args.prompt_file as string)}`);
+    }
+    let envelope: Input;
+    try {
+        envelope = _build_prompt_envelope(raw);
+    } catch (exc) {
+        if (exc instanceof PromptResolverError) {
+            throw new _CLIError(`--prompt-file is not a valid prompt: ${exc.message}`);
+        }
+        throw exc;
+    }
+    const work = new WorkState({ input: envelope });
+    if (args.persona) {
+        work.persona = args.persona;
+    }
+    populate_routing(work);
+    return work;
+}
+
+/**
+ * Read `--diff-file` as raw text and wrap it in a diff envelope.
+ *
+ * The file is read verbatim (UTF-8) and handed to the diff resolver, which
+ * validates the unified-diff header heuristic and returns the canonical
+ * `Input(kind="diff", data={raw, reconstructed_ac, assumptions})` envelope.
+ * `populate_routing` then routes the envelope to the UI-improve directive set
+ * without running the prose classifier.
+ */
+export function _build_from_diff_file(args: ParsedArgs): WorkState {
+    let raw: string;
+    try {
+        raw = fs.readFileSync(args.diff_file as string, 'utf-8');
+    } catch (exc) {
+        throw new _CLIError(`Cannot read ${args.diff_file}: ${_osErrorText(exc, args.diff_file as string)}`);
+    }
+    let envelope: Input;
+    try {
+        envelope = _build_diff_envelope(raw);
+    } catch (exc) {
+        if (exc instanceof DiffResolverError) {
+            throw new _CLIError(`--diff-file is not a valid diff: ${exc.message}`);
+        }
+        throw exc;
+    }
+    const work = new WorkState({ input: envelope });
+    if (args.persona) {
+        work.persona = args.persona;
+    }
+    populate_routing(work);
+    return work;
+}
+
+/**
+ * Read `--file-file` as a single-line path and wrap it in a file envelope.
+ *
+ * The file is read verbatim (UTF-8); the first non-empty line is taken as the
+ * path reference and handed to the file resolver, which validates path shape
+ * (non-empty, NUL-free, not a URL) and returns the canonical
+ * `Input(kind="file", data={path, reconstructed_ac, assumptions})` envelope.
+ * Trailing whitespace and additional lines are ignored.
+ */
+export function _build_from_file_file(args: ParsedArgs): WorkState {
+    let raw: string;
+    try {
+        raw = fs.readFileSync(args.file_file as string, 'utf-8');
+    } catch (exc) {
+        throw new _CLIError(`Cannot read ${args.file_file}: ${_osErrorText(exc, args.file_file as string)}`);
+    }
+    // Python: `raw.strip().splitlines()[0] if raw.strip() else ""`.
+    const stripped = _pyStrip(raw);
+    const path_ = stripped ? _firstLine(stripped) : '';
+    let envelope: Input;
+    try {
+        envelope = _build_file_envelope(path_);
+    } catch (exc) {
+        if (exc instanceof FileResolverError) {
+            throw new _CLIError(`--file-file does not carry a valid path: ${exc.message}`);
+        }
+        throw exc;
+    }
+    const work = new WorkState({ input: envelope });
+    if (args.persona) {
+        work.persona = args.persona;
+    }
+    populate_routing(work);
+    return work;
+}
+
+// ── Python-parity helpers ────────────────────────────────────────────────
+
+function _exists(p: string): boolean {
+    try {
+        fs.statSync(p);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/** Python `isinstance(x, dict)` — plain object only (not array, not null). */
+function _isPlainDict(value: unknown): boolean {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Python `type(x).__name__` for the JSON value shapes the messages emit. */
+function _pyTypeName(value: unknown): string {
+    if (value === null || value === undefined) {
+        return 'NoneType';
+    }
+    if (Array.isArray(value)) {
+        return 'list';
+    }
+    switch (typeof value) {
+        case 'string':
+            return 'str';
+        case 'boolean':
+            return 'bool';
+        case 'number':
+            return Number.isInteger(value as number) ? 'int' : 'float';
+        case 'object':
+            return 'dict';
+        default:
+            return typeof value;
+    }
+}
+
+/** Python `str.strip()` — strip leading/trailing whitespace. */
+function _pyStrip(s: string): string {
+    // Python str.strip() with no arg removes ASCII + Unicode whitespace; JS \s
+    // covers the common set adequately for the single-line-path contract.
+    return s.replace(/^\s+/u, '').replace(/\s+$/u, '');
+}
+
+/**
+ * Python `str.splitlines()[0]` on an already-`strip()`ped string.
+ *
+ * The caller consumes only the first line; the stripped input has no leading
+ * boundary, so splitting on the universal-newline set and returning element 0
+ * is byte-equivalent to `splitlines()[0]` for the single-line-path contract.
+ */
+function _firstLine(s: string): string {
+    const m = s.split(/\r\n|[\n\r\v\f\x1c\x1d\x1e\x85\u2028\u2029]/u);
+    return m[0] ?? '';
+}
+
+/**
+ * Approximate the text of Python's `OSError` for a failed read (mirrors
+ * `state_io.ts::_osErrorText`). The error *channel* (exit 2 via `_CLIError`)
+ * and the *prefix* ("Cannot read <path>: ") stay identical; only the trailing
+ * OS detail differs — tests normalise it.
+ */
+function _osErrorText(exc: unknown, p: string): string {
+    const e = exc as NodeJS.ErrnoException;
+    if (e && e.code === 'ENOENT') {
+        return `[Errno 2] No such file or directory: '${p}'`;
+    }
+    if (e && e.code === 'EISDIR') {
+        return `[Errno 21] Is a directory: '${p}'`;
+    }
+    if (e && e.code === 'EACCES') {
+        return `[Errno 13] Permission denied: '${p}'`;
+    }
+    return e && e.message ? e.message : String(exc);
+}