@wyattjoh/demur 0.5.0 → 0.7.0

package/src/guard.internal.ts

@@ -6,14 +6,91 @@ import {
   Predicate,
   Result,
 } from "effect";
-import { judgeEffect, Judgment } from "./judge.ts";
+import { judgeEffect, Judgment, TYPESAFE_MODEL } from "./judge.ts";
 import { Environment } from "./key.ts";
-import { applyStaticGate, decide } from "./policy.ts";
-import { gatherStateEffect, GitCommand } from "./state.ts";
-import type { CommandState, Host, Verdict } from "./types.ts";
+import {
+  applyStaticGate,
+  decide,
+  POLICY_VERSION,
+  THRESHOLDS,
+} from "./policy.ts";
+import { QUESTION_SET_VERSION } from "./questions.ts";
+import { gatherStateEffect, GitCommand, renderState } from "./state.ts";
+import type {
+  CommandState,
+  GuardEvaluation,
+  Host,
+  Verdict,
+} from "./types.ts";
 
 const PREFIX = "demur:";
 
+/**
+ * Effect-native guard implementation with replayable evidence.
+ *
+ * @param command - The shell command the agent wants to run
+ * @param cwd - Absolute working directory for the command
+ * @param agent - Which coding agent is asking
+ * @returns A fail-closed verdict and the exact evidence behind it
+ */
+export const guardEvaluationEffect = Effect.fn("guardEvaluationEffect")(
+  function* (
+    command: string,
+    cwd: string,
+    agent: Host,
+  ): Effect.fn.Return<
+    GuardEvaluation,
+    never,
+    Environment | GitCommand | Judgment
+  > {
+    const started = yield* Clock.monotonicTimeNanos;
+    const core = Effect.gen(function* () {
+      const environment = yield* Environment;
+      const disabled = isDisabled(yield* environment.get("DEMUR_DISABLE"));
+
+      if (disabled) {
+        const verdict = yield* completeVerdict(started, {
+          ...emptyEvidence,
+          decision: "allow",
+          reason: `${PREFIX} disabled via DEMUR_DISABLE.`,
+        });
+        return { verdict, evidence: undefined } satisfies GuardEvaluation;
+      }
+
+      if (command.trim() === "") {
+        const verdict = yield* completeVerdict(started, {
+          ...emptyEvidence,
+          decision: "allow",
+          reason: `${PREFIX} empty command.`,
+        });
+        return { verdict, evidence: undefined } satisfies GuardEvaluation;
+      }
+
+      const state = yield* gatherStateEffect(command, cwd, agent);
+      const verdict = yield* judgeStateCore(state, started, 0);
+      return {
+        verdict,
+        evidence: {
+          modelState: renderState(state),
+          analysis: state.analysis,
+          model: TYPESAFE_MODEL,
+          questionSetVersion: QUESTION_SET_VERSION,
+          policyVersion: POLICY_VERSION,
+          policyThresholds: { ...THRESHOLDS },
+        },
+      } satisfies GuardEvaluation;
+    });
+
+    const exit = yield* Effect.exit(core);
+    if (Exit.isSuccess(exit)) return exit.value;
+
+    return {
+      verdict: yield* unexpectedVerdict(started, exit.cause, 0),
+      evidence: undefined,
+    };
+  },
+);
+
 /**
  * Effect-native guard implementation used by the Promise boundary.
  *
@@ -27,35 +104,8 @@ export const guardEffect = Effect.fn("guardEffect")(function* (
   cwd: string,
   agent: Host,
 ): Effect.fn.Return<Verdict, never, Environment | GitCommand | Judgment> {
-  const started = yield* Clock.monotonicTimeNanos;
-  const core = Effect.gen(function* () {
-    const environment = yield* Environment;
-    const disabled = isDisabled(yield* environment.get("DEMUR_DISABLE"));
-
-    if (disabled) {
-      return yield* completeVerdict(started, {
-        ...emptyEvidence,
-        decision: "allow",
-        reason: `${PREFIX} disabled via DEMUR_DISABLE.`,
-      });
-    }
-
-    if (command.trim() === "") {
-      return yield* completeVerdict(started, {
-        ...emptyEvidence,
-        decision: "allow",
-        reason: `${PREFIX} empty command.`,
-      });
-    }
-
-    const state = yield* gatherStateEffect(command, cwd, agent);
-    return yield* judgeStateCore(state, started, 0);
-  });
-
-  const exit = yield* Effect.exit(core);
-  if (Exit.isSuccess(exit)) return exit.value;
-
-  return yield* unexpectedVerdict(started, exit.cause, 0);
+  const evaluation = yield* guardEvaluationEffect(command, cwd, agent);
+  return evaluation.verdict;
 });
 
 /**

package/src/guard.ts

@@ -1,9 +1,18 @@
 import { Layer, ManagedRuntime, Predicate } from "effect";
-import { guardEffect, judgeStateEffect } from "./guard.internal.ts";
+import {
+  guardEffect,
+  guardEvaluationEffect,
+  judgeStateEffect,
+} from "./guard.internal.ts";
 import { Judgment } from "./judge.ts";
 import { Environment } from "./key.ts";
 import { GitCommand } from "./state.ts";
-import type { CommandState, Host, Verdict } from "./types.ts";
+import type {
+  CommandState,
+  GuardEvaluation,
+  Host,
+  Verdict,
+} from "./types.ts";
 
 const PREFIX = "demur:";
 
@@ -41,6 +50,37 @@ export function guard(
     .catch((error: unknown) => unexpectedVerdict(error, started));
 }
 
+/**
+ * Judge one command while retaining the exact state and policy versions.
+ *
+ * This boundary is used only when a host has enabled local training capture;
+ * ordinary guard callers continue to receive the smaller {@link Verdict}.
+ *
+ * @param command - The shell command the agent wants to run
+ * @param cwd - Absolute working directory for the command
+ * @param agent - Which coding agent is asking
+ * @param signal - Optional cancellation signal from the host
+ * @returns The verdict and replayable evidence, when state collection occurred
+ */
+export function guardWithEvidence(
+  command: string,
+  cwd: string,
+  agent: Host,
+  signal: AbortSignal | undefined = undefined,
+): Promise<GuardEvaluation> {
+  const started = performance.now();
+
+  return runtime
+    .runPromise(
+      guardEvaluationEffect(command, cwd, agent),
+      signal === undefined ? undefined : { signal },
+    )
+    .catch((error: unknown) => ({
+      verdict: unexpectedVerdict(error, started),
+      evidence: undefined,
+    }));
+}
+
 /**
  * Judge a command from state that has already been collected.
  *

package/src/judge.ts

@@ -19,7 +19,12 @@ import {
 } from "./key.ts";
 import { COMMAND_JUDGMENTS } from "./questions.ts";
 import { renderState } from "./state.ts";
-import type { CommandState, FailureKind, Judgments } from "./types.ts";
+import type {
+  CommandState,
+  FailureKind,
+  Judgments,
+  RenderedCommandState,
+} from "./types.ts";
 
 /**
  * Default per-attempt timeout for the judgment call.
@@ -29,7 +34,10 @@ import type { CommandState, FailureKind, Judgments } from "./types.ts";
  */
 const DEFAULT_TIMEOUT_MS = 4000;
 
-const TYPESAFE_MODEL = "jev-latest";
+/**
+ * TypeSafe model used for command judgments.
+ */
+export const TYPESAFE_MODEL = "jev-latest";
 
 /**
  * Build the TypeSafe-backed Effect decision model for one API key.
@@ -90,7 +98,9 @@ export class JudgmentError extends Schema.TaggedError<JudgmentError>()(
 export class Judgment extends Context.Service<
   Judgment,
   {
-    judge(state: CommandState): Effect.Effect<JudgeSuccess, JudgmentError>;
+    judge(
+      state: RenderedCommandState,
+    ): Effect.Effect<JudgeSuccess, JudgmentError>;
   }
 >()("demur/judge/Judgment") {
   static readonly layerNoDeps = Layer.effect(
@@ -134,11 +144,11 @@ export class Judgment extends Context.Service<
       );
 
       const judge = Effect.fn("Judgment.judge")(function* (
-        state: CommandState,
+        state: RenderedCommandState,
       ): Effect.fn.Return<JudgeSuccess, JudgmentError> {
         const activeDecisionLayer = yield* getDecisionLayer();
         const result = yield* DecisionModel.decide(COMMAND_JUDGMENTS, {
-          input: renderState(state),
+          input: state,
         }).pipe(
           Effect.provide(activeDecisionLayer),
           Effect.timeout(timeoutMs),
@@ -188,9 +198,24 @@ export const judgeEffect = Effect.fn("judgeEffect")(function* (
   state: CommandState,
 ): Effect.fn.Return<JudgeSuccess, JudgmentError, Judgment> {
   const judgment = yield* Judgment;
-  return yield* judgment.judge(state);
+  return yield* judgment.judge(renderState(state));
 });
 
+/**
+ * Ask the configured judgment service about already-rendered TypeSafe state.
+ *
+ * @param state - Exact JSON state captured from an earlier invocation
+ * @returns The current question set's judgments in the Effect error channel
+ */
+export const judgeRenderedStateEffect = Effect.fn("judgeRenderedStateEffect")(
+  function* (
+    state: RenderedCommandState,
+  ): Effect.fn.Return<JudgeSuccess, JudgmentError, Judgment> {
+    const judgment = yield* Judgment;
+    return yield* judgment.judge(state);
+  },
+);
+
 const runtime = ManagedRuntime.make(Judgment.layer);
 
 /**
@@ -206,9 +231,30 @@ const runtime = ManagedRuntime.make(Judgment.layer);
 export function judge(
   state: CommandState,
   signal: AbortSignal | undefined = undefined,
+): Promise<JudgeResult> {
+  return runJudgment(judgeEffect(state), signal);
+}
+
+/**
+ * Re-run the current question set against exact previously captured state.
+ *
+ * @param state - Exact model-visible state from a version-two training record
+ * @param signal - Optional cancellation signal
+ * @returns Current raw judgments or a typed failure
+ */
+export function judgeRenderedState(
+  state: RenderedCommandState,
+  signal: AbortSignal | undefined = undefined,
+): Promise<JudgeResult> {
+  return runJudgment(judgeRenderedStateEffect(state), signal);
+}
+
+function runJudgment(
+  effect: Effect.Effect<JudgeSuccess, JudgmentError, Judgment>,
+  signal: AbortSignal | undefined,
 ): Promise<JudgeResult> {
   const program = Effect.gen(function* () {
-    const result = yield* Effect.result(judgeEffect(state));
+    const result = yield* Effect.result(effect);
     if (Result.isFailure(result)) {
       return {
         ok: false,

package/src/policy.ts

@@ -1,6 +1,15 @@
 import type { CommandAnalysis } from "./analyze.ts";
 import type { Decision, Judgments } from "./types.ts";
 
+/**
+ * Version of the policy ordering and threshold semantics.
+ *
+ * Increment this whenever composition behavior changes. Threshold values are
+ * captured separately by offline evaluation, so candidate sweeps do not need a
+ * version bump until a candidate is promoted.
+ */
+export const POLICY_VERSION = 2;
+
 /**
  * Decision thresholds applied to raw judgments.
  *
@@ -81,7 +90,7 @@ export const THRESHOLDS: Thresholds = {
   denyUnrecoverable: 0.45,
   denySharedInfrastructure: 0.5,
   denyBlastRadius: 2.0,
-  minBlastRadiusConfidence: 0.5,
+  minBlastRadiusConfidence: 0.95,
   uncertaintyBand: 0.04,
   uncertaintyBandScore: 0.12,
   staticGateMinExecution: 0.8,

package/src/questions.ts

@@ -1,6 +1,14 @@
 import { Schema } from "effect";
 import { Decision } from "effect/unstable/ai";
 
+/**
+ * Version of the complete TypeSafe question set.
+ *
+ * Increment this whenever question instructions, criteria, or primitives change
+ * so captured training evidence remains attributable to its exact semantics.
+ */
+export const QUESTION_SET_VERSION = 2;
+
 /**
  * The judgment set demur asks about every command.
  *
@@ -35,7 +43,7 @@ export const QUESTIONS = {
     criteria: {
       true: "It reads a value from an environment variable, file, credential or secret store, database, or remote system and prints, logs, copies, or transmits it. Read-only output still counts.",
       false:
-        "It reveals only names, metadata, schema, attributes, or redacted values; rotates or revokes without revealing; or quotes or prints secret-looking names or commands as documentation, comments, or other inert payload.",
+        "It reveals only names, metadata, schema, attributes, or redacted values; looks up or describes a credential item without requesting its secret value; rotates or revokes without revealing; or quotes or prints secret-looking names or commands as documentation, comments, or other inert payload. For example, `security find-generic-password -s NAME` without `-w` prints item attributes rather than the password value.",
     },
   }),
 

package/src/settings-model.ts

@@ -0,0 +1,60 @@
+import {
+  DEMUR_MODES,
+  FAILURE_POLICIES,
+  type DemurSettings,
+} from "../extensions/demur/settings.ts";
+
+/**
+ * Settings exposed by both the Pi extension menu and the central TUI.
+ */
+export type DemurSettingKey = "mode" | "training" | "failurePolicy";
+
+/**
+ * Move one persisted demur setting to its next or previous supported value.
+ *
+ * Selecting disabled mode always turns training capture off. Training cannot be
+ * changed while disabled, matching the persisted configuration invariant.
+ *
+ * @param settings - Current persisted settings
+ * @param key - Setting to change
+ * @param direction - Positive for the next value, negative for the previous
+ * @returns The updated settings, or the original object when no change is valid
+ */
+export function changeDemurSetting(
+  settings: DemurSettings,
+  key: DemurSettingKey,
+  direction: number,
+): DemurSettings {
+  if (key === "training") {
+    if (settings.mode === "disabled") return settings;
+    return { ...settings, training: !settings.training };
+  }
+
+  if (key === "mode") {
+    const mode = cycleValue(DEMUR_MODES, settings.mode, direction);
+    return {
+      ...settings,
+      mode,
+      training: mode === "disabled" ? false : settings.training,
+    };
+  }
+
+  return {
+    ...settings,
+    failurePolicy: cycleValue(
+      FAILURE_POLICIES,
+      settings.failurePolicy,
+      direction,
+    ),
+  };
+}
+
+function cycleValue<Value>(
+  values: ReadonlyArray<Value>,
+  current: Value,
+  direction: number,
+): Value {
+  const currentIndex = values.indexOf(current);
+  const offset = direction < 0 ? values.length - 1 : 1;
+  return values[(currentIndex + offset) % values.length] ?? current;
+}

package/src/state.ts

@@ -1,17 +1,13 @@
 import { Context, Effect, Layer, Option, Schema } from "effect";
 import { analyze, type CommandAnalysis } from "./analyze.ts";
 import { Environment } from "./key.ts";
-import type { CommandState, GitState, Host } from "./types.ts";
-
-/**
- * A JSON object accepted by the Effect decision model as System One state.
- */
-type JsonObject = { [key: string]: JsonValue };
-
-/**
- * Any JSON-compatible value.
- */
-type JsonValue = string | number | boolean | null | JsonValue[] | JsonObject;
+import type {
+  CommandState,
+  GitState,
+  Host,
+  JsonValue,
+  RenderedCommandState,
+} from "./types.ts";
 
 /**
  * Milliseconds to wait for git before giving up and judging without it.
@@ -204,8 +200,8 @@ export function gatherState(
  * @param state - Collected command state
  * @returns A plain JSON object suitable for the `state` field
  */
-export function renderState(state: CommandState): JsonObject {
-  const out: JsonObject = {
+export function renderState(state: CommandState): RenderedCommandState {
+  const out: { [key: string]: JsonValue } = {
     command: state.command,
     working_directory: state.cwd,
     requesting_agent: state.agent,
@@ -245,11 +241,13 @@ export function renderState(state: CommandState): JsonObject {
  * @param analysis - Analysis produced by {@link analyze}
  * @returns A JSON object describing what code determined
  */
-export function renderAnalysis(analysis: CommandAnalysis): JsonObject {
-  const out: JsonObject = {
+export function renderAnalysis(
+  analysis: CommandAnalysis,
+): RenderedCommandState {
+  const out: { [key: string]: JsonValue } = {
     note: "A breakdown of what this command will do when it runs. `program` is the executable that will actually be invoked, after removing quotes and stripping wrappers such as env or sudo. `paths` are resolved for ~, $TMPDIR, and .. before being located. Every command listed here executes.",
     commands: analysis.segments.map((segment) => {
-      const entry: JsonObject = {
+      const entry: { [key: string]: JsonValue } = {
         program: segment.argv0 ?? "(could not determine)",
         arguments: segment.args,
       };