@cad0p/pi-steering 0.1.0

package/src/evaluator-internals/context.ts

@@ -0,0 +1,290 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * Predicate context construction for the v2 evaluator.
+ *
+ * Two concerns live here because they collaborate tightly:
+ *
+ *   1. `createExecCache` — memoizes `exec(cmd, args, opts)` by
+ *      `(cmd, args, cwd)` so every rule evaluated for ONE tool_call
+ *      sees the same result for the same query, without re-running the
+ *      underlying child process. A fresh cache is created per
+ *      tool_call; cross-call results are never shared.
+ *   2. `createFindEntries` — wraps pi's `sessionManager.getEntries()`
+ *      into the {@link PredicateContext.findEntries} shape, filtering
+ *      to `type: "custom"` entries by `customType` and flattening to
+ *      `{ data, timestamp }` (timestamps normalized from ISO strings to
+ *      epoch ms, matching what observers producing entries can rely on).
+ *
+ * The evaluator itself assembles the final {@link PredicateContext}
+ * from these closures plus per-candidate fields (cwd / tool / input /
+ * agentLoopIndex) as an object literal — no helper needed once the shape
+ * is shared across bash and write/edit code paths.
+ *
+ * Kept internal (under `evaluator-internals/`) so consumers can swap
+ * the evaluator without inheriting its helper surface. The only
+ * re-export is through `../evaluator.ts`.
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ExecOptions as PiExecOptions,
+  ExecResult as PiExecResult,
+} from "@earendil-works/pi-coding-agent";
+import type { ExecOpts, ExecResult, PredicateContext } from "../schema.ts";
+
+/**
+ * Narrow host surface the evaluator needs from the pi runtime. Lets
+ * tests pass a stub without building a full fake `ExtensionAPI`, and
+ * keeps the evaluator decoupled from the unrelated parts of pi's API
+ * (tool registration, slash commands, OAuth, …).
+ */
+export interface EvaluatorHost {
+  /** See {@link ExtensionAPI.exec}. */
+  exec: ExtensionAPI["exec"];
+  /** See {@link ExtensionAPI.appendEntry}. */
+  appendEntry: ExtensionAPI["appendEntry"];
+}
+
+/**
+ * Key used by the per-tool-call exec cache. Null-byte separator is safe
+ * because neither a command path nor POSIX argv can legitimately contain
+ * a NUL byte; collisions are impossible in practice.
+ */
+function execCacheKey(
+  cmd: string,
+  args: readonly string[],
+  cwd: string,
+): string {
+  return `${cmd}\x00${args.join("\x00")}\x00${cwd}`;
+}
+
+/**
+ * Bridge pi's `ExecResult` (uses `code`) to the schema's `ExecResult`
+ * (uses `exitCode`). Dropping `killed` is intentional — predicate
+ * authors don't need to distinguish "timed out" from "exited
+ * non-zero"; both surface as a non-zero exit for guardrail purposes.
+ */
+function toSchemaExecResult(r: PiExecResult): ExecResult {
+  return { stdout: r.stdout, stderr: r.stderr, exitCode: r.code };
+}
+
+/**
+ * Create a tool_call-scoped exec function that memoizes by
+ * `(cmd, args, cwd)`. Caches only the PROMISE so concurrent
+ * predicate evaluations that hit the same key await the same
+ * in-flight child process — not N redundant ones.
+ *
+ * `opts.cwd` defaults to `sessionCwd` (mirroring how predicates see
+ * their "current cwd" via {@link PredicateContext.cwd}). `timeoutMs`
+ * is forwarded as `timeout`.
+ */
+export function createExecCache(
+  host: EvaluatorHost,
+  sessionCwd: string,
+): PredicateContext["exec"] {
+  const cache = new Map<string, Promise<ExecResult>>();
+  return (cmd, args, opts) => {
+    const cwd = opts?.cwd ?? sessionCwd;
+    const key = execCacheKey(cmd, args, cwd);
+    const hit = cache.get(key);
+    if (hit !== undefined) return hit;
+    const piOpts: PiExecOptions = { cwd };
+    if (opts?.timeoutMs !== undefined) piOpts.timeout = opts.timeoutMs;
+    const p = host.exec(cmd, args, piOpts).then(toSchemaExecResult);
+    cache.set(key, p);
+    return p;
+  };
+}
+
+/**
+ * Key under which the engine auto-injects the current `agentLoopIndex`
+ * into every entry written via `PredicateContext.appendEntry` or
+ * `ObserverContext.appendEntry`. Rules using
+ * `when.happened: { in: "agent_loop" }` filter session entries by
+ * comparing this key against `ctx.agentLoopIndex`.
+ *
+ * Part of the on-disk session-JSONL format, exposed as a public
+ * module-level constant. Re-exported from the package root
+ * so plugin authors who manually inspect entries via
+ * `findEntries` can import the constant by name rather than
+ * hardcoding the string — a future rename would then break at
+ * import time instead of silently producing un-filtered entries.
+ */
+export const AGENT_LOOP_INDEX_KEY = "_agentLoopIndex" as const;
+
+/**
+ * Narrow "is plain object" guard used to distinguish payloads that
+ * are safe to merge into (spread) from payloads that must be wrapped
+ * as `{ value, _agentLoopIndex }`.
+ *
+ * Anything that is NOT a plain object (arrays, Date, Map, Set, Error,
+ * class instances, functions, null, undefined, primitives) falls into
+ * the wrap branch. Direct `{...}` or `Object.create(null)` shapes fall
+ * into the merge branch.
+ *
+ * Two-stage detection:
+ *   1. `Object.prototype.toString.call(x)` returns `"[object Object]"`
+ *      only for plain objects and for class instances of user-defined
+ *      classes. It correctly excludes arrays, Date, Map, Set, Error,
+ *      etc.
+ *   2. A prototype check then rejects user-class instances: plain
+ *      objects have `Object.prototype` (or `null` for
+ *      `Object.create(null)`) as their prototype; `new Box(...)` has
+ *      `Box.prototype`, which is neither.
+ *
+ * The explicit `Array.isArray` check is belt-and-suspenders — some
+ * runtimes have historically misreported arrays via `toString`, and
+ * the array case is the one most likely to hit this wrapper (an
+ * observer appending a list of watched paths). Cheap to check twice.
+ */
+export function isPlainObject(x: unknown): x is Record<string, unknown> {
+  if (x === null || typeof x !== "object") return false;
+  if (Array.isArray(x)) return false;
+  if (Object.prototype.toString.call(x) !== "[object Object]") return false;
+  const proto = Object.getPrototypeOf(x);
+  if (proto !== null && proto !== Object.prototype) return false;
+  return true;
+}
+
+/**
+ * Wrap a raw `host.appendEntry` so every write auto-injects the
+ * current `agentLoopIndex` into the payload. Plain-object payloads
+ * get the field merged in; everything else — primitives, arrays,
+ * `Date`, `Map`, `Set`, `Error`, class instances, functions, null,
+ * undefined — is wrapped as `{ value, _agentLoopIndex }` so
+ * downstream consumers always see a consistent object shape.
+ *
+ * The "everything else" branch exists because the naive spread
+ * (`{ ...data, ... }`) silently corrupts non-plain objects: arrays
+ * become pseudo-objects with string-indexed keys, Date / Map / Set /
+ * Error instances lose their internal state entirely, etc. Wrapping
+ * under `value` preserves the original reference unchanged.
+ *
+ * The returned closure matches both {@link PredicateContext.appendEntry}
+ * and {@link ObserverContext.appendEntry} so the evaluator and the
+ * observer dispatcher share one wrapper.
+ *
+ * `findEntriesCache` (optional) is a cache map shared with a sibling
+ * {@link createFindEntries} closure. When supplied, every `appendEntry`
+ * call invalidates the cache entry for the written `customType` so
+ * the next `findEntries(customType)` re-reads the session JSONL and
+ * sees the newly-written entry (S2/E1; see ../INVARIANTS.md for the
+ * S/E tag glossary). Omit the parameter to keep
+ * the pre-S2 behaviour (no invalidation) — handy for tests or callers
+ * that don't pair the two closures.
+ */
+export function createAppendEntry(
+  host: EvaluatorHost,
+  agentLoopIndex: number,
+  findEntriesCache?: Map<string, Array<{ data: unknown; timestamp: number }>>,
+): PredicateContext["appendEntry"] {
+  return <T>(customType: string, data?: T) => {
+    const tagged = isPlainObject(data)
+      ? { ...data, [AGENT_LOOP_INDEX_KEY]: agentLoopIndex }
+      : { value: data, [AGENT_LOOP_INDEX_KEY]: agentLoopIndex };
+    host.appendEntry(customType, tagged);
+    // S2/E1: drop the cached read for this customType so a later
+    // `findEntries(customType)` call from the same phase re-materializes
+    // the list and sees the write we just made. Without this, a rule's
+    // `onFire` that writes + a later rule's `when.happened` that reads
+    // see inconsistent snapshots within one tool_call.
+    findEntriesCache?.delete(customType);
+  };
+}
+
+/**
+ * Adapt pi's `sessionManager.getEntries()` into the typed-and-filtered
+ * view predicates (and observers) expect.
+ *
+ * Strategy:
+ *   - pick only `type: "custom"` entries (the shape `pi.appendEntry`
+ *     produces — see `CustomEntry` in pi's session-manager),
+ *   - filter by `customType`,
+ *   - project to `{ data, timestamp }` where `timestamp` is epoch-ms
+ *     (parsed from the entry's ISO string). Epoch-ms is what turn-state
+ *     checks want for chronological comparisons without having to
+ *     re-parse.
+ *
+ * Results are memoized PER invocation of `createFindEntries` by
+ * customType. The evaluator rebuilds the closure on every tool_call;
+ * the observer dispatcher rebuilds on every tool_result. So each phase
+ * sees a consistent snapshot across reads.
+ *
+ * Cross-rule write visibility (S2/E1): when the same phase also uses
+ * a paired {@link createAppendEntry} with the SAME cache map, a write
+ * during rule A's `onFire` invalidates the cached read for that
+ * customType so rule B's `when.happened` predicate sees the fresh
+ * entry. Callers that want this consistency pass in a shared cache
+ * via the optional `cache` parameter; callers that omit it get the
+ * old per-closure snapshot behaviour (pre-S2), which is sound only
+ * when the closure never interleaves reads with writes.
+ *
+ * The `ctx` argument is the pi `ExtensionContext` — we re-read
+ * `getEntries()` only on a cache miss. Cache keys are per-closure (or
+ * per shared cache) so cross-tool_call or cross-tool_result reads
+ * always see the freshest state (a new closure = a new cache).
+ */
+export function createFindEntries(
+  ctx: ExtensionContext,
+  cache?: Map<string, Array<{ data: unknown; timestamp: number }>>,
+): PredicateContext["findEntries"] {
+  const entryCache =
+    cache ?? new Map<string, Array<{ data: unknown; timestamp: number }>>();
+  return <T>(customType: string) => {
+    const hit = entryCache.get(customType);
+    if (hit !== undefined) {
+      return hit as Array<{ data: T; timestamp: number }>;
+    }
+    const out: Array<{ data: T; timestamp: number }> = [];
+    for (const entry of ctx.sessionManager.getEntries()) {
+      if (entry.type !== "custom") continue;
+      if (entry.customType !== customType) continue;
+      const ts = Date.parse(entry.timestamp);
+      out.push({
+        data: entry.data as T,
+        timestamp: Number.isNaN(ts) ? 0 : ts,
+      });
+    }
+    entryCache.set(
+      customType,
+      out as Array<{ data: unknown; timestamp: number }>,
+    );
+    return out;
+  };
+}
+
+/**
+ * Allocate a fresh session-entry cache shared between a paired
+ * {@link createFindEntries} + {@link createAppendEntry} for the same
+ * tool_call (evaluator) or tool_result (observer dispatcher) phase.
+ *
+ * Using a shared cache gives two guarantees the evaluator + dispatcher
+ * rely on:
+ *
+ *   1. Consistent reads: N calls to `findEntries(type)` within one
+ *      phase materialize the entry list ONCE per type.
+ *   2. Write-through-reads (S2/E1): a write via the paired
+ *      `appendEntry` invalidates that type's cached list, so the next
+ *      read re-scans the session JSONL and observes the write. Without
+ *      this, a rule's `onFire` appending X followed by a later rule's
+ *      `when.happened: { event: X }` would read a stale pre-write
+ *      snapshot.
+ *
+ * Consumers who don't need write-through-reads (tests, one-shot
+ * `findEntries` calls) can pass a fresh cache or omit the parameter
+ * on both constructors — the closures then each get their own cache
+ * map and behave like the pre-S2 implementation.
+ */
+export function createSessionEntryCache(): Map<
+  string,
+  Array<{ data: unknown; timestamp: number }>
+> {
+  return new Map<string, Array<{ data: unknown; timestamp: number }>>();
+}
+
+// Silence a re-import of ExecOpts that older linters flag (we only use
+// the type via PredicateContext["exec"] signature above).
+export type { ExecOpts };

package/src/evaluator-internals/override.test.ts

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * Unit tests for `extractOverride` — the inline override-comment
+ * detector the v2 evaluator uses to surface `# steering-override:
+ * <rule> — <reason>` annotations on bash / write / edit inputs.
+ *
+ * Ported from the v1 suite in `../../evaluator.test.ts` (the
+ * `describe("extractOverride", ...)` block) so the v2 module is
+ * directly pinned against the v1 behavior it claims parity with.
+ * Phase 3c deletes v1; these tests preserve every documented regex
+ * edge case independently of the evaluator pipeline.
+ *
+ * Each test targets one axis of the override grammar (leader
+ * character, separator character, empty reason, stacked overrides,
+ * mismatched rule name, …). Kept as a flat `describe` block to match
+ * the v1 shape for diff-friendly porting.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { extractOverride } from "./override.ts";
+
+describe("extractOverride", () => {
+  it("extracts reason from a hash-leader override", () => {
+    const r = extractOverride(
+      "git push --force # steering-override: no-force-push \u2014 coordinated rewrite",
+      "no-force-push",
+    );
+    assert.equal(r, "coordinated rewrite");
+  });
+
+  it("extracts reason from a slash-leader override", () => {
+    const r = extractOverride(
+      "// steering-override: no-console \u2014 debug session only",
+      "no-console",
+    );
+    assert.equal(r, "debug session only");
+  });
+
+  it("accepts em dash, en dash, and hyphen as separators", () => {
+    assert.equal(
+      extractOverride("# steering-override: r \u2014 em", "r"),
+      "em",
+    );
+    assert.equal(
+      extractOverride("# steering-override: r \u2013 en", "r"),
+      "en",
+    );
+    assert.equal(
+      extractOverride("# steering-override: r - hyphen", "r"),
+      "hyphen",
+    );
+  });
+
+  it("returns null when no override is present", () => {
+    assert.equal(extractOverride("git push --force", "no-force-push"), null);
+  });
+
+  it("returns null when the override targets a different rule", () => {
+    const r = extractOverride(
+      "# steering-override: other-rule \u2014 reason",
+      "no-force-push",
+    );
+    assert.equal(r, null);
+  });
+
+  it("returns null when reason is empty", () => {
+    const r = extractOverride("# steering-override: r \u2014   ", "r");
+    assert.equal(r, null);
+  });
+
+  it("stacked overrides: looking up first rule returns its reason only", () => {
+    const text =
+      "cmd # steering-override: rule-a \u2014 reason-a # steering-override: rule-b \u2014 reason-b";
+    assert.equal(extractOverride(text, "rule-a"), "reason-a");
+  });
+
+  it("stacked overrides: looking up second rule returns its reason only", () => {
+    const text =
+      "cmd # steering-override: rule-a \u2014 reason-a # steering-override: rule-b \u2014 reason-b";
+    assert.equal(extractOverride(text, "rule-b"), "reason-b");
+  });
+
+  it("stacked overrides: unrelated lookup returns null (no bleed from either)", () => {
+    const text =
+      "cmd # steering-override: rule-a \u2014 reason-a # steering-override: rule-b \u2014 reason-b";
+    assert.equal(extractOverride(text, "rule-c"), null);
+  });
+
+  it("stacked overrides: empty reason on first is skipped, scanner finds second match for same rule", () => {
+    // First `foo` override has no reason (whitespace only). The scanner
+    // must keep going and surface the second `foo` override's reason.
+    const text =
+      "# steering-override: foo \u2014   # steering-override: foo \u2014 actual reason";
+    assert.equal(extractOverride(text, "foo"), "actual reason");
+  });
+});

package/src/evaluator-internals/override.ts

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * Inline override-comment detection for the v2 evaluator.
+ *
+ * Ported verbatim from the v1 evaluator's `extractOverride` (see
+ * `../../evaluator.ts`). Syntax and behaviour match exactly so the
+ * extension runtime can swap from v1 to v2 without users rewriting
+ * their override comments. See the v1 evaluator's JSDoc for the full
+ * syntax grammar.
+ *
+ * Exposed as a standalone module so the evaluator and its tests can
+ * assert override detection independently of the rest of the pipeline.
+ */
+
+/**
+ * Global-flag regex matching every override comment in a text blob.
+ *
+ *   leader:  `#`, `//`, `/*`, `<!--`, `--`, `%%`, `;;`
+ *   key:     `steering-override:`
+ *   name:    `[A-Za-z0-9_-]+`
+ *   sep:     `—` (em dash), `–` (en dash), or `-` (hyphen)
+ *   reason:  anything up to `*\u002f`, `-->`, or end of line
+ */
+const OVERRIDE_RE =
+  /(?:#|\/\/|\/\*|<!--|--|%%|;;)\s*steering-override:\s*([A-Za-z0-9_-]+)\s*[\u2014\u2013-]\s*(.*?)(?:\*\/|-->|$)/gm;
+
+/**
+ * Shorter marker-only regex used to detect when the lazy reason capture
+ * in {@link OVERRIDE_RE} swallowed a subsequent override marker. When the
+ * scanner finds one, it trims the reason at the marker and rewinds so
+ * the next iteration parses the subsequent override cleanly.
+ */
+const OVERRIDE_MARKER_RE = /(?:#|\/\/|\/\*|<!--|--|%%|;;)\s*steering-override:/;
+
+/**
+ * Extract an inline override-comment's reason that targets a specific
+ * rule name. Returns the trimmed reason, or null when no override
+ * addressed to `ruleName` is present (empty reasons are treated as
+ * "no override" — users must supply an explicit justification).
+ *
+ * Behaviour parity with v1 `extractOverride`:
+ *
+ *   - case-sensitive rule-name match,
+ *   - supports stacked overrides on one line (e.g.
+ *     `cmd # steering-override: a — r1 # steering-override: b — r2`),
+ *   - first-match-wins across the scanned comments,
+ *   - all leader styles from v1 accepted.
+ *
+ * The v1 implementation is the authoritative reference for edge cases
+ * — see `evaluator.ts` in this package's v1 tree.
+ */
+export function extractOverride(text: string, ruleName: string): string | null {
+  // Reset `lastIndex` — the regex is module-scoped and shared across
+  // calls. Without the reset two back-to-back calls with different
+  // texts would pick up mid-string from the previous scan.
+  OVERRIDE_RE.lastIndex = 0;
+  let m = OVERRIDE_RE.exec(text);
+  while (m !== null) {
+    let reason = m[2] ?? "";
+    // Compute where the reason capture started in the source so we
+    // can rewind the scanner if we trim a trailing next-override
+    // marker out of the lazy capture.
+    const reasonStart = (m.index ?? 0) + m[0].length - reason.length;
+    const nextIdx = reason.search(OVERRIDE_MARKER_RE);
+    if (nextIdx !== -1) {
+      reason = reason.slice(0, nextIdx);
+      OVERRIDE_RE.lastIndex = reasonStart + nextIdx;
+    }
+    if (m[1] !== ruleName) {
+      m = OVERRIDE_RE.exec(text);
+      continue;
+    }
+    reason = reason.trim();
+    if (reason === "") {
+      m = OVERRIDE_RE.exec(text);
+      continue;
+    }
+    return reason;
+  }
+  return null;
+}