@wyattjoh/demur 0.1.0

package/src/guard.internal.ts

@@ -0,0 +1,164 @@
+import {
+  Cause,
+  Clock,
+  Effect,
+  Exit,
+  Predicate,
+  Result,
+} from "effect";
+import { judgeEffect, Judgment } 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";
+
+const PREFIX = "demur:";
+
+/**
+ * Effect-native guard implementation used by the Promise boundary.
+ *
+ * @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
+ */
+export const guardEffect = Effect.fn("guardEffect")(function* (
+  command: string,
+  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);
+});
+
+/**
+ * Effect-native judgment for state that has already been collected.
+ *
+ * @param state - Pre-collected command state
+ * @param latencyOffsetMs - Time already spent before entering this Effect
+ * @returns A fail-closed verdict
+ */
+export const judgeStateEffect = Effect.fn("judgeStateEffect")(function* (
+  state: CommandState,
+  latencyOffsetMs = 0,
+): Effect.fn.Return<Verdict, never, Judgment> {
+  const started = yield* Clock.monotonicTimeNanos;
+  const exit = yield* Effect.exit(
+    judgeStateCore(state, started, latencyOffsetMs),
+  );
+  if (Exit.isSuccess(exit)) return exit.value;
+
+  return yield* unexpectedVerdict(started, exit.cause, latencyOffsetMs);
+});
+
+const judgeStateCore = Effect.fn("judgeStateCore")(function* (
+  state: CommandState,
+  started: bigint,
+  latencyOffsetMs: number,
+): Effect.fn.Return<Verdict, never, Judgment> {
+  const result = yield* Effect.result(judgeEffect(state));
+
+  if (Result.isFailure(result)) {
+    return yield* completeVerdict(
+      started,
+      {
+        ...emptyEvidence,
+        decision: "deny",
+        reason: `${PREFIX} guard unavailable (${result.failure.failure}) — ${result.failure.detail} Blocking because demur fails closed. Set DEMUR_DISABLE=1 to bypass.`,
+        failure: result.failure.failure,
+      },
+      latencyOffsetMs,
+    );
+  }
+
+  const success = result.success;
+  const outcome = applyStaticGate(
+    decide(success.judgments),
+    state.analysis,
+    success.judgments,
+  );
+
+  return yield* completeVerdict(
+    started,
+    {
+      decision: outcome.decision,
+      reason: `${PREFIX} ${outcome.reason}`,
+      judgments: success.judgments,
+      failure: undefined,
+      usage: success.usage,
+    },
+    latencyOffsetMs,
+  );
+});
+
+const emptyEvidence = {
+  judgments: undefined,
+  failure: undefined,
+  usage: undefined,
+} as const;
+
+type VerdictWithoutLatency = Omit<Verdict, "latencyMs">;
+
+function completeVerdict(
+  started: bigint,
+  verdict: VerdictWithoutLatency,
+  latencyOffsetMs = 0,
+): Effect.Effect<Verdict> {
+  return Effect.map(Clock.monotonicTimeNanos, (finished) => ({
+    ...verdict,
+    latencyMs:
+      latencyOffsetMs + Number((finished - started) / BigInt(1_000_000)),
+  }));
+}
+
+function unexpectedVerdict(
+  started: bigint,
+  cause: Cause.Cause<unknown>,
+  latencyOffsetMs: number,
+): Effect.Effect<Verdict> {
+  const error = Cause.squash(cause);
+  const detail = Predicate.isError(error) ? error.message : String(error);
+
+  return completeVerdict(
+    started,
+    {
+      ...emptyEvidence,
+      decision: "deny",
+      reason: `${PREFIX} guard crashed — ${detail} Blocking because demur fails closed. Set DEMUR_DISABLE=1 to bypass.`,
+      failure: "unexpected",
+    },
+    latencyOffsetMs,
+  );
+}
+
+function isDisabled(flag: string | undefined): boolean {
+  const normalized = flag?.trim();
+  return normalized === "1" || normalized === "true";
+}

package/src/guard.ts

@@ -0,0 +1,84 @@
+import { Layer, ManagedRuntime, Predicate } from "effect";
+import { guardEffect, 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";
+
+const PREFIX = "demur:";
+
+const runtime = ManagedRuntime.make(
+  Layer.mergeAll(Environment.layer, GitCommand.layer, Judgment.layer),
+);
+
+/**
+ * Judge one command and decide what the host should do with it.
+ *
+ * Fails closed: any path that does not produce a judgment returns `deny`, with
+ * a reason that names the failure so an outage is never mistaken for a policy
+ * decision. This Promise is the compatibility boundary around the Effect
+ * implementation.
+ *
+ * @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, including the judgments behind it
+ */
+export function guard(
+  command: string,
+  cwd: string,
+  agent: Host,
+  signal: AbortSignal | undefined = undefined,
+): Promise<Verdict> {
+  const started = performance.now();
+
+  return runtime
+    .runPromise(
+      guardEffect(command, cwd, agent),
+      signal === undefined ? undefined : { signal },
+    )
+    .catch((error: unknown) => unexpectedVerdict(error, started));
+}
+
+/**
+ * Judge a command from state that has already been collected.
+ *
+ * Separate from {@link guard} so the eval harness can hold context fixed across
+ * a corpus run instead of picking up whatever repository it happens to run in.
+ *
+ * @param state - Pre-collected command state
+ * @param signal - Optional cancellation signal from the host
+ * @param startedAt - `performance.now()` reading to measure latency from
+ * @returns The verdict, including the judgments behind it
+ */
+export function judgeState(
+  state: CommandState,
+  signal: AbortSignal | undefined = undefined,
+  startedAt: number | undefined = undefined,
+): Promise<Verdict> {
+  const enteredAt = performance.now();
+  const latencyOffsetMs =
+    startedAt === undefined ? 0 : Math.max(0, Math.round(enteredAt - startedAt));
+
+  return runtime
+    .runPromise(
+      judgeStateEffect(state, latencyOffsetMs),
+      signal === undefined ? undefined : { signal },
+    )
+    .catch((error: unknown) =>
+      unexpectedVerdict(error, startedAt ?? enteredAt),
+    );
+}
+
+function unexpectedVerdict(error: unknown, startedAt: number): Verdict {
+  const detail = Predicate.isError(error) ? error.message : String(error);
+  return {
+    decision: "deny",
+    reason: `${PREFIX} guard crashed — ${detail} Blocking because demur fails closed. Set DEMUR_DISABLE=1 to bypass.`,
+    judgments: undefined,
+    failure: "unexpected",
+    usage: undefined,
+    latencyMs: Math.round(performance.now() - startedAt),
+  };
+}

package/src/judge.ts

@@ -0,0 +1,233 @@
+import { TypeSafeClient, TypeSafeDecisionModel } from "@effect/ai-typesafe";
+import {
+  Cause,
+  Context,
+  Effect,
+  Layer,
+  ManagedRuntime,
+  Predicate,
+  Redacted,
+  Result,
+  Schema,
+} from "effect";
+import { AiError, DecisionModel } from "effect/unstable/ai";
+import { FetchHttpClient } from "effect/unstable/http";
+import { Environment, MISSING_KEY_HELP } from "./key.ts";
+import { COMMAND_JUDGMENTS } from "./questions.ts";
+import { renderState } from "./state.ts";
+import type { CommandState, FailureKind, Judgments } from "./types.ts";
+
+/**
+ * Default per-attempt timeout for the judgment call.
+ *
+ * Override with `DEMUR_TIMEOUT_MS`. This sits in front of every Bash call the
+ * agent makes, so it is a latency budget, not a generosity setting.
+ */
+const DEFAULT_TIMEOUT_MS = 4000;
+
+const TYPESAFE_MODEL = "jev-latest";
+
+/**
+ * Build the TypeSafe-backed Effect decision model for one API key.
+ *
+ * @param apiKey - TypeSafe API key to redact and attach to requests
+ * @returns A complete decision-model layer with its HTTP dependency provided
+ */
+export function makeDecisionModelLayer(apiKey: string) {
+  return TypeSafeDecisionModel.layer({ model: TYPESAFE_MODEL }).pipe(
+    Layer.provide(TypeSafeClient.layer({ apiKey: Redacted.make(apiKey) })),
+    Layer.provide(FetchHttpClient.layer),
+  );
+}
+
+/**
+ * A completed judgment, with the token cost of producing it.
+ */
+export type JudgeSuccess = {
+  ok: true;
+  judgments: Judgments;
+  usage: { inputTokens: number; outputTokens: number };
+};
+
+/**
+ * A judgment that could not be produced, and why.
+ */
+export type JudgeFailure = {
+  ok: false;
+  failure: FailureKind;
+  detail: string;
+};
+
+/**
+ * The outcome of asking the model about a command.
+ */
+export type JudgeResult = JudgeSuccess | JudgeFailure;
+
+/**
+ * Typed failure raised while obtaining a System One judgment.
+ */
+export class JudgmentError extends Schema.TaggedError<JudgmentError>()(
+  "JudgmentError",
+  {
+    failure: Schema.Literals([
+      "no-api-key",
+      "timeout",
+      "api-error",
+      "unexpected",
+    ]),
+    detail: Schema.String,
+  },
+) {}
+
+/**
+ * Effect service that obtains raw judgments for command state.
+ */
+export class Judgment extends Context.Service<
+  Judgment,
+  {
+    judge(state: CommandState): Effect.Effect<JudgeSuccess, JudgmentError>;
+  }
+>()("demur/judge/Judgment") {
+  static readonly layerNoDeps = Layer.effect(
+    Judgment,
+    Effect.gen(function* () {
+      const environment = yield* Environment;
+      let decisionLayer: ReturnType<typeof makeDecisionModelLayer> | undefined;
+      let timeoutMs = DEFAULT_TIMEOUT_MS;
+
+      const getDecisionLayer = Effect.fn("Judgment.getDecisionLayer")(
+        function* (): Effect.fn.Return<
+          ReturnType<typeof makeDecisionModelLayer>,
+          JudgmentError
+        > {
+          if (decisionLayer !== undefined) return decisionLayer;
+
+          const apiKey =
+            (yield* environment.get("TYPESAFE_API_KEY"))?.trim() || undefined;
+          if (apiKey === undefined) {
+            return yield* new JudgmentError({
+              failure: "no-api-key",
+              detail: MISSING_KEY_HELP,
+            });
+          }
+
+          const configuredTimeout = Number(
+            yield* environment.get("DEMUR_TIMEOUT_MS"),
+          );
+          timeoutMs = configuredTimeout || DEFAULT_TIMEOUT_MS;
+          decisionLayer = makeDecisionModelLayer(apiKey);
+          return decisionLayer;
+        },
+      );
+
+      const judge = Effect.fn("Judgment.judge")(function* (
+        state: CommandState,
+      ): Effect.fn.Return<JudgeSuccess, JudgmentError> {
+        const activeDecisionLayer = yield* getDecisionLayer();
+        const result = yield* DecisionModel.decide(COMMAND_JUDGMENTS, {
+          input: renderState(state),
+        }).pipe(
+          Effect.provide(activeDecisionLayer),
+          Effect.timeout(timeoutMs),
+          // One retry only. A guard that retries three times with backoff is a
+          // guard that hangs the agent for ten seconds on a bad network.
+          Effect.retry({ times: 1, while: isRetryableDecisionError }),
+          Effect.mapError(toJudgmentError),
+        );
+        const answers = result.answers;
+
+        return {
+          ok: true,
+          judgments: {
+            executesDestruction: answers.executesDestruction.probability,
+            unrecoverable: answers.unrecoverable.probability,
+            targetsSharedInfrastructure:
+              answers.targetsSharedInfrastructure.probability,
+            blastRadius: answers.blastRadius.rating,
+            blastRadiusConfidence: answers.blastRadius.confidence ?? 0,
+          },
+          usage: {
+            inputTokens: result.usage.inputTokens ?? 0,
+            outputTokens: result.usage.outputTokens ?? 0,
+          },
+        };
+      });
+
+      return Judgment.of({ judge });
+    }),
+  );
+
+  static readonly layer = this.layerNoDeps.pipe(
+    Layer.provide(Environment.layer),
+  );
+}
+
+/**
+ * Ask the configured judgment service about one command.
+ *
+ * @param state - The command and its surrounding context
+ * @returns The judgments, or a typed failure in the Effect error channel
+ */
+export const judgeEffect = Effect.fn("judgeEffect")(function* (
+  state: CommandState,
+): Effect.fn.Return<JudgeSuccess, JudgmentError, Judgment> {
+  const judgment = yield* Judgment;
+  return yield* judgment.judge(state);
+});
+
+const runtime = ManagedRuntime.make(Judgment.layer);
+
+/**
+ * Ask System One every question about one command, in a single call.
+ *
+ * This Promise API is retained for existing callers; the implementation runs
+ * the Effect-native judgment service through a managed runtime.
+ *
+ * @param state - The command and its surrounding context
+ * @param signal - Optional cancellation signal from the host
+ * @returns The judgments, or a typed failure for the caller to act on
+ */
+export function judge(
+  state: CommandState,
+  signal: AbortSignal | undefined = undefined,
+): Promise<JudgeResult> {
+  const program = Effect.gen(function* () {
+    const result = yield* Effect.result(judgeEffect(state));
+    if (Result.isFailure(result)) {
+      return {
+        ok: false,
+        failure: result.failure.failure,
+        detail: result.failure.detail,
+      } satisfies JudgeFailure;
+    }
+    return result.success;
+  });
+
+  return runtime
+    .runPromise(program, signal === undefined ? undefined : { signal })
+    .catch((error: unknown) => ({
+      ok: false,
+      failure: "unexpected",
+      detail: errorDetail(error),
+    }));
+}
+
+function isRetryableDecisionError(
+  error: AiError.AiError | Cause.TimeoutError,
+): boolean {
+  return Cause.isTimeoutError(error) || error.isRetryable;
+}
+
+function toJudgmentError(error: unknown): JudgmentError {
+  const failure: FailureKind = Cause.isTimeoutError(error)
+    ? "timeout"
+    : AiError.isAiError(error)
+      ? "api-error"
+      : "unexpected";
+
+  return new JudgmentError({ failure, detail: errorDetail(error) });
+}
+
+function errorDetail(error: unknown): string {
+  return Predicate.isError(error) ? error.message : String(error);
+}

package/src/key.ts

@@ -0,0 +1,45 @@
+import { Context, Effect, Layer } from "effect";
+
+/**
+ * Effect service for reading process environment variables.
+ *
+ * Keeping environment access behind a service lets guard tests supply a
+ * complete, deterministic process context without mutating global state.
+ */
+export class Environment extends Context.Service<
+  Environment,
+  {
+    get(name: string): Effect.Effect<string | undefined>;
+  }
+>()("demur/key/Environment") {
+  static readonly layer = Layer.succeed(
+    Environment,
+    Environment.of({
+      get: Effect.fn("Environment.get")(function* (name: string) {
+        return Bun.env[name];
+      }),
+    }),
+  );
+}
+
+/**
+ * Resolve the TypeSafe API key from the environment.
+ *
+ * demur does not fetch or persist credentials. Export `TYPESAFE_API_KEY` before
+ * launching the host agent, or inject it with a secret manager so every hook
+ * invocation inherits the already-resolved value.
+ *
+ * @returns The API key, or `undefined` when the environment does not carry one
+ */
+export function resolveApiKey(): string | undefined {
+  return Bun.env.TYPESAFE_API_KEY?.trim() || undefined;
+}
+
+/**
+ * What to tell the user when the key is missing.
+ *
+ * demur fails closed, so a missing key blocks every command. The message has to
+ * name the fix, or the failure reads like a policy decision.
+ */
+export const MISSING_KEY_HELP =
+  "No TYPESAFE_API_KEY in the environment. Export it, or inject it with a secret manager, before launching the agent.";