@cad0p/pi-steering 0.1.0

package/dist/define-config.js

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+/**
+ * Build a {@link SteeringConfig} with cross-reference name checking.
+ *
+ * Observer references in {@link Rule.observer} are typed against the
+ * union of observer names gathered from `plugins[*].observers` AND the
+ * top-level `observers` array — a typo produces a compile error.
+ *
+ * The `disabledRules` / `disabledPlugins` arrays are typed against the unions
+ * of registered rule / plugin names — typos rejected.
+ *
+ * `rules[].when.happened.event` and `rules[].when.happened.since` are
+ * both typed against the union of all `writes` declarations across
+ * plugin rules, plugin observers, user rules, and user observers —
+ * typos rejected. (The `since` field on the `Writes` union enforces
+ * the same contract as `event`: the sentinel event must be known to
+ * the config, not a free-form string.)
+ *
+ * Runtime behavior: returns a shallow copy of the input with optional
+ * fields normalized from `readonly` arrays to mutable arrays (the
+ * {@link SteeringConfig} shape doesn't constrain mutability). The
+ * return value is safe to pass to the loader / buildConfig.
+ *
+ * ## Authoring pattern — preserving observer/plugin names for inference
+ *
+ * For compile-time typo detection on rule `observer` references, declare
+ * your observers and plugins with `as const satisfies` so TypeScript
+ * preserves the literal `name` values through to `AllObserverNames`:
+ *
+ *     const myObs = {
+ *       name: "description-read",
+ *       onResult: (event, ctx) => { ... },
+ *     } as const satisfies Observer;
+ *
+ *     const myPlugin = {
+ *       name: "my-plugin",
+ *       observers: [{ name: "sync-done", onResult: ... }],
+ *     } as const satisfies Plugin;
+ *
+ * Authors who prefer type annotations (`const myObs: Observer = ...`)
+ * get widened `name: string`, which collapses `AllObserverNames` to
+ * `string` and silently disables typo detection. Use `as const satisfies`
+ * to keep the inference.
+ *
+ * ## Behavior with no observers declared
+ *
+ * When no plugins contribute observers AND no inline `observers[]` is
+ * passed, `AllObserverNames` resolves to `never`, which causes ANY
+ * string `observer` reference on a Rule to be a compile error. This is
+ * deliberate — fail-closed on unknown observer names. For configs that
+ * deliberately reference observers by name without registering them
+ * inline (e.g., deferred to runtime), use `satisfies SteeringConfig`
+ * as a fallback; you lose typo detection but regain flexibility.
+ *
+ * ## Hover ergonomics for plugin-predicate JSDoc
+ *
+ * The `const R extends readonly Rule[]` signature narrows the
+ * contextual type of inline rule literals to their `const`-inferred
+ * shape, bypassing the homomorphic mapped-type linkage that surfaces
+ * source-declared JSDoc on hover (e.g. on `when.isClean:`). Factor
+ * rules out into `const myRule = { ... } as const satisfies Rule`
+ * bindings before passing them to `defineConfig` to keep the
+ * hover-rich shape; see the
+ * `examples/dynamic-reason-runtime-cwd/steering.ts` example. The
+ * `as const` modifier on the binding (and the `const R` modifier on
+ * the signature) preserves each rule's literal `name` so
+ * `disabledRules` typo detection fires — the alternatives `: Rule`
+ * and bare `satisfies Rule` restore hover but widen the inferred
+ * type and collapse typo detection (and `when.happened.event`
+ * narrowing across declared `writes`).
+ *
+ * @example
+ *   export default defineConfig({
+ *     plugins: [gitPlugin],
+ *     observers: [descriptionReadObserver],
+ *     rules: [
+ *       { name: "must-read-docs", ..., observer: "description-read" },
+ *     ],
+ *   });
+ */
+export function defineConfig(config) {
+    // Runtime work is minimal: copy the supplied config, widening the
+    // `readonly` tuple slots back to plain arrays for downstream
+    // consumers (loader, evaluator) that don't care about the tuple
+    // literal types. The generic machinery's job is done at the call
+    // site — once we return, we return plain SteeringConfig.
+    const out = {};
+    if (config.defaultNoOverride !== undefined) {
+        out.defaultNoOverride = config.defaultNoOverride;
+    }
+    if (config.disabledRules !== undefined) {
+        out.disabledRules = [...config.disabledRules];
+    }
+    if (config.disabledPlugins !== undefined) {
+        out.disabledPlugins = [...config.disabledPlugins];
+    }
+    if (config.disableDefaults !== undefined) {
+        out.disableDefaults = config.disableDefaults;
+    }
+    if (config.failOnWarnings !== undefined) {
+        out.failOnWarnings = config.failOnWarnings;
+    }
+    if (config.plugins !== undefined) {
+        // Cast: `readonly Plugin[]` → `Plugin[]` (shape is identical;
+        // the loader never mutates the array, but SteeringConfig
+        // doesn't require readonly).
+        out.plugins = [...config.plugins];
+    }
+    if (config.rules !== undefined) {
+        out.rules = [...config.rules];
+    }
+    if (config.observers !== undefined) {
+        out.observers = [...config.observers];
+    }
+    return out;
+}
+//# sourceMappingURL=define-config.js.map

package/dist/define-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-config.js","sourceRoot":"","sources":["../src/define-config.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,uBAAuB;AA4PvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,MAAM,UAAU,YAAY,CAO1B,MAAuC;IACvC,kEAAkE;IAClE,6DAA6D;IAC7D,gEAAgE;IAChE,iEAAiE;IACjE,yDAAyD;IACzD,MAAM,GAAG,GAAmB,EAAE,CAAC;IAC/B,IAAI,MAAM,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;QAC3C,GAAG,CAAC,iBAAiB,GAAG,MAAM,CAAC,iBAAiB,CAAC;IACnD,CAAC;IACD,IAAI,MAAM,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QACvC,GAAG,CAAC,aAAa,GAAG,CAAC,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;IAChD,CAAC;IACD,IAAI,MAAM,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;QACzC,GAAG,CAAC,eAAe,GAAG,CAAC,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC;IACpD,CAAC;IACD,IAAI,MAAM,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;QACzC,GAAG,CAAC,eAAe,GAAG,MAAM,CAAC,eAAe,CAAC;IAC/C,CAAC;IACD,IAAI,MAAM,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QACxC,GAAG,CAAC,cAAc,GAAG,MAAM,CAAC,cAAc,CAAC;IAC7C,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACjC,8DAA8D;QAC9D,yDAAyD;QACzD,6BAA6B;QAC7B,GAAG,CAAC,OAAO,GAAG,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IACD,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/B,GAAG,CAAC,KAAK,GAAG,CAAC,GAAG,MAAM,CAAC,KAAK,CAAW,CAAC;IAC1C,CAAC;IACD,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACnC,GAAG,CAAC,SAAS,GAAG,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/define-predicate.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `definePredicate<T>` — ~5-LOC helper for declaring typed plugin
+ * predicate handlers.
+ *
+ * Parallels {@link defineConfig} — pure pass-through at runtime, all
+ * the value is in the type signature. Narrows the handler's first
+ * argument to the supplied type parameter `T` so the body reads like
+ * a plain function on typed args, without the author needing to
+ * write the annotation twice (once on the declaration, once on the
+ * handler's `args` parameter). The `PredicateHandler<T>` return
+ * preserves that narrowing when the result is assigned to a local
+ * variable; the {@link Plugin.predicates} registry slot then accepts
+ * it cast-free via {@link AnyPredicateHandler} (= `PredicateHandler<any>`),
+ * which uses TS bivariance to admit typed handlers directly.
+ *
+ * See ADR §10 for the motivating usage.
+ */
+import type { PredicateHandler } from "./schema.ts";
+/**
+ * Sugar for declaring a typed {@link PredicateHandler}. The handler
+ * is returned unchanged at runtime; the generic parameter `T`
+ * narrows the handler's `args` parameter to the author's intended
+ * shape. Return type is `PredicateHandler<T>`, so authors threading
+ * the result through local variables keep the narrowed arg type.
+ * The registry slot at {@link Plugin.predicates} accepts the result
+ * cast-free via {@link AnyPredicateHandler}.
+ *
+ * @example
+ *   interface CommitFormatArgs {
+ *     pattern: RegExp;
+ *     onUnknown?: "allow" | "block";
+ *   }
+ *
+ *   export const commitFormat = definePredicate<CommitFormatArgs>(
+ *     (args, ctx) => {
+ *       // `args` is narrowed to CommitFormatArgs here.
+ *       const msg = extractCommitMessage(ctx.input.args ?? []);
+ *       return args.pattern.test(msg);
+ *     },
+ *   );
+ *
+ *   // Plug into a plugin:
+ *   export const gitPlugin: Plugin = {
+ *     name: "git",
+ *     predicates: { commitFormat },
+ *   };
+ */
+export declare function definePredicate<T>(handler: PredicateHandler<T>): PredicateHandler<T>;
+//# sourceMappingURL=define-predicate.d.ts.map

package/dist/define-predicate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-predicate.d.ts","sourceRoot":"","sources":["../src/define-predicate.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAC3B,gBAAgB,CAAC,CAAC,CAAC,CAErB"}

package/dist/define-predicate.js

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+/**
+ * Sugar for declaring a typed {@link PredicateHandler}. The handler
+ * is returned unchanged at runtime; the generic parameter `T`
+ * narrows the handler's `args` parameter to the author's intended
+ * shape. Return type is `PredicateHandler<T>`, so authors threading
+ * the result through local variables keep the narrowed arg type.
+ * The registry slot at {@link Plugin.predicates} accepts the result
+ * cast-free via {@link AnyPredicateHandler}.
+ *
+ * @example
+ *   interface CommitFormatArgs {
+ *     pattern: RegExp;
+ *     onUnknown?: "allow" | "block";
+ *   }
+ *
+ *   export const commitFormat = definePredicate<CommitFormatArgs>(
+ *     (args, ctx) => {
+ *       // `args` is narrowed to CommitFormatArgs here.
+ *       const msg = extractCommitMessage(ctx.input.args ?? []);
+ *       return args.pattern.test(msg);
+ *     },
+ *   );
+ *
+ *   // Plug into a plugin:
+ *   export const gitPlugin: Plugin = {
+ *     name: "git",
+ *     predicates: { commitFormat },
+ *   };
+ */
+export function definePredicate(handler) {
+    return handler;
+}
+//# sourceMappingURL=define-predicate.js.map

package/dist/define-predicate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-predicate.js","sourceRoot":"","sources":["../src/define-predicate.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,uBAAuB;AAsBvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,eAAe,CAC7B,OAA4B;IAE5B,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/evaluator-internals/context.d.ts

@@ -0,0 +1,186 @@
+/**
+ * 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 } from "@earendil-works/pi-coding-agent";
+import type { ExecOpts, 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"];
+}
+/**
+ * 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 declare function createExecCache(host: EvaluatorHost, sessionCwd: string): PredicateContext["exec"];
+/**
+ * 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 declare const AGENT_LOOP_INDEX_KEY: "_agentLoopIndex";
+/**
+ * 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 declare function isPlainObject(x: unknown): x is Record<string, unknown>;
+/**
+ * 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 declare function createAppendEntry(host: EvaluatorHost, agentLoopIndex: number, findEntriesCache?: Map<string, Array<{
+    data: unknown;
+    timestamp: number;
+}>>): PredicateContext["appendEntry"];
+/**
+ * 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 declare function createFindEntries(ctx: ExtensionContext, cache?: Map<string, Array<{
+    data: unknown;
+    timestamp: number;
+}>>): PredicateContext["findEntries"];
+/**
+ * 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 declare function createSessionEntryCache(): Map<string, Array<{
+    data: unknown;
+    timestamp: number;
+}>>;
+export type { ExecOpts };
+//# sourceMappingURL=context.d.ts.map

package/dist/evaluator-internals/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/evaluator-internals/context.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAGjB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,QAAQ,EAAc,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAE3E;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAC3B,4CAA4C;IAC5C,WAAW,EAAE,YAAY,CAAC,aAAa,CAAC,CAAC;CAC1C;AAyBD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,aAAa,EACnB,UAAU,EAAE,MAAM,GACjB,gBAAgB,CAAC,MAAM,CAAC,CAa1B;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,EAAG,iBAA0B,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOtE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,aAAa,EACnB,cAAc,EAAE,MAAM,EACtB,gBAAgB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,GAC1E,gBAAgB,CAAC,aAAa,CAAC,CAajC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,gBAAgB,EACrB,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,GAC/D,gBAAgB,CAAC,aAAa,CAAC,CAwBjC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,IAAI,GAAG,CAC5C,MAAM,EACN,KAAK,CAAC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAC5C,CAEA;AAID,YAAY,EAAE,QAAQ,EAAE,CAAC"}

package/dist/evaluator-internals/context.js

@@ -0,0 +1,219 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+/**
+ * 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, args, cwd) {
+    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) {
+    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, sessionCwd) {
+    const cache = new Map();
+    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 = { 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";
+/**
+ * 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) {
+    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, agentLoopIndex, findEntriesCache) {
+    return (customType, data) => {
+        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, cache) {
+    const entryCache = cache ?? new Map();
+    return (customType) => {
+        const hit = entryCache.get(customType);
+        if (hit !== undefined) {
+            return hit;
+        }
+        const out = [];
+        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,
+                timestamp: Number.isNaN(ts) ? 0 : ts,
+            });
+        }
+        entryCache.set(customType, out);
+        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() {
+    return new Map();
+}
+//# sourceMappingURL=context.js.map

package/dist/evaluator-internals/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/evaluator-internals/context.ts"],"names":[],"mappings":"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"}

package/dist/evaluator-internals/override.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 declare function extractOverride(text: string, ruleName: string): string | null;
+//# sourceMappingURL=override.d.ts.map

package/dist/evaluator-internals/override.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"override.d.ts","sourceRoot":"","sources":["../../src/evaluator-internals/override.ts"],"names":[],"mappings":"AAoCA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA6B7E"}