@event4u/agent-config 8.4.0 → 8.4.1

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

@@ -0,0 +1,104 @@
+/**
+ * Lifecycle-hook registry assembly for the CLI entry point.
+ *
+ * TypeScript twin of `work_engine/hook_bootstrap.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
+ * nothing but `_build_hook_registry` and its chat-history helper.
+ */
+
+import type { ParsedArgs } from './cli_args.js';
+import { HookRegistry } from './hooks/index.js';
+import {
+    ChatHistoryAppendHook,
+    ChatHistoryHaltAppendHook,
+    DecisionTraceHook,
+    DirectiveSetGuardHook,
+    HaltSurfaceAuditHook,
+    MemoryVisibilityHook,
+    StateShapeValidationHook,
+    TraceHook,
+    build_decision_gate_hook,
+} from './hooks/builtin/index.js';
+import type { HookSettings} from './hooks/settings.js';
+import { load_hook_settings } from './hooks/settings.js';
+
+/**
+ * Build the CLI-side {@link HookRegistry} for one `main()` run.
+ *
+ * Reads `hooks.*` from `.agent-settings.yml` and registers the enabled hooks.
+ * The master switch `hooks.enabled` defaults to `false` when the block (or the
+ * file) is missing — the registry stays empty and golden replay flows are
+ * byte-stable.
+ *
+ * `--no-hooks` on the CLI forces an empty registry regardless of settings,
+ * which is the explicit escape hatch golden-replay test harnesses can use.
+ */
+export function _build_hook_registry(args: ParsedArgs): HookRegistry {
+    const registry = new HookRegistry();
+    if (_getattr(args, 'no_hooks', false)) {
+        return registry;
+    }
+
+    const settings_path = _getattr(args, 'hooks_config', null) as string | null;
+    const settings = load_hook_settings(settings_path);
+    if (!settings.enabled) {
+        return registry;
+    }
+
+    if (settings.trace) {
+        new TraceHook().register(registry);
+    }
+    if (settings.halt_surface_audit) {
+        new HaltSurfaceAuditHook().register(registry);
+    }
+    if (settings.state_shape_validation) {
+        new StateShapeValidationHook().register(registry);
+    }
+    if (settings.directive_set_guard) {
+        new DirectiveSetGuardHook().register(registry);
+    }
+    if (settings.decision_trace) {
+        new DecisionTraceHook().register(registry);
+    }
+    const gate_hook = build_decision_gate_hook(settings.decision_engine);
+    if (gate_hook !== null) {
+        gate_hook.register(registry);
+    }
+    if (settings.memory_visibility) {
+        new MemoryVisibilityHook({
+            memory_cadence: settings.memory_cadence,
+            visibility_off: settings.memory_visibility_off,
+        }).register(registry);
+    }
+    if (settings.chat_history_enabled) {
+        _register_chat_history_hooks(registry, settings);
+    }
+
+    return registry;
+}
+
+/**
+ * Register the structural chat-history hooks bound to the configured script.
+ *
+ * Hook-only contract (post road-to-chat-history-hook-only): only the append +
+ * halt-append hooks remain; cooperative `turn-check` / `heartbeat` hooks were
+ * removed when the cooperative always-rules were retired.
+ */
+export function _register_chat_history_hooks(registry: HookRegistry, settings: HookSettings): void {
+    const script = settings.chat_history_script;
+    new ChatHistoryAppendHook(script).register(registry);
+    new ChatHistoryHaltAppendHook(script).register(registry);
+}
+
+/** Python `getattr(obj, attr, default)` for plain object attribute access. */
+function _getattr(obj: unknown, attr: string, dflt: unknown): unknown {
+    if (obj !== null && typeof obj === 'object' && attr in (obj as Record<string, unknown>)) {
+        const v = (obj as Record<string, unknown>)[attr];
+        return v === undefined ? dflt : v;
+    }
+    return dflt;
+}

package/src/agent-src/templates/scripts/work_engine/hooks/builtin/_chat_history_base.ts

@@ -0,0 +1,189 @@
+/**
+ * Shared plumbing for chat-history hooks.
+ *
+ * TypeScript twin of `work_engine/hooks/builtin/_chat_history_base.py`
+ * (ADR-200 py2ts — work_engine.hooks.builtin subpackage). Subprocess-driven
+ * so the work-engine package stays decoupled from `scripts/chat_history.py`'s
+ * internals. The `runner` injection point is the test seam — production passes
+ * the default runner, tests pass a fake.
+ */
+import { spawnSync, type SpawnSyncReturns } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Subset of Python's `subprocess.CompletedProcess[str]` the hooks read:
+ * the return code plus the captured streams.
+ */
+export interface CompletedProcess {
+    returncode: number;
+    stdout: string;
+    stderr: string;
+}
+
+/** Callable that runs a subprocess. Production default: {@link _default_runner}. */
+export type ProcessRunner = (cmd: string[]) => CompletedProcess;
+
+export const EXIT_OK = 0;
+export const EXIT_MISSING = 10;
+export const EXIT_FOREIGN = 11;
+export const EXIT_RETURNING = 12;
+
+export function _default_runner(cmd: string[]): CompletedProcess {
+    const [program, ...args] = cmd;
+    const proc: SpawnSyncReturns<string> = spawnSync(program as string, args, {
+        encoding: 'utf8',
+    });
+    return {
+        // `null` status (signal/spawn failure) maps to a non-OK code.
+        returncode: proc.status === null ? -1 : proc.status,
+        stdout: proc.stdout ?? '',
+        stderr: proc.stderr ?? '',
+    };
+}
+
+/**
+ * Resolve the invocation for the chat-history script as a TypeScript twin.
+ *
+ * The chat-history script ships as a `.ts` file run through `tsx` — no
+ * python3 dependency. A `.py` `script_path` (the historical default /
+ * config value) is mapped to its `.ts` sibling. The `tsx` binary is found
+ * by walking up from the script's directory to a `node_modules/.bin/tsx`,
+ * falling back to `npx tsx`. Mirrors `dispatch_hook.ts::_resolve_tsx_invocation`
+ * and `run.ts::resolveTsxInvocation`.
+ */
+export function _resolve_chat_history_invocation(script_path: string): string[] {
+    const tsScript = script_path.replace(/\.py$/, '.ts');
+    const binName = process.platform === 'win32' ? 'tsx.cmd' : 'tsx';
+    const walkUp = (start: string): string | null => {
+        let dir = start;
+        for (;;) {
+            const candidate = path.join(dir, 'node_modules', '.bin', binName);
+            try {
+                if (fs.statSync(candidate).isFile()) {
+                    return candidate;
+                }
+            } catch {
+                // not here — keep walking up.
+            }
+            const parent = path.dirname(dir);
+            if (parent === dir) {
+                return null;
+            }
+            dir = parent;
+        }
+    };
+    // Script's tree first, then THIS module's package tree (the package
+    // ships tsx as a runtime dependency). `npx tsx` stays last-resort only:
+    // it runs against the consumer's npm config and fails hard on e.g.
+    // devEngines pins (the 8.1.0 EBADDEVENGINES regression).
+    const tsx =
+        walkUp(path.dirname(path.resolve(tsScript))) ??
+        walkUp(path.dirname(fileURLToPath(import.meta.url)));
+    if (tsx !== null) {
+        return [tsx, tsScript];
+    }
+    return ['npx', 'tsx', tsScript];
+}
+
+/**
+ * Shared plumbing — script path and runner.
+ *
+ * Schema v4 derives session attribution from the platform `session_id`,
+ * not from a derived first-user-msg. work-engine internal hooks have no
+ * platform session in scope, so they omit `--session-id` and entries land
+ * in the `<unknown>` session bucket.
+ */
+export class _ChatHistoryHookBase {
+    readonly script_path: string;
+    private readonly _runner: ProcessRunner;
+
+    constructor(script_path: string, options: { runner?: ProcessRunner | null } = {}) {
+        this.script_path = script_path;
+        this._runner = options.runner ?? _default_runner;
+    }
+
+    protected _invoke(...args: string[]): CompletedProcess {
+        // Run the chat-history `.ts` script through `tsx` — no python3
+        // dependency. `script_path` (a `.py` default / config value) maps to
+        // its `.ts` sibling, prefixed by the resolved `tsx` binary.
+        const cmd = [..._resolve_chat_history_invocation(this.script_path), ...args];
+        return this._runner(cmd);
+    }
+}
+
+/** Python `getattr(obj, name, default)` for a duck-typed object. */
+export function _getattr(obj: unknown, name: string, dflt: unknown): unknown {
+    if (obj !== null && typeof obj === 'object' && name in (obj as object)) {
+        return (obj as Record<string, unknown>)[name];
+    }
+    return dflt;
+}
+
+/**
+ * Python `json.dumps(obj)` with default separators (`", "`, `": "`) and
+ * `ensure_ascii=True`. Covers the simple `{"step": str}` /
+ * `{"step": str, "questions": [str, …]}` payloads the chat-history hooks
+ * build: strings, numbers, booleans, null, arrays, and plain objects in
+ * insertion order.
+ */
+export function _pyJsonDumps(value: unknown): string {
+    if (value === null || value === undefined) {
+        return 'null';
+    }
+    if (typeof value === 'boolean') {
+        return value ? 'true' : 'false';
+    }
+    if (typeof value === 'number') {
+        return String(value);
+    }
+    if (typeof value === 'string') {
+        return _jsonStrAscii(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => _pyJsonDumps(v)).join(', ')}]`;
+    }
+    if (typeof value === 'object') {
+        const obj = value as Record<string, unknown>;
+        const items = Object.keys(obj).map((k) => `${_jsonStrAscii(k)}: ${_pyJsonDumps(obj[k])}`);
+        return `{${items.join(', ')}}`;
+    }
+    return _jsonStrAscii(String(value));
+}
+
+/** Python `json.dumps(s, ensure_ascii=True)` for a single string. */
+function _jsonStrAscii(s: string): string {
+    let out = '"';
+    for (const ch of s) {
+        const code = ch.codePointAt(0) as number;
+        if (ch === '"') {
+            out += '\\"';
+        } else if (ch === '\\') {
+            out += '\\\\';
+        } else if (ch === '\n') {
+            out += '\\n';
+        } else if (ch === '\r') {
+            out += '\\r';
+        } else if (ch === '\t') {
+            out += '\\t';
+        } else if (ch === '\b') {
+            out += '\\b';
+        } else if (ch === '\f') {
+            out += '\\f';
+        } else if (code < 0x20) {
+            out += `\\u${code.toString(16).padStart(4, '0')}`;
+        } else if (code < 0x7f) {
+            out += ch;
+        } else if (code <= 0xffff) {
+            out += `\\u${code.toString(16).padStart(4, '0')}`;
+        } else {
+            const c = code - 0x10000;
+            const hi = 0xd800 + (c >> 10);
+            const lo = 0xdc00 + (c & 0x3ff);
+            out += `\\u${hi.toString(16).padStart(4, '0')}\\u${lo.toString(16).padStart(4, '0')}`;
+        }
+    }
+    return `${out}"`;
+}

package/src/agent-src/templates/scripts/work_engine/hooks/builtin/chat_history_append.ts

@@ -0,0 +1,41 @@
+/**
+ * `ChatHistoryAppendHook` — phase-boundary persistence.
+ *
+ * TypeScript twin of `work_engine/hooks/builtin/chat_history_append.py`
+ * (ADR-200 py2ts — work_engine.hooks.builtin subpackage). Fires on
+ * `after_step`. Appends a `--type phase` entry whenever a step closed with
+ * `Outcome.SUCCESS`. Failures bubble up as {@link HookError} so the runner
+ * converts them to warnings — append errors must not break the main flow.
+ */
+import { Outcome } from '../../delivery_state.js';
+import type { HookContext } from '../context.js';
+import { HookEvent } from '../events.js';
+import { HookError } from '../exceptions.js';
+import type { HookRegistry } from '../registry.js';
+import { EXIT_OK, _ChatHistoryHookBase, _getattr, _pyJsonDumps } from './_chat_history_base.js';
+
+/** Arbitrary value, mirroring the Python `Any` payload values. */
+type Any = unknown;
+
+/** Append a phase-boundary entry after every successful step. */
+export class ChatHistoryAppendHook extends _ChatHistoryHookBase {
+    register(registry: HookRegistry): void {
+        registry.register(HookEvent.AFTER_STEP, (ctx) => this._on_after_step(ctx));
+    }
+
+    private _on_after_step(ctx: HookContext): void {
+        const result = ctx.result;
+        if (
+            result === null ||
+            result === undefined ||
+            _getattr(result, 'outcome', null) !== Outcome.SUCCESS
+        ) {
+            return;
+        }
+        const payload: Record<string, Any> = { step: ctx.step_name || '<unknown>' };
+        const proc = this._invoke('append', '--type', 'phase', '--json', _pyJsonDumps(payload));
+        if (proc.returncode !== EXIT_OK) {
+            throw new HookError(`chat-history append failed (exit ${proc.returncode})`);
+        }
+    }
+}

package/src/agent-src/templates/scripts/work_engine/hooks/builtin/chat_history_halt_append.ts

@@ -0,0 +1,89 @@
+/**
+ * `ChatHistoryHaltAppendHook` — capture halt surfaces in the log.
+ *
+ * TypeScript twin of `work_engine/hooks/builtin/chat_history_halt_append.py`
+ * (ADR-200 py2ts — work_engine.hooks.builtin subpackage). Fires on `on_halt`.
+ * Records a `--type decision` entry with the step name and any pending
+ * questions so a fresh chat can resume from the persisted log alone.
+ */
+import type { HookContext } from '../context.js';
+import { HookEvent } from '../events.js';
+import { HookError } from '../exceptions.js';
+import type { HookRegistry } from '../registry.js';
+import { EXIT_OK, _ChatHistoryHookBase, _getattr, _pyJsonDumps } from './_chat_history_base.js';
+
+/** Arbitrary value, mirroring the Python `Any` payload values. */
+type Any = unknown;
+
+/** Append a decision entry whenever a step halts. */
+export class ChatHistoryHaltAppendHook extends _ChatHistoryHookBase {
+    register(registry: HookRegistry): void {
+        registry.register(HookEvent.ON_HALT, (ctx) => this._on_halt(ctx));
+    }
+
+    private _on_halt(ctx: HookContext): void {
+        let questions: string[] = [];
+        if (ctx.result !== null && ctx.result !== undefined) {
+            questions = _pyList(_pyOr(_getattr(ctx.result, 'questions', []), []));
+        }
+        if (questions.length === 0 && ctx.delivery !== null && ctx.delivery !== undefined) {
+            questions = _pyList(_pyOr(_getattr(ctx.delivery, 'questions', []), []));
+        }
+        const payload: Record<string, Any> = {
+            step: ctx.step_name || '<unknown>',
+            questions,
+        };
+        const proc = this._invoke('append', '--type', 'decision', '--json', _pyJsonDumps(payload));
+        if (proc.returncode !== EXIT_OK) {
+            throw new HookError(`chat-history halt-append failed (exit ${proc.returncode})`);
+        }
+    }
+}
+
+/** Python `a or b`. */
+function _pyOr(a: Any, b: Any): Any {
+    return _pyTruthy(a) ? a : b;
+}
+
+/** Python `list(x)` for the iterable shapes `questions` can be. */
+function _pyList(x: Any): string[] {
+    if (x === null || x === undefined) {
+        return [];
+    }
+    if (Array.isArray(x)) {
+        return [...x] as string[];
+    }
+    if (typeof x === 'string') {
+        return [...x];
+    }
+    if (typeof (x as { [Symbol.iterator]?: unknown })[Symbol.iterator] === 'function') {
+        return [...(x as Iterable<string>)];
+    }
+    return [];
+}
+
+/** Python `bool(x)` truthiness for the list / falsy shapes seen here. */
+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/hooks/builtin/decision_gate.ts

@@ -0,0 +1,193 @@
+/**
+ * `DecisionGateHook` — refuse to advance when an opt-in gate fires.
+ *
+ * TypeScript twin of `work_engine/hooks/builtin/decision_gate.py` (ADR-200
+ * py2ts — work_engine.hooks.builtin subpackage). Bridges
+ * `work_engine/scoring/decision_engine` into the dispatcher hook bus. Reads
+ * the gate config from {@link DecisionEngineSettings} and fires on
+ * `AFTER_STEP` only for the phase each gate owns.
+ *
+ * Three actions, mapped 1:1 from `evaluate_gates`:
+ *
+ * - `stop`        → throw {@link HookHalt} with a numbered-option surface.
+ * - `warn`        → throw {@link HookError} so the runner logs the reason.
+ * - `ask_timeout` → non-interactive context; apply `on_block_fallback` and
+ *                   re-resolve to `stop` or `warn`.
+ * - `ask`         → interactive context; collapses to `stop` with the prompt
+ *                   surface for the CLI integration.
+ *
+ * Default-off: when `settings.decision_engine` is `null` or every gate is
+ * `off` the hook short-circuits without examining state.
+ */
+import type {
+    GateDecision} from '../../scoring/decision_engine.js';
+import {
+    DecisionEngineSettings,
+    evaluate_gates,
+} from '../../scoring/decision_engine.js';
+import {
+    derive_confidence_band,
+    derive_risk_class,
+    summarise_memory,
+    summarise_verify,
+} from '../../scoring/decision_trace.js';
+import type { HookContext } from '../context.js';
+import { HookEvent } from '../events.js';
+import { HookError, HookHalt } from '../exceptions.js';
+import type { HookRegistry } from '../registry.js';
+
+/** Arbitrary value, mirroring the Python `Any` fields. */
+type Any = unknown;
+
+const _BLOCK_REASON_PREFIX = 'decision_gate';
+
+/**
+ * Evaluate decision-engine gates on every `AFTER_STEP`.
+ *
+ * The hook stores `settings` as a frozen reference; tests pass a fresh
+ * instance per scenario.
+ */
+export class DecisionGateHook {
+    private readonly _settings: DecisionEngineSettings;
+
+    constructor(settings: DecisionEngineSettings) {
+        this._settings = settings;
+    }
+
+    /** Register the gate callback on `AFTER_STEP`. */
+    register(registry: HookRegistry): void {
+        registry.register(HookEvent.AFTER_STEP, (ctx) => this._evaluate(ctx));
+    }
+
+    // -- lifecycle callback ------------------------------------------
+
+    private _evaluate(ctx: HookContext): void {
+        if (!this._settings.any_gate_active) {
+            return;
+        }
+        const phase = ctx.step_name;
+        if (!phase) {
+            return;
+        }
+        const delivery = ctx.delivery;
+        const memory = summarise_memory(_getattr(delivery, 'memory', null));
+        const verify = summarise_verify(_getattr(delivery, 'verify', null));
+        const ambiguity = _pyTruthy(_getattr(delivery, 'questions', null));
+        const decision = evaluate_gates(this._settings, {
+            phase,
+            confidence_band: derive_confidence_band({
+                memory_hits: memory['hits'] as number,
+                verify_claims: verify['claims'] as number,
+                verify_first_try_passes: verify['first_try_passes'] as number,
+                ambiguity_flag: ambiguity,
+            }),
+            risk_class: derive_risk_class(_getattr(delivery, 'changes', null)),
+            memory_hits: memory['hits'] as number,
+        });
+        if (decision === null) {
+            return;
+        }
+        this._apply(decision);
+    }
+
+    // -- action dispatch ----------------------------------------------
+
+    private _apply(decision: GateDecision): void {
+        const action = decision.action;
+        if (action === 'warn') {
+            throw new HookError(DecisionGateHook._format_reason(decision));
+        }
+        if (action === 'ask_timeout') {
+            const fallback = this._settings.on_block_fallback;
+            if (fallback === 'warn') {
+                throw new HookError(
+                    DecisionGateHook._format_reason(decision, 'ask_timeout'),
+                );
+            }
+            throw new HookHalt(
+                `${_BLOCK_REASON_PREFIX}:${decision.gate_id}:ask_timeout`,
+                DecisionGateHook._surface(decision, 'ask_timeout'),
+            );
+        }
+        throw new HookHalt(
+            `${_BLOCK_REASON_PREFIX}:${decision.gate_id}`,
+            DecisionGateHook._surface(decision),
+        );
+    }
+
+    // -- formatting helpers -------------------------------------------
+
+    private static _format_reason(decision: GateDecision, suffix = ''): string {
+        let tag = `${_BLOCK_REASON_PREFIX}:${decision.gate_id}`;
+        if (suffix) {
+            tag = `${tag}:${suffix}`;
+        }
+        return `${tag} — ${decision.reason}`;
+    }
+
+    private static _surface(decision: GateDecision, suffix = ''): string[] {
+        let header = `Decision-engine gate fired: ${decision.gate_id} (phase=${decision.phase})`;
+        if (suffix) {
+            header = `${header} [${suffix}]`;
+        }
+        return [
+            header,
+            `Reason: ${decision.reason}`,
+            '1) Address the gate condition and resume.',
+            '2) Lower the gate in `.agent-settings.yml` ' + '(`decision_engine` block) and resume.',
+            '3) Abort the run.',
+        ];
+    }
+}
+
+/**
+ * Construct the hook from a {@link DecisionEngineSettings}-like object.
+ * Returns `null` when the config is absent or every gate is `off`; the
+ * bootstrap layer then skips registration entirely.
+ */
+export function build_decision_gate_hook(settings: Any): DecisionGateHook | null {
+    if (settings === null || settings === undefined) {
+        return null;
+    }
+    if (!(settings instanceof DecisionEngineSettings)) {
+        return null;
+    }
+    if (!settings.any_gate_active) {
+        return null;
+    }
+    return new DecisionGateHook(settings);
+}
+
+/** Python `getattr(obj, name, default)`. */
+function _getattr(obj: Any, name: string, dflt: Any): Any {
+    if (obj !== null && typeof obj === 'object' && name in (obj as object)) {
+        return (obj as Record<string, Any>)[name];
+    }
+    return dflt;
+}
+
+/** Python `bool(x)` truthiness for the shapes `questions` can take. */
+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;
+}