@wyattjoh/demur 0.1.0

package/src/policy.ts

@@ -0,0 +1,215 @@
+import type { CommandAnalysis } from "./analyze.ts";
+import type { Decision, Judgments } from "./types.ts";
+
+/**
+ * Decision thresholds applied to raw judgments.
+ *
+ * Policy lives here, apart from the judgments themselves, so thresholds can be
+ * retuned without changing the model questions or re-running inference.
+ *
+ * Each severity signal has a single deny threshold plus a shared uncertainty
+ * band. There are deliberately no separate "ask" thresholds, which could cross
+ * their corresponding deny thresholds and silently make branches unreachable.
+ * One threshold plus a band cannot express that invalid configuration.
+ */
+export type Thresholds = {
+  /**
+   * Below this probability of actually executing something, the command is
+   * treated as inert text and allowed outright. This is the gate that rescues
+   * `grep "rm -rf"`, heredocs quoting dangerous strings, and `sed` scripts that
+   * merely mention a scary path.
+   */
+  executesDestruction: number;
+  /**
+   * Probability of unrecoverable loss at which a command is denied.
+   */
+  denyUnrecoverable: number;
+  /**
+   * Probability of touching shared or production systems at which a command is
+   * denied.
+   */
+  denySharedInfrastructure: number;
+  /**
+   * Expected blast radius at which a command is denied, on the 0–3 rubric.
+   */
+  denyBlastRadius: number;
+  /**
+   * Blast-radius confidence below which a destructive command is escalated to a
+   * prompt rather than allowed. An uncertain model on a destructive command is
+   * exactly the case a human should see.
+   */
+  minBlastRadiusConfidence: number;
+  /**
+   * Half-width of the uncertainty band around each probability threshold.
+   *
+   * Model judgments are not deterministic. Anything inside the band becomes
+   * `ask`, turning a borderline automatic decision into a question for the user.
+   */
+  uncertaintyBand: number;
+  /**
+   * The same band for the 0–3 blast-radius scale rather than a probability.
+   */
+  uncertaintyBandScore: number;
+  /**
+   * How destructive a command must look before an unresolvable target escalates
+   * it to a prompt.
+   *
+   * Without this floor the static gate also fires on `test -d "$p/.git"` and
+   * `command -v git` — read-only commands that merely contain a variable.
+   */
+  staticGateMinExecution: number;
+};
+
+/**
+ * Shipped thresholds.
+ *
+ * These are proof-of-concept defaults, not safety guarantees. Re-validate them
+ * against your own threat model and command distribution.
+ */
+export const THRESHOLDS: Thresholds = {
+  executesDestruction: 0.3,
+  denyUnrecoverable: 0.45,
+  denySharedInfrastructure: 0.5,
+  denyBlastRadius: 2.0,
+  minBlastRadiusConfidence: 0.5,
+  uncertaintyBand: 0.04,
+  uncertaintyBandScore: 0.12,
+  staticGateMinExecution: 0.8,
+};
+
+/**
+ * A decision plus the sentence explaining it.
+ */
+export type PolicyOutcome = {
+  /**
+   * The action to take.
+   */
+  decision: Decision;
+  /**
+   * Justification naming the signal that drove the decision.
+   */
+  reason: string;
+};
+
+/**
+ * Turn raw judgments into an action.
+ *
+ * Order matters. The inert-text gate runs first, so a command that executes
+ * nothing is allowed however alarming its text looks. Then each severity signal
+ * is checked clear of its band (deny), and only afterwards is anything merely
+ * near a threshold escalated to a prompt.
+ *
+ * @param j - Judgments returned for the command
+ * @param t - Threshold set to apply; defaults to the shipped values
+ * @returns The decision and the reason behind it
+ */
+export function decide(j: Judgments, t: Thresholds = THRESHOLDS): PolicyOutcome {
+  const pct = (n: number) => `${Math.round(n * 100)}%`;
+  const band = t.uncertaintyBand;
+  const scoreBand = t.uncertaintyBandScore;
+
+  if (j.executesDestruction < t.executesDestruction - band) {
+    return {
+      decision: "allow",
+      reason: `No destructive operation is actually executed (${pct(j.executesDestruction)} likelihood); any dangerous-looking text is inert.`,
+    };
+  }
+
+  if (j.targetsSharedInfrastructure >= t.denySharedInfrastructure + band) {
+    return {
+      decision: "deny",
+      reason: `Acts on shared or production infrastructure (${pct(j.targetsSharedInfrastructure)} likelihood). Run it yourself if that is intended.`,
+    };
+  }
+
+  if (j.unrecoverable >= t.denyUnrecoverable + band) {
+    return {
+      decision: "deny",
+      reason: `Destroys work that cannot be recovered (${pct(j.unrecoverable)} likelihood). Commit, stash, or back up first.`,
+    };
+  }
+
+  if (j.blastRadius >= t.denyBlastRadius + scoreBand) {
+    return {
+      decision: "deny",
+      reason: `Blast radius ${j.blastRadius.toFixed(1)}/3 — at this level the loss reaches irreplaceable or shared state.`,
+    };
+  }
+
+  // Inside a band: the signal is too close to its threshold for the decision to
+  // be reproducible, so ask rather than flip a coin on the user's behalf.
+  if (j.targetsSharedInfrastructure >= t.denySharedInfrastructure - band) {
+    return {
+      decision: "ask",
+      reason: `Borderline on whether this touches shared or production infrastructure (${pct(j.targetsSharedInfrastructure)}).`,
+    };
+  }
+
+  if (j.unrecoverable >= t.denyUnrecoverable - band) {
+    return {
+      decision: "ask",
+      reason: `Borderline on whether the loss is recoverable (${pct(j.unrecoverable)}).`,
+    };
+  }
+
+  if (j.blastRadius >= t.denyBlastRadius - scoreBand) {
+    return {
+      decision: "ask",
+      reason: `Blast radius ${j.blastRadius.toFixed(1)}/3, right at the line where the loss stops being contained.`,
+    };
+  }
+
+  if (j.blastRadiusConfidence < t.minBlastRadiusConfidence) {
+    return {
+      decision: "ask",
+      reason: `Destructive, and the blast radius is unclear (confidence ${j.blastRadiusConfidence.toFixed(2)}). Escalating rather than guessing.`,
+    };
+  }
+
+  if (j.executesDestruction < t.executesDestruction + band) {
+    return {
+      decision: "ask",
+      reason: `Borderline on whether this executes anything at all (${pct(j.executesDestruction)}).`,
+    };
+  }
+
+  return {
+    decision: "allow",
+    reason: `Destructive but contained: blast radius ${j.blastRadius.toFixed(1)}/3, ${pct(j.unrecoverable)} chance of unrecoverable loss.`,
+  };
+}
+
+/**
+ * Refuse to allow a destructive command whose real target cannot be known.
+ *
+ * Some commands do not determine their own effect. A delete rooted at `$TMPDIR`
+ * removes whatever that variable happens to name. A glob in the program position
+ * depends on what it expands to. A command substitution runs whatever it prints.
+ *
+ * A judgment answers what a command *appears* to do. Where appearance and effect
+ * can diverge, that answer is not a basis for allowing it automatically, so the
+ * decision is floored at `ask`. Denials stand; this can only tighten a verdict.
+ *
+ * @param outcome - The decision reached from the judgments alone
+ * @param analysis - Static analysis of the same command
+ * @param judgments - The raw judgments, for the destructiveness floor
+ * @param t - Threshold set to apply; defaults to the shipped values
+ * @returns The outcome, escalated to `ask` when the target is unknowable
+ */
+export function applyStaticGate(
+  outcome: PolicyOutcome,
+  analysis: CommandAnalysis | undefined,
+  judgments: Judgments,
+  t: Thresholds = THRESHOLDS,
+): PolicyOutcome {
+  if (analysis === undefined) return outcome;
+  if (outcome.decision !== "allow") return outcome;
+  if (!analysis.staticallyUnresolvable) return outcome;
+  if (judgments.executesDestruction < t.staticGateMinExecution) return outcome;
+
+  return {
+    decision: "ask",
+    reason:
+      "Destructive, and what it actually targets depends on the environment — a variable, a glob, or a command substitution — rather than on the command text. Confirm before running.",
+  };
+}

package/src/questions.ts

@@ -0,0 +1,70 @@
+import { Schema } from "effect";
+import { Decision } from "effect/unstable/ai";
+
+/**
+ * The judgment set demur asks about every command.
+ *
+ * All four are sent in a single System One call. They are independent of one
+ * another and are evaluated in parallel, so asking all four costs one round
+ * trip. Code — not the model — decides which ones matter for a given verdict.
+ *
+ * Every question is phrased so that a high value means *more* dangerous,
+ * except `executesDestruction`, where a high value means the command really is
+ * an operation rather than inert text.
+ *
+ * A fifth question asking whether the command reaches outside the working
+ * directory was removed: "outside the working directory" turned out not to be a
+ * risk signal at all. It scored ~0.97 on any absolute path, including a rename
+ * within one directory, and no threshold sweep ever found a setting where it
+ * improved a decision.
+ */
+export const QUESTIONS = {
+  executesDestruction: Decision.probability({
+    instructions:
+      "Executing this command will actually carry out an operation that changes existing state, rather than only reading, searching, printing, or querying.",
+    criteria: {
+      true: "Running it performs a real operation on something that already exists: removing, overwriting, moving, resetting, or reconfiguring files, permissions, ownership, processes, containers, or remote resources. Judge what the command does when it runs, including anything it reaches through a shell, an interpreter, a wrapper such as `env` or `sudo`, command substitution, an alias, or a glob that expands to an executable.",
+      false:
+        "It only reads, searches, prints, lists, queries, or checks. Any destructive-looking text is inert: a search pattern, an argument to a read-only command, a string being printed or sent as data to a network service, quoted content inside a heredoc body that is payload rather than script, a comment, or documentation describing a command rather than running it.",
+    },
+  }),
+
+  unrecoverable: Decision.probability({
+    instructions:
+      "Whatever this command destroys could not be recovered afterwards from the state described.",
+    criteria: {
+      true: "The affected data has no second copy. Uncommitted edits, untracked files, unpushed commits with no upstream, or remote resources with no backup.",
+      false:
+        "Everything it touches can be restored: it is committed and pushed to git, reinstallable, regenerable by re-running a build, or a cache that rebuilds on demand.",
+    },
+  }),
+
+  targetsSharedInfrastructure: Decision.probability({
+    instructions:
+      "This command acts on a shared, remote, or production system rather than on this machine's local checkout.",
+    criteria: {
+      true: "It operates on a production or shared database, a cloud account, a Kubernetes cluster, a remote host, a container registry, or a branch on a git remote.",
+      false:
+        "It operates only on local files, local containers, or the local git repository.",
+    },
+  }),
+
+  blastRadius: Decision.rate({
+    instructions:
+      "How much would be lost if this command ran and the outcome turned out to be unwanted.",
+    criteria: [
+      "Nothing of value. The command is read-only, or it touches only caches, build output, temporary files, or files it created itself.",
+      "Recoverable work inside this project: committed files, dependencies that can be reinstalled, or generated code that can be regenerated.",
+      "Irreplaceable local work: uncommitted edits, untracked files, unpushed commits, or unrelated files elsewhere on this machine.",
+      "Shared or production state: a branch other people depend on, a production database, cloud infrastructure, or a live service.",
+    ],
+  }),
+} as const;
+
+/**
+ * Batched System One definition for all command judgments.
+ */
+export const COMMAND_JUDGMENTS = Decision.make({
+  input: Schema.Json,
+  decisions: QUESTIONS,
+});

package/src/state.ts

@@ -0,0 +1,287 @@
+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;
+
+/**
+ * Milliseconds to wait for git before giving up and judging without it.
+ *
+ * Git state is an enrichment, not a requirement: a slow or broken repository
+ * must never delay the guard past its own budget.
+ */
+const GIT_TIMEOUT_MS = 400;
+
+class GitCommandError extends Schema.TaggedError<GitCommandError>()("GitCommandError", {
+  cause: Schema.Defect(),
+}) {}
+
+/**
+ * Effect service for the bounded git queries used to enrich command state.
+ */
+export class GitCommand extends Context.Service<
+  GitCommand,
+  {
+    run(cwd: string, args: ReadonlyArray<string>): Effect.Effect<string | undefined>;
+  }
+>()("demur/state/GitCommand") {
+  static readonly layer = Layer.succeed(
+    GitCommand,
+    GitCommand.of({
+      run: Effect.fn("GitCommand.run")(function* (
+        cwd: string,
+        args: ReadonlyArray<string>,
+      ) {
+        return yield* Effect.tryPromise({
+          try: async (signal) => {
+            const proc = Bun.spawn(["git", ...args], {
+              cwd,
+              stdout: "pipe",
+              stderr: "ignore",
+              stdin: "ignore",
+            });
+            const abort = () => proc.kill();
+            signal.addEventListener("abort", abort, { once: true });
+
+            try {
+              const [stdout, exitCode] = await Promise.all([
+                new Response(proc.stdout).text(),
+                proc.exited,
+              ]);
+              return exitCode === 0 ? stdout.trim() : undefined;
+            } finally {
+              signal.removeEventListener("abort", abort);
+            }
+          },
+          catch: (cause) => new GitCommandError({ cause }),
+        }).pipe(
+          Effect.timeoutOption(GIT_TIMEOUT_MS),
+          Effect.map(Option.getOrUndefined),
+          Effect.catch(() => Effect.succeed(undefined)),
+        );
+      }),
+    }),
+  );
+}
+
+/**
+ * Collect the git facts that change whether a command is really destructive.
+ *
+ * Uses a single porcelain v2 status with branch headers, so this is one process
+ * spawn rather than one per fact.
+ *
+ * @param cwd - Directory the command will run in
+ * @returns Git state, or `undefined` when `cwd` is not inside a work tree
+ */
+export const gatherGitStateEffect = Effect.fn("gatherGitStateEffect")(function* (
+  cwd: string,
+): Effect.fn.Return<GitState | undefined, never, GitCommand> {
+  const git = yield* GitCommand;
+  const status = yield* git.run(cwd, [
+    "status",
+    "--porcelain=v2",
+    "--branch",
+    "--untracked-files=normal",
+  ]);
+  if (status === undefined) return undefined;
+
+  const root = yield* git.run(cwd, ["rev-parse", "--show-toplevel"]);
+  if (root === undefined) return undefined;
+
+  let branch: string | undefined;
+  let hasUpstream = false;
+  let unpushedCommitCount = 0;
+  let uncommittedFileCount = 0;
+  let untrackedFileCount = 0;
+
+  for (const line of status.split("\n")) {
+    if (line.startsWith("# branch.head ")) {
+      const head = line.slice("# branch.head ".length);
+      branch = head === "(detached)" ? undefined : head;
+    } else if (line.startsWith("# branch.upstream ")) {
+      hasUpstream = true;
+    } else if (line.startsWith("# branch.ab ")) {
+      // Format: "# branch.ab +<ahead> -<behind>"
+      const ahead = line.slice("# branch.ab ".length).split(" ")[0];
+      unpushedCommitCount = Math.max(0, Number(ahead ?? 0) || 0);
+    } else if (line.startsWith("? ")) {
+      untrackedFileCount += 1;
+    } else if (line.startsWith("1 ") || line.startsWith("2 ") || line.startsWith("u ")) {
+      uncommittedFileCount += 1;
+    }
+  }
+
+  return {
+    root,
+    branch,
+    uncommittedFileCount,
+    untrackedFileCount,
+    unpushedCommitCount,
+    hasUpstream,
+  };
+});
+
+/**
+ * Collect the git facts through the live Effect service.
+ *
+ * @param cwd - Directory the command will run in
+ * @returns Git state, or `undefined` when `cwd` is not inside a work tree
+ */
+export function gatherGitState(cwd: string): Promise<GitState | undefined> {
+  return Effect.runPromise(
+    gatherGitStateEffect(cwd).pipe(Effect.provide(GitCommand.layer)),
+  );
+}
+
+/**
+ * Build the full state handed to the model for one command.
+ *
+ * @param command - The shell command about to run
+ * @param cwd - Absolute working directory for the command
+ * @param agent - Which coding agent is asking
+ * @returns State ready to send as a System One request
+ */
+export const gatherStateEffect = Effect.fn("gatherStateEffect")(function* (
+  command: string,
+  cwd: string,
+  agent: Host,
+): Effect.fn.Return<CommandState, never, Environment | GitCommand> {
+  const environment = yield* Environment;
+  const [git, home, tmpDir] = yield* Effect.all([
+    gatherGitStateEffect(cwd),
+    environment.get("HOME"),
+    environment.get("TMPDIR"),
+  ]);
+
+  return {
+    command,
+    cwd,
+    agent,
+    git,
+    nonce: undefined,
+    // Computed for the static gate in policy.ts, NOT sent to the model.
+    // renderState below explains why it is withheld from the request.
+    analysis: analyze(command, cwd, home ?? "/root", tmpDir?.replace(/\/$/, "")),
+  };
+});
+
+/**
+ * Build state through the live Effect services.
+ *
+ * @param command - The shell command about to run
+ * @param cwd - Absolute working directory for the command
+ * @param agent - Which coding agent is asking
+ * @returns State ready to send as a System One request
+ */
+export function gatherState(
+  command: string,
+  cwd: string,
+  agent: Host,
+): Promise<CommandState> {
+  return Effect.runPromise(
+    gatherStateEffect(command, cwd, agent).pipe(
+      Effect.provide(Layer.merge(Environment.layer, GitCommand.layer)),
+    ),
+  );
+}
+
+/**
+ * Render state as the JSON object sent to the model.
+ *
+ * Field names are part of the prompt, so they are spelled out rather than
+ * abbreviated, and git facts are flattened with a short explanation of what an
+ * absent repository means.
+ *
+ * @param state - Collected command state
+ * @returns A plain JSON object suitable for the `state` field
+ */
+export function renderState(state: CommandState): JsonObject {
+  const out: JsonObject = {
+    command: state.command,
+    working_directory: state.cwd,
+    requesting_agent: state.agent,
+  };
+
+  if (state.nonce !== undefined) out.request_nonce = state.nonce;
+
+  out.version_control =
+    state.git === undefined
+      ? "Not inside a git repository."
+      : {
+          repository_root: state.git.root,
+          current_branch: state.git.branch ?? "(detached HEAD)",
+          uncommitted_modified_files: state.git.uncommittedFileCount,
+          untracked_files: state.git.untrackedFileCount,
+          unpushed_commits: state.git.unpushedCommitCount,
+          branch_has_remote_upstream: state.git.hasUpstream,
+        };
+
+  // The static analysis in `analyze.ts` is deliberately NOT sent. It exists for
+  // the deterministic policy gate; the model judges the original command rather
+  // than a lossy summary of it.
+
+  return out;
+}
+
+/**
+ * Render the static analysis as state the model can read directly.
+ *
+ * Retained for deterministic policy and future hybrid guards. It is not part of
+ * the model request; see {@link renderState}.
+ *
+ * The wording of each key is part of the prompt. `program` in particular is
+ * spelled out as the real executable, because its whole purpose is to stop the
+ * model from reading `rm` out of the middle of `transform`.
+ *
+ * @param analysis - Analysis produced by {@link analyze}
+ * @returns A JSON object describing what code determined
+ */
+export function renderAnalysis(analysis: CommandAnalysis): JsonObject {
+  const out: JsonObject = {
+    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 = {
+        program: segment.argv0 ?? "(could not determine)",
+        arguments: segment.args,
+      };
+      if (segment.wrappers.length > 0) entry.invoked_through = segment.wrappers;
+      if (segment.paths.length > 0) {
+        entry.paths = segment.paths.map((p) => ({
+          as_written: p.value,
+          resolves_to: p.resolved ?? "(contains an unresolved variable)",
+          location: p.class,
+        }));
+      }
+      return entry;
+    }),
+  };
+
+  if (analysis.substitutions.length > 0) {
+    out.commands_inside_substitutions = analysis.substitutions;
+  }
+
+  if (analysis.heredocs.length > 0) {
+    out.heredoc_bodies = analysis.heredocs.map((h) => ({
+      delimiter: h.tag,
+      fed_to: h.consumer ?? "(unknown)",
+      shell_expansion_suppressed: h.quoted,
+      body: h.body.length > 500 ? `${h.body.slice(0, 500)}…` : h.body,
+    }));
+  }
+
+  if (!analysis.parsedCleanly) {
+    out.parse_warning =
+      "Part of this command could not be parsed cleanly; treat the breakdown above as incomplete.";
+  }
+
+  return out;
+}