pi-steering TypeScript Type Reference

interface SteeringConfig {
  defaultNoOverride?: boolean;
  disabledRules?: readonly string[];
  disabledPlugins?: readonly string[];
  disableDefaults?: boolean;
  failOnWarnings?: boolean;
  plugins?: readonly Plugin[];
  rules?: readonly Rule[];
  observers?: readonly Observer[];
}

type Rule<ObsName extends string = string, Writes extends string = string> =
  | BashRule<ObsName, Writes>
  | WriteRule<ObsName, Writes>
  | EditRule<ObsName, Writes>;

interface BaseRule<ObsName extends string = string, Writes extends string = string> {
  /** Unique rule identifier. Used in override comments and audit logs. */
  name: string;

  /** Main match predicate tested against the chosen field value. */
  pattern: Pattern;

  /** Optional extra AND predicate. Rule fires only if this also matches. */
  requires?: Pattern | PredicateFn;

  /** Exemption predicate. When provided and matches, rule does NOT fire. */
  unless?: Pattern | PredicateFn;

  /** Composable predicate block. See TopLevelWhenClause. */
  when?: TopLevelWhenClause<Writes>;

  /** Message shown to the agent when blocked. */
  reason: string | ReasonFn;

  /** Override policy. Omitted: falls back to SteeringConfig.defaultNoOverride. */
  noOverride?: boolean;

  /** Observer attached to this rule — inline or referenced by name. */
  observer?: Observer | ObsName;

  /** Session-entry event types this rule's onFire may write. */
  writes?: readonly string[];

  /** Side-effect hook invoked when the rule fires, before the block verdict. */
  onFire?: (ctx: PredicateContext) => void | Promise<void>;
}

interface BashRule extends BaseRule {
  tool: "bash";
  field: "command";      // Only valid field for bash rules
}

interface WriteRule extends BaseRule {
  tool: "write";
  field: "path" | "content";
}

interface EditRule extends BaseRule {
  tool: "edit";
  field: "path" | "content";
}

interface Observer {
  /** Unique name. Referenced from Rule.observer as a string. */
  name: string;

  /** Session-entry event types this observer's onResult may write. */
  writes?: readonly string[];

  /** Filter narrowing which tool_result events fire onResult. */
  watch?: ObserverWatch;

  /** Called on every matching tool_result event. */
  onResult: (event: ToolResultEvent, ctx: ObserverContext) => void | Promise<void>;
}

interface Plugin {
  /** Unique plugin identifier. */
  name: string;

  /** Predicate handlers keyed by the when.<key> slot they register. */
  predicates?: Record<string, AnyPredicateHandler>;

  /** Rules the plugin suggests. Users opt out via disabledRules. */
  rules?: readonly Rule[];

  /** Observers the plugin ships. Referenced by name from rules. */
  observers?: readonly Observer[];

  /** New walker state dimensions the plugin introduces. */
  trackers?: Record<string, Tracker<unknown>>;

  /** Modifiers added to an existing tracker. */
  trackerExtensions?: Record<
    string,
    Record<string, Modifier<unknown> | readonly Modifier<unknown>[]>
  >;
}

interface ObserverWatch {
  /** Only fire on results from this tool. */
  toolName?: "bash" | "read" | "write" | "edit" | (string & {});

  /**
   * Per-field regex constraints on the tool INPUT.
   * Observer fires only when every listed field matches.
   */
  inputMatches?: Record<string, Pattern>;

  /** Constrain by exit code or success/failure classification. */
  exitCode?: number | "success" | "failure" | "any";
}

interface PredicateContext {
  /** Session cwd (or effective cwd of the command for bash rules). */
  cwd: string;

  /** Which pi tool is being gated. */
  tool: "bash" | "write" | "edit";

  /** Tool input — evaluator populates whichever fields apply to tool. */
  input: PredicateToolInput;

  /**
   * Engine-maintained agent-loop counter.
   * Bumped on each pi agent_start event.
   */
  agentLoopIndex: number;

  /** Run a shell command. Memoized per (cmd, args, cwd) within a single tool_call. */
  exec: (cmd: string, args: string[], opts?: ExecOpts) => Promise<ExecResult>;

  /** Append a typed entry into pi's session JSONL. */
  appendEntry: <T>(customType: string, data?: T) => void;

  /** Read all prior typed entries of the given custom type. */
  findEntries: <T>(customType: string) => Array<{ data: T; timestamp: number }>;

  /**
   * Walker state snapshot for the command being evaluated.
   * Populated only for bash rules. Undefined for write / edit rules.
   */
  walkerState?: Readonly<WhenWalkerState>;
}

interface WhenWalkerState {
  /** Effective cwd at this ref, per cwdTracker. "unknown" when unresolvable. */
  readonly cwd: string;

  /** Env map at this ref, per envTracker. */
  readonly env: EnvState;

  /** Additional tracker and reserved keys (e.g. branch, events). */
  readonly [key: string]: unknown;
}

// cwd — matches the command's effective cwd
when: { cwd: /\/workspace\// }
when: { cwd: { pattern: /\/workspace\//, onUnknown: "allow" } }

// happened — fires when an event has NOT occurred in scope
when: { happened: { event: "sync-done", in: "agent_loop" } }

// condition — escape-hatch arbitrary logic
when: { condition: (ctx) => ctx.input.args?.length === 0 }

// not — logical negation of a sub-clause
when: { not: { cwd: /\/personal\//, onUnknown: "block" } }

/** A plain string (treated as regex source) or a RegExp. */
type Pattern = string | RegExp;

/** A single Pattern or an OR-of-patterns array (any match counts). */
type Patterns = Pattern | Pattern[];

/** Trinary verdict returned by predicate handlers. */
type PredicateVerdict = boolean | "unknown";

type PredicateFn = (ctx: PredicateContext) => boolean | Promise<boolean>;

type PredicateHandler<A = unknown> = (
  args: A,
  ctx: PredicateContext,
) => PredicateVerdict | Promise<PredicateVerdict>;

type ReasonFn = (ctx: PredicateContext) => string | Promise<string>;

type CommandRef = {
  node: Command;         // The unbash AST Command node
  source: string;        // The original bash source string
  group: number;         // Group ID — commands in the same && / || chain share a group
  joiner?: "|" | "&&" | "||" | ";"; // Operator connecting this command to the next
};

interface Tracker<T> {
  /** Starting value. Overridden per-call via walk()'s initialState parameter. */
  initial: T;

  /** Sentinel value emitted when a modifier returns undefined (unresolvable). */
  unknown: T;

  /**
   * Modifiers keyed by command basename.
   * An array value applies modifiers left-to-right on the same ref.
   */
  modifiers: Record<string, Modifier<T> | Modifier<T>[]>;

  /**
   * How subshell boundaries affect this dimension.
   * Defaults to "isolated" (changes inside a subshell don't escape).
   */
  subshellSemantics?: "isolated" | "global";
}

// "sequential" — propagates to this command AND all subsequent siblings
type Modifier<
  T,
  TAll extends Record<string, unknown> = Record<string, unknown>
> =
  | {
      scope: "sequential";
      apply(args: readonly Word[], current: T, allState: Readonly<TAll>): T | undefined;
    }
  | {
      scope: "per-command";
      apply(args: readonly Word[], current: T, allState: Readonly<TAll>): T | undefined;
    };

type EnvState = ReadonlyMap<string, string>;

interface Harness {
  evaluate: EvaluatorRuntime["evaluate"];
  dispatch: ObserverDispatcher["dispatch"];
  readonly config: SteeringConfig;
  readonly resolved: ResolvedPluginState;
  readonly diagnostics: readonly SteeringDiagnostic[];
}

interface LoadHarnessOptions {
  /** The config under test. */
  readonly config: SteeringConfig;

  /**
   * Prepend DEFAULT_PLUGINS and DEFAULT_RULES to the config.
   * Default: false.
   */
  readonly includeDefaults?: boolean;

  /**
   * Host for exec / appendEntry. Defaults to an in-memory stub
   * whose exec rejects with a clear error.
   */
  readonly host?: EvaluatorHost;
}

interface MatrixCase {
  readonly name: string;
  readonly event: ToolCallEvent | ToolCallShorthand;
  readonly expect:
    | "block"
    | "allow"
    | { readonly block: true; readonly rule?: string };
  readonly cwd?: string;
}

interface MatrixResult {
  readonly total: number;
  readonly passed: number;
  readonly failed: number;
  readonly cases: ReadonlyArray<MatrixCaseResult>;
}

interface MockContextOptions {
  cwd?: string;                   // Defaults to "/tmp/test"
  agentLoopIndex?: number;        // Defaults to 0
  tool?: "bash" | "write" | "edit"; // Defaults to "bash"
  input?: PredicateToolInput;
  walkerState?: Partial<WhenWalkerState> & Record<string, unknown>;
  exec?: (cmd: string, args: readonly string[], opts?: ExecOpts) => ExecResult | Promise<ExecResult>;
  entries?: ReadonlyArray<MockEntry>;
  toolCallEvents?: Readonly<Record<string, readonly SyntheticEntry[]>>;
}

interface SteeringDiagnostic {
  /** "warning" — safe to ignore in fail-soft mode; "error" — always throws. */
  type: "warning" | "error";

  /** Discriminator for programmatic dispatch. */
  kind: SteeringDiagnosticKind;

  /** Human-readable message with context. */
  message: string;

  /** Source file path, when applicable. */
  path?: string;
}

const DEFAULT_PLUGINS = [gitPlugin] as const satisfies readonly Plugin[];

const AGENT_LOOP_INDEX_KEY = "_agentLoopIndex" as const;