@event4u/agent-config 8.4.0 → 8.4.1

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

@@ -0,0 +1,366 @@
+/**
+ * State machine stub for the `/orchestrate` command.
+ *
+ * TypeScript twin of `work_engine/orchestration.py` (ADR-200 py2ts Phase 1 —
+ * work_engine foundation). Public API names stay snake_case to mirror the
+ * Python module 1:1 (per ADR-200 — Python style is part of the contract).
+ *
+ * Reads a pipeline file conforming to
+ * `docs/contracts/orchestration-dsl-v1.md` and produces an ordered
+ * sequence of step descriptors the agent dispatches one at a time.
+ * The runtime itself is **not** in Python — each step is executed by the
+ * agent via skill / command / persona / subagent dispatch. This module
+ * holds the deterministic bookkeeping:
+ *
+ * - load + interpolate
+ * - step iteration with success / failure / when-guard tracking
+ * - output-map resolution at the end
+ *
+ * Design constraints (R1 carve-outs from
+ * `road-to-distribution-and-adoption.md`):
+ *
+ * - No external dependencies. YAML loading reuses the dispatcher's
+ *   loader so the runtime sees what the linter sees.
+ * - No side effects. The state machine never edits files, runs commands,
+ *   or emits hooks of its own. Audit emission is the caller's job.
+ * - Forward-ref free. `steps[].with` references can only reach
+ *   earlier steps; this is enforced both by the linter and at runtime.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+// Mirror of Python `re` group semantics: capture (inputs|steps), the ident,
+// and an optional `.output` suffix; `g` flag so `.sub`-style replace covers
+// every non-overlapping match like Python `re.sub`.
+const _INTERP_RE = /\$\{\{\s*(inputs|steps)\.([a-z0-9_-]+)(?:\.output)?\s*\}\}/g;
+
+/** Heterogeneous value, mirroring Python's `Any`. */
+export type Any = unknown;
+
+/** One step's record after dispatch. */
+export class StepResult {
+    step_id: string;
+    kind: string;
+    ref: string;
+    success: boolean;
+    output: string;
+    error: string | null;
+
+    constructor(
+        step_id: string,
+        kind: string,
+        ref: string,
+        success = false,
+        output = '',
+        error: string | null = null,
+    ) {
+        this.step_id = step_id;
+        this.kind = kind;
+        this.ref = ref;
+        this.success = success;
+        this.output = output;
+        this.error = error;
+    }
+}
+
+/** Bookkeeping for a single `/orchestrate` run. */
+export class PipelineState {
+    name: string;
+    inputs: Record<string, string>;
+    results: Record<string, StepResult>;
+    halted: boolean;
+    halt_reason: string | null;
+
+    constructor(args: {
+        name: string;
+        inputs: Record<string, string>;
+        results?: Record<string, StepResult>;
+        halted?: boolean;
+        halt_reason?: string | null;
+    }) {
+        this.name = args.name;
+        this.inputs = args.inputs;
+        this.results = args.results ?? {};
+        this.halted = args.halted ?? false;
+        this.halt_reason = args.halt_reason ?? null;
+    }
+}
+
+/** True when `value` is a plain object (Python `isinstance(x, dict)`). */
+function _isDict(value: unknown): value is Record<string, Any> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Python `re.Match`-style replacement function signature loader. */
+interface DispatchHookModule {
+    _load_yaml(p: string): Record<string, Any>;
+}
+
+/**
+ * Reuse the linter's loader so the runtime accepts the same shape.
+ *
+ * Walks parents to find `scripts/hooks/dispatch_hook.ts` so the loader is
+ * reachable both when this module runs from the consumer projection
+ * (`dist/agent-src/templates/scripts/work_engine/`) and from the
+ * source-of-truth tree
+ * (`packages/<pack>/.agent-src.uncondensed/templates/scripts/work_engine/`).
+ * Loaded by dynamic `import()` to avoid namespace collisions with test
+ * modules named `hooks` (the TS analogue of the Python importlib-by-path
+ * approach).
+ */
+async function _load_pipeline(p: string): Promise<Record<string, Any>> {
+    const here = fs.realpathSync(fileURLToPath(import.meta.url));
+    let candidate: string | null = null;
+    // Layout-agnostic: the dispatcher sits at `scripts/hooks/` in a consumer
+    // install + the `dist/agent-src/` projection, and at `src/scripts/hooks/`
+    // in the maintainer source tree. Probe both per parent so the loader
+    // resolves regardless of where this template runs.
+    const relCandidates = [
+        path.join('scripts', 'hooks', 'dispatch_hook.ts'),
+        path.join('src', 'scripts', 'hooks', 'dispatch_hook.ts'),
+    ];
+    let dir = path.dirname(here);
+    // Walk `here.parents` — every ancestor directory up to the filesystem root.
+    for (;;) {
+        for (const rel of relCandidates) {
+            const probe = path.join(dir, rel);
+            if (fs.existsSync(probe) && fs.statSync(probe).isFile()) {
+                candidate = probe;
+                break;
+            }
+        }
+        if (candidate !== null) {
+            break;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    if (candidate === null) {
+        throw new Error(
+            'could not locate scripts/hooks/dispatch_hook.ts (or ' +
+                `src/scripts/hooks/dispatch_hook.ts) from ${here}`,
+        );
+    }
+    const module = (await import(pathToFileURL(candidate).href)) as DispatchHookModule;
+    const doc = module._load_yaml(p);
+    if (!_isDict(doc)) {
+        throw new Error(`${p}: top-level must be a mapping`);
+    }
+    return doc;
+}
+
+/**
+ * Substitute `${{ inputs.X }}` / `${{ steps.Y.output }}` in a nested value.
+ * Unknown references throw — the linter should have caught them, but the
+ * runtime double-checks.
+ */
+export function _interpolate(value: Any, state: PipelineState): Any {
+    if (typeof value === 'string') {
+        return value.replace(_INTERP_RE, (_match, ns: string, ident: string) => {
+            if (ns === 'inputs') {
+                if (!(ident in state.inputs)) {
+                    // Mirror Python `KeyError(f"unknown input '{ident}'")`.
+                    throw new KeyError(`unknown input '${ident}'`);
+                }
+                return state.inputs[ident] as string;
+            }
+            if (!(ident in state.results)) {
+                throw new KeyError(`unknown step '${ident}'`);
+            }
+            return (state.results[ident] as StepResult).output;
+        });
+    }
+    if (_isDict(value)) {
+        const out: Record<string, Any> = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = _interpolate(v, state);
+        }
+        return out;
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => _interpolate(v, state));
+    }
+    return value;
+}
+
+/**
+ * Evaluate the limited `when` mini-language. Supports
+ * `steps.X.success` / `steps.X.failure` and equality on a single
+ * `${{ steps.X.output }}` template against a literal.
+ */
+export function _when_passes(when: string | null | undefined, state: PipelineState): boolean {
+    if (!when) {
+        return true;
+    }
+    when = when.trim();
+    const m1 = fullmatch(/steps\.([a-z0-9_-]+)\.(success|failure)/, when);
+    if (m1) {
+        const sid = m1[1] as string;
+        const kind = m1[2] as string;
+        if (!(sid in state.results)) {
+            return false;
+        }
+        const res = state.results[sid] as StepResult;
+        return kind === 'success' ? res.success : !res.success;
+    }
+    const m2 = fullmatch(/\$\{\{\s*steps\.([a-z0-9_-]+)\.output\s*\}\}\s*==\s*"([^"]*)"/, when);
+    if (m2) {
+        const sid = m2[1] as string;
+        const literal = m2[2] as string;
+        const res = state.results[sid] ?? new StepResult(sid, '', '');
+        return res.output === literal;
+    }
+    // Mirror Python `ValueError(f"unsupported when expression: {when!r}")`.
+    throw new ValueError(`unsupported when expression: ${pyRepr(when)}`);
+}
+
+/** A descriptor yielded by `iter_steps`, carrying the live state for callbacks. */
+export interface StepDescriptor {
+    id: string;
+    kind: string;
+    ref: string;
+    with: Any;
+    _state: PipelineState;
+}
+
+/**
+ * Yield interpolated step descriptors in order.
+ *
+ * Caller dispatches each descriptor via skill / command / persona /
+ * subagent and feeds the result back via {@link record_result}.
+ */
+export async function* iter_steps(
+    p: string,
+    inputs: Record<string, string>,
+): AsyncGenerator<StepDescriptor> {
+    const doc = await _load_pipeline(p);
+    const merged_inputs: Record<string, string> = {};
+    const docInputs = (doc['inputs'] as Any[] | null | undefined) || [];
+    for (const inp of docInputs) {
+        if (_isDict(inp) && typeof inp['id'] === 'string') {
+            const id = inp['id'] as string;
+            merged_inputs[id] =
+                id in inputs
+                    ? (inputs[id] as string)
+                    : (((inp['default'] as string | undefined) ?? '') as string);
+        }
+    }
+    const state = new PipelineState({
+        name: (doc['name'] as string | undefined) ?? '',
+        inputs: merged_inputs,
+    });
+    const steps = (doc['steps'] as Array<Record<string, Any>> | null | undefined) || [];
+    for (const step of steps) {
+        if (state.halted) {
+            break;
+        }
+        if (!_when_passes(step['when'] as string | null | undefined, state)) {
+            continue;
+        }
+        yield {
+            id: step['id'] as string,
+            kind: step['kind'] as string,
+            ref: step['ref'] as string,
+            with: _interpolate((step['with'] as Any) || {}, state),
+            _state: state,
+        };
+    }
+}
+
+/**
+ * Caller hands the descriptor + outcome back so subsequent steps can see
+ * `${{ steps.<id>.output }}`.
+ */
+export function record_result(
+    descriptor: StepDescriptor,
+    opts: { success: boolean; output?: string; error?: string | null },
+): void {
+    const state = descriptor._state;
+    state.results[descriptor.id] = new StepResult(
+        descriptor.id,
+        descriptor.kind,
+        descriptor.ref,
+        opts.success,
+        opts.output ?? '',
+        opts.error ?? null,
+    );
+    if (!opts.success) {
+        state.halted = true;
+        state.halt_reason = `step ${descriptor.id} failed`;
+    }
+}
+
+/**
+ * Resolve the pipeline's `outputs:` map against the captured step outputs.
+ * Returns an empty map if the pipeline declares no outputs.
+ */
+export async function resolve_outputs(
+    p: string,
+    state: PipelineState,
+): Promise<Record<string, Any>> {
+    const doc = await _load_pipeline(p);
+    const raw = (doc['outputs'] as Record<string, Any> | null | undefined) || {};
+    const out: Record<string, Any> = {};
+    for (const [k, v] of Object.entries(raw)) {
+        out[k] = _interpolate(v, state);
+    }
+    return out;
+}
+
+// ── Python-parity helpers ───────────────────────────────────────────────
+
+/** Python `KeyError` — distinct class so callers can mirror the type. */
+export class KeyError extends Error {
+    constructor(message?: string) {
+        super(message);
+        Object.setPrototypeOf(this, KeyError.prototype);
+        this.name = 'KeyError';
+    }
+}
+
+/** Python `ValueError`. */
+export class ValueError extends Error {
+    constructor(message?: string) {
+        super(message);
+        Object.setPrototypeOf(this, ValueError.prototype);
+        this.name = 'ValueError';
+    }
+}
+
+/** Python `re.fullmatch(pattern, s)` — the whole string must match. */
+function fullmatch(pattern: RegExp, s: string): RegExpExecArray | null {
+    const anchored = new RegExp(`^(?:${pattern.source})$`, pattern.flags.replace('g', ''));
+    return anchored.exec(s);
+}
+
+/**
+ * Python `repr(s)` for a string — used in the `unsupported when` error.
+ * CPython prefers single quotes, switching to double only when the string
+ * contains a single quote and no double quote.
+ */
+function pyRepr(s: string): string {
+    const hasSingle = s.includes("'");
+    const hasDouble = s.includes('"');
+    const quote = hasSingle && !hasDouble ? '"' : "'";
+    let body = '';
+    for (const ch of s) {
+        if (ch === '\\') {
+            body += '\\\\';
+        } else if (ch === quote) {
+            body += `\\${ch}`;
+        } else if (ch === '\n') {
+            body += '\\n';
+        } else if (ch === '\r') {
+            body += '\\r';
+        } else if (ch === '\t') {
+            body += '\\t';
+        } else {
+            body += ch;
+        }
+    }
+    return `${quote}${body}${quote}`;
+}

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

@@ -0,0 +1,97 @@
+/**
+ * Persona policy — behavioural parameters resolved from `state.persona`.
+ *
+ * TypeScript twin of `work_engine/persona_policy.py` (ADR-200 py2ts Phase 1 —
+ * work_engine foundation). Public API names stay snake_case to mirror the
+ * Python module 1:1 (per ADR-200 — Python style is part of the contract).
+ *
+ * Three personas ship today, each keyed by the string already carried
+ * on `DeliveryState.persona` (see
+ * `docs/contracts/implement-ticket-flow.md#personas`):
+ *
+ * `senior-engineer`
+ *     Default. Runs every step. No test widening.
+ * `qa`
+ *     Runs every step but widens the `test` scope to the full suite
+ *     (`scope=full` in the `run-tests` directive) so regressions
+ *     outside the changed paths are caught.
+ * `advisory`
+ *     Plan-only mode. `implement`, `test`, and `verify` short-
+ *     circuit to SUCCESS without doing work — the flow produces a
+ *     delivery report whose value is the plan itself, and next-command
+ *     suggestions are suppressed (nothing was committed).
+ *
+ * Unknown persona names fall back to `senior-engineer` rather than
+ * raising, so a mistyped value never aborts a run mid-flight. The
+ * caller is responsible for validating the string at the state-
+ * construction boundary if strict behaviour is needed.
+ */
+
+/** Name used when `state.persona` is empty or unrecognised. */
+export const DEFAULT_PERSONA = 'senior-engineer';
+
+/**
+ * Behavioural flags read by individual step handlers.
+ *
+ * The Python source is a frozen dataclass; this class mirrors its field
+ * order and default values. Instances are treated as read-only configuration
+ * (the Python `frozen=True` contract) — `_POLICIES` holds the only instances
+ * and callers never mutate them.
+ */
+export class PersonaPolicy {
+    readonly name: string;
+    readonly allows_implement: boolean;
+    readonly allows_test: boolean;
+    readonly allows_verify: boolean;
+    readonly widen_tests: boolean;
+    readonly suggests_next_commands: boolean;
+
+    constructor(args: {
+        name: string;
+        allows_implement?: boolean;
+        allows_test?: boolean;
+        allows_verify?: boolean;
+        widen_tests?: boolean;
+        suggests_next_commands?: boolean;
+    }) {
+        this.name = args.name;
+        this.allows_implement = args.allows_implement ?? true;
+        this.allows_test = args.allows_test ?? true;
+        this.allows_verify = args.allows_verify ?? true;
+        this.widen_tests = args.widen_tests ?? false;
+        this.suggests_next_commands = args.suggests_next_commands ?? true;
+        Object.freeze(this);
+    }
+}
+
+const _POLICIES: Record<string, PersonaPolicy> = {
+    'senior-engineer': new PersonaPolicy({ name: 'senior-engineer' }),
+    qa: new PersonaPolicy({ name: 'qa', widen_tests: true }),
+    advisory: new PersonaPolicy({
+        name: 'advisory',
+        allows_implement: false,
+        allows_test: false,
+        allows_verify: false,
+        suggests_next_commands: false,
+    }),
+};
+
+/**
+ * Return the policy for `persona`; fall back to the default on miss.
+ *
+ * `persona` is typed `unknown` because it originates from
+ * `DeliveryState.persona` which the Python dataclass declares as `str`
+ * but does not enforce — a caller may set it to `None`/`null` while
+ * wiring up a partial state in tests.
+ */
+export function resolve_policy(persona: unknown): PersonaPolicy {
+    if (typeof persona === 'string' && persona in _POLICIES) {
+        return _POLICIES[persona] as PersonaPolicy;
+    }
+    return _POLICIES[DEFAULT_PERSONA] as PersonaPolicy;
+}
+
+/** Return the persona names shipped today, in insertion order. */
+export function known_personas(): string[] {
+    return Object.keys(_POLICIES);
+}

package/src/agent-src/templates/scripts/work_engine/resolvers/diff.ts

@@ -0,0 +1,135 @@
+/**
+ * Diff resolver — wrap a unified-diff payload as an {@link Input} envelope.
+ *
+ * TypeScript twin of `work_engine/resolvers/diff.py` (ADR-200 py2ts —
+ * work_engine foundation). Public API names stay snake_case to mirror the
+ * Python module 1:1 (per ADR-200 — Python style is part of the contract).
+ *
+ * The resolver is the R3 Phase 1 entry point for the "improve this screen via
+ * diff/PR" surface: a user (or `/work` adapter) hands the engine a patch text,
+ * the resolver normalises it, and the dispatcher routes it through the UI-track
+ * `ui-improve` directive set.
+ *
+ * Like `work_engine.resolvers.prompt`, this module is intentionally thin:
+ * it normalises and rejects garbage payloads, nothing more. Reconstruction of
+ * acceptance criteria + assumptions + confidence is the job of the
+ * `refine-prompt` skill (R2 Phase 3) running against the diff once the engine
+ * hits the `refine` step. Keeping the split sharp means the envelope shape
+ * stays cheap to round-trip through state and the heavy lifting stays with the
+ * agent-directive halt where it belongs.
+ *
+ * The envelope mirrors the prompt resolver's shape so a single refiner code
+ * path can read both — `{raw, reconstructed_ac, assumptions}`. The only
+ * material difference is the heuristic header check that rejects payloads
+ * that obviously are not unified-diff text.
+ */
+import { Input } from '../state.js';
+
+export const KIND = 'diff';
+/** Wire value carried in {@link Input.kind}. */
+
+const _MIN_DIFF_LEN = 1;
+/**
+ * Minimum non-whitespace character count before the heuristic runs.
+ *
+ * The resolver is not a *quality* gate; it only rejects literally empty
+ * payloads and obvious non-diffs. A semantically empty diff (e.g., headers but
+ * no hunks) is still accepted so the refiner can score its tractability and
+ * surface a `low`-band halt where appropriate.
+ */
+
+const _DIFF_MARKERS: readonly RegExp[] = [
+    /^diff --git /m,
+    /^--- /m,
+    /^\+\+\+ /m,
+    /^@@ /m,
+    /^Index: /m,
+];
+/**
+ * Heuristic markers that flag a payload as a unified or git-style diff.
+ *
+ * A payload qualifies if **any** marker matches — the resolver accepts unified
+ * diffs (`--- `/`+++ `/`@@ `), `git diff` output (`diff --git`), and
+ * the legacy `Index: ` SVN/CVS header. The match is anchored at line start so
+ * quoted snippets inside prose ("the function `--- foo` failed") do not pass
+ * the gate.
+ */
+
+/** Raised when a payload cannot be resolved into a diff envelope. */
+export class DiffResolverError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'DiffResolverError';
+        Object.setPrototypeOf(this, DiffResolverError.prototype);
+    }
+}
+
+/**
+ * Return an {@link Input} carrying the raw diff + empty refinement slots.
+ *
+ * @param raw The user-supplied diff text. Whitespace is preserved verbatim —
+ *   the refiner reads original spacing/casing when scoring goal clarity, and
+ *   a unified-diff round-trip cannot tolerate normalised whitespace.
+ * @returns Envelope of shape
+ *   `{"kind": "diff", "data": {"raw": <raw>, "reconstructed_ac": [],
+ *   "assumptions": []}}`. The two empty lists are placeholders the
+ *   `refine-prompt` skill writes into on the rebound from `refine`.
+ * @throws {@link DiffResolverError} If `raw` is not a string, contains no
+ *   non-whitespace characters, or does not match any {@link _DIFF_MARKERS}.
+ *   The marker check guards against accidentally routing free-form prose
+ *   through the diff path.
+ */
+export function build_envelope(raw: unknown): Input {
+    if (typeof raw !== 'string') {
+        throw new DiffResolverError(
+            `diff must be a string; got ${pyTypeName(raw)}`,
+        );
+    }
+    if (pyStrip(raw).length < _MIN_DIFF_LEN) {
+        throw new DiffResolverError(
+            'diff is empty or whitespace-only — nothing to resolve',
+        );
+    }
+    if (!_DIFF_MARKERS.some((marker) => reSearch(marker, raw))) {
+        throw new DiffResolverError(
+            'payload does not look like a unified diff — expected one of ' +
+                "'diff --git', '--- ', '+++ ', '@@ ', or 'Index: ' headers",
+        );
+    }
+    return new Input(KIND, {
+        raw: raw,
+        reconstructed_ac: [],
+        assumptions: [],
+    });
+}
+
+// ── Python-parity helpers ───────────────────────────────────────────────
+
+/**
+ * Mirror Python `re.Pattern.search` for a boolean hit. The patterns carry the
+ * `m` (MULTILINE) flag so `^` matches at every line start, identical to
+ * `re.compile(..., re.MULTILINE)`. The regexes are flag-only (no `g`), so a
+ * fresh `.test` has no `lastIndex` state to reset between calls.
+ */
+function reSearch(pattern: RegExp, text: string): boolean {
+    return pattern.test(text);
+}
+
+/**
+ * Mirror Python `str.strip()` — see `resolvers/prompt.ts` for the parity note.
+ * `String.trim()` is faithful for every realistic whitespace-only payload.
+ */
+function pyStrip(s: string): string {
+    return s.trim();
+}
+
+/** Python `type(x).__name__` for the non-string `isinstance` guard branch. */
+function pyTypeName(v: unknown): string {
+    if (v === null) return 'NoneType';
+    if (v === undefined) return 'NoneType';
+    if (typeof v === 'boolean') return 'bool';
+    if (typeof v === 'string') return 'str';
+    if (typeof v === 'number') return Number.isInteger(v) ? 'int' : 'float';
+    if (Array.isArray(v)) return 'list';
+    return 'dict';
+}