pi-advisor-flow 0.6.0 → 0.8.0

package/src/jev/key-store.ts

@@ -0,0 +1,267 @@
+import {
+  chmodSync,
+  existsSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+import { readExistingConfig, resetConfigCache } from "../config/storage.ts";
+import { isString } from "../content-utils.ts";
+import type { RecordValue } from "../content-utils.ts";
+import { redactSecrets } from "../redaction.ts";
+
+export type JevKeySource = "bun-secrets" | "env" | "file" | "advisor-json";
+
+export interface JevKeyResolution {
+  key?: string;
+  /** Present whenever a key resolved. */
+  source?: JevKeySource;
+}
+
+export interface JevKeyStoreResult {
+  message: string;
+  ok: boolean;
+}
+
+export interface JevSecretEntry {
+  name: string;
+  service: string;
+}
+
+export interface JevSecretsLike {
+  delete: (options: JevSecretEntry) => Promise<boolean | undefined>;
+  get: (options: JevSecretEntry) => Promise<string | null | undefined>;
+  set: (options: JevSecretEntry & { value: string }) => Promise<void>;
+}
+
+export interface JevKeyStoreDeps {
+  /** Deletes the extension-managed key file; injectable for tests. */
+  deleteFileStore?: () => void;
+  env?: NodeJS.ProcessEnv;
+  readAdvisorJson?: () => RecordValue;
+  /** Reads the extension-managed 0600 key file; injectable for tests. */
+  readFileStore?: () => string | undefined;
+  /** Inject `null` to simulate a runtime without a secret store. */
+  secrets?: JevSecretsLike | null;
+  writeFileStore?: (key: string) => void;
+}
+
+export const TYPESAFE_KEY_ENV_VAR = "TYPESAFE_API_KEY";
+export const TYPESAFE_KEY_SERVICE = "pi-advisor";
+export const TYPESAFE_KEY_NAME = "typesafe-api-key";
+export const TYPESAFE_KEY_CONFIG_FIELD = "typesafe_api_key";
+
+const KEY_FILE_MODE = 0o600;
+
+const keyFilePath = () => join(getAgentDir(), "typesafe_api_key");
+
+interface BunGlobal {
+  Bun?: { secrets?: JevSecretsLike };
+}
+
+const runtimeSecrets = (): JevSecretsLike | undefined => {
+  // SAFETY: only Bun runtimes expose Bun.secrets on globalThis; others leave it undefined.
+  const bun = globalThis as BunGlobal;
+  return bun.Bun?.secrets;
+};
+
+/** Whether the current runtime offers a Bun.secrets store. */
+export const hasRuntimeSecretStore = () => runtimeSecrets() !== undefined;
+
+const normalizeKey = (value: string | null | undefined): string | undefined =>
+  value?.trim() || undefined;
+
+const readAdvisorJsonConfig = (): RecordValue =>
+  readExistingConfig(join(getAgentDir(), "advisor.json"));
+
+const defaultReadFileStore = (): string | undefined => {
+  try {
+    return normalizeKey(readFileSync(keyFilePath(), "utf-8"));
+  } catch {
+    return undefined;
+  }
+};
+
+const defaultWriteFileStore = (key: string) => {
+  const path = keyFilePath();
+  writeFileSync(path, `${key}\n`, { mode: KEY_FILE_MODE });
+  // writeFileSync's mode only applies at creation; re-assert it on every write.
+  chmodSync(path, KEY_FILE_MODE);
+};
+
+const defaultDeleteFileStore = () => {
+  rmSync(keyFilePath(), { force: true });
+};
+
+const messageOf = <E>(error: E) =>
+  redactSecrets(error instanceof Error ? error.message : String(error));
+
+/** Resolves the TypeSafe API key: Bun.secrets → env var → the extension's
+ * 0600 key file → a hand-placed advisor.json string (read-only). Never
+ * throws; no key means undefined. */
+export const resolveTypeSafeKey = async (
+  deps: JevKeyStoreDeps = {}
+): Promise<JevKeyResolution> => {
+  const secrets = deps.secrets === undefined ? runtimeSecrets() : deps.secrets;
+  if (secrets) {
+    try {
+      const stored = normalizeKey(
+        await secrets.get({
+          name: TYPESAFE_KEY_NAME,
+          service: TYPESAFE_KEY_SERVICE,
+        })
+      );
+      if (stored) {
+        return { key: stored, source: "bun-secrets" };
+      }
+    } catch {
+      // An unavailable secret store falls through to the next source.
+    }
+  }
+  const env = deps.env ?? process.env;
+  const fromEnv = normalizeKey(env[TYPESAFE_KEY_ENV_VAR]);
+  if (fromEnv) {
+    return { key: fromEnv, source: "env" };
+  }
+  const readFileStore = deps.readFileStore ?? defaultReadFileStore;
+  const fromFile = normalizeKey(readFileStore());
+  if (fromFile) {
+    return { key: fromFile, source: "file" };
+  }
+  const config = (deps.readAdvisorJson ?? readAdvisorJsonConfig)();
+  const staged = config[TYPESAFE_KEY_CONFIG_FIELD];
+  if (isString(staged)) {
+    const fromConfig = normalizeKey(staged);
+    if (fromConfig) {
+      return { key: fromConfig, source: "advisor-json" };
+    }
+  }
+  return {};
+};
+
+/** Stores the key securely: Bun.secrets when the runtime provides it,
+ * otherwise a dedicated 0600-mode file in the Pi agent directory. The key is
+ * never written to advisor.json. */
+export const writeKeyTypeSafeKey = async (
+  key: string,
+  deps: JevKeyStoreDeps = {}
+): Promise<JevKeyStoreResult> => {
+  const normalized = normalizeKey(key);
+  if (!normalized) {
+    return { message: "The key is empty.", ok: false };
+  }
+  const secrets = deps.secrets === undefined ? runtimeSecrets() : deps.secrets;
+  if (secrets) {
+    try {
+      await secrets.set({
+        name: TYPESAFE_KEY_NAME,
+        service: TYPESAFE_KEY_SERVICE,
+        value: normalized,
+      });
+      return { message: "Key stored in Bun.secrets.", ok: true };
+    } catch (error) {
+      return {
+        message: `Storing the key in Bun.secrets failed: ${messageOf(error)}. Alternatively set the ${TYPESAFE_KEY_ENV_VAR} environment variable in your shell profile.`,
+        ok: false,
+      };
+    }
+  }
+  try {
+    (deps.writeFileStore ?? defaultWriteFileStore)(normalized);
+    return {
+      message: "Key stored in ~/.pi/agent/typesafe_api_key (mode 0600).",
+      ok: true,
+    };
+  } catch (error) {
+    return {
+      message: `Storing the key failed: ${messageOf(error)}. Alternatively set the ${TYPESAFE_KEY_ENV_VAR} environment variable in your shell profile.`,
+      ok: false,
+    };
+  }
+};
+
+/** Removes every stored key (Bun.secrets entry and the 0600 file); never
+ * touches env vars or the hand-placed advisor.json entry. */
+export const clearKeyTypeSafeKey = async (
+  deps: JevKeyStoreDeps = {}
+): Promise<JevKeyStoreResult> => {
+  let clearedSomething = false;
+  let firstError: string | undefined;
+  const secrets = deps.secrets === undefined ? runtimeSecrets() : deps.secrets;
+  if (secrets) {
+    try {
+      await secrets.delete({
+        name: TYPESAFE_KEY_NAME,
+        service: TYPESAFE_KEY_SERVICE,
+      });
+      clearedSomething = true;
+    } catch (error) {
+      firstError = messageOf(error);
+    }
+  }
+  try {
+    if (deps.deleteFileStore) {
+      deps.deleteFileStore();
+    } else if (existsSync(keyFilePath())) {
+      defaultDeleteFileStore();
+    }
+    clearedSomething = true;
+  } catch (error) {
+    firstError ??= messageOf(error);
+  }
+  if (firstError) {
+    return {
+      message: `Clearing the stored key failed: ${firstError}.`,
+      ok: false,
+    };
+  }
+  return {
+    message: `Stored key cleared.${clearedSomething ? "" : ` Nothing was stored; unset ${TYPESAFE_KEY_ENV_VAR} and remove ${TYPESAFE_KEY_CONFIG_FIELD} from advisor.json yourself if you use them.`}`,
+    ok: true,
+  };
+};
+
+/** Removes a hand-placed advisor.json key after a successful store migration.
+ * Unknown keys and all config settings are preserved verbatim. */
+export const removeTypeSafeKeyFromAdvisorJson = (): JevKeyStoreResult => {
+  try {
+    const path = join(getAgentDir(), "advisor.json");
+    const existing = readExistingConfig(path);
+    if (!(TYPESAFE_KEY_CONFIG_FIELD in existing)) {
+      return { message: "No plaintext key in advisor.json.", ok: true };
+    }
+    const retained = Object.fromEntries(
+      Object.entries(existing).filter(
+        ([key]) => key !== TYPESAFE_KEY_CONFIG_FIELD
+      )
+    );
+    writeFileSync(path, `${JSON.stringify(retained, null, 2)}\n`);
+    resetConfigCache();
+    return { message: "Plaintext key removed from advisor.json.", ok: true };
+  } catch (error) {
+    return {
+      message: `Removing the plaintext key failed: ${messageOf(error)}.`,
+      ok: false,
+    };
+  }
+};
+
+let warnedPlaintextKey = false;
+
+/** Returns the plaintext-key warning once so callers can notify without spam. */
+export const consumePlaintextKeyWarning = (): string | undefined => {
+  if (warnedPlaintextKey) {
+    return undefined;
+  }
+  warnedPlaintextKey = true;
+  return `Advisor is using a plaintext ${TYPESAFE_KEY_CONFIG_FIELD} from advisor.json; this is not recommended. Open /advisor-settings → Jev consultation filter to migrate it into a secure store, or use the ${TYPESAFE_KEY_ENV_VAR} environment variable.`;
+};
+
+/** Test-only: re-arms the one-time plaintext warning. */
+export const resetPlaintextKeyWarning = () => {
+  warnedPlaintextKey = false;
+};

package/src/jev/ledger.ts

@@ -0,0 +1,228 @@
+import { formatTokenCount } from "../usage.ts";
+
+export interface AdvisorJevUsageTotals {
+  cost: number;
+  inputTokens: number;
+  outputTokens: number;
+}
+
+export interface AdvisorJevFilterLedger {
+  allowed: number;
+  failures: number;
+  overrides: number;
+  repeatSkipped: number;
+  screened: number;
+  skipped: number;
+}
+
+export interface AdvisorJevGateLedger {
+  checks: number;
+  consultations: number;
+  failures: number;
+  usage: AdvisorJevUsageTotals;
+}
+
+export interface AdvisorJevLedger {
+  filter: AdvisorJevFilterLedger;
+  gate: AdvisorJevGateLedger;
+  usage: AdvisorJevUsageTotals;
+}
+
+export interface AdvisorJevUsage {
+  cost: number;
+  inputTokens: number;
+  outputTokens: number;
+}
+
+export interface JevSkipRecord {
+  normalizedQuestion?: string;
+  turn: number;
+}
+
+/** Invocation fields the Jev summary reads; satisfied by AdvisorInvocationRecord. */
+export interface JevInvocationView {
+  cost?: number;
+  kind: string;
+  trigger: string;
+}
+
+const freshJevUsage = (): AdvisorJevUsageTotals => ({
+  cost: 0,
+  inputTokens: 0,
+  outputTokens: 0,
+});
+
+const freshJevLedger = (): AdvisorJevLedger => ({
+  filter: {
+    allowed: 0,
+    failures: 0,
+    overrides: 0,
+    repeatSkipped: 0,
+    screened: 0,
+    skipped: 0,
+  },
+  gate: { checks: 0, consultations: 0, failures: 0, usage: freshJevUsage() },
+  usage: freshJevUsage(),
+});
+
+const addJevUsage = (totals: AdvisorJevUsageTotals, usage: AdvisorJevUsage) => {
+  totals.cost += usage.cost;
+  totals.inputTokens += usage.inputTokens;
+  totals.outputTokens += usage.outputTokens;
+};
+
+const savingsLine = (costs: number[], skipped: number) => {
+  if (costs.length === 0) {
+    return "Estimated saving from skips: unavailable — no observed consultation cost this session";
+  }
+  const mean = costs.reduce((sum, cost) => sum + cost, 0) / costs.length;
+  return `Estimated saving from skips: ≤ $${(mean * skipped).toFixed(4)} — upper bound; assumes each skipped consultation would have cost this session's mean allowed-consultation cost ($${mean.toFixed(4)}), which the skipped calls would likely have undercut`;
+};
+
+const formatJevTokens = (usage: AdvisorJevUsageTotals) =>
+  `↑${formatTokenCount(usage.inputTokens + usage.outputTokens)}`;
+
+const markdownCosts = (invocations: readonly JevInvocationView[]): number[] =>
+  invocations
+    .filter(
+      (item): item is JevInvocationView & { cost: number } =>
+        item.kind === "markdown" && typeof item.cost === "number"
+    )
+    .map((item) => item.cost);
+
+const filterLine = (filter: AdvisorJevFilterLedger) => {
+  const head = `${filter.screened} screened (${filter.allowed} allowed, ${filter.skipped} skipped${filter.repeatSkipped > 0 ? ` [${filter.repeatSkipped} repeat]` : ""})`;
+  const parts = [head];
+  if (filter.overrides > 0) {
+    parts.push(
+      `${filter.overrides} override${filter.overrides === 1 ? "" : "s"}`
+    );
+  }
+  if (filter.failures > 0) {
+    parts.push(`${filter.failures} failure${filter.failures === 1 ? "" : "s"}`);
+  }
+  return `Jev filter: ${parts.join(", ")}`;
+};
+
+const gateLine = (
+  gate: AdvisorJevGateLedger,
+  invocations: readonly JevInvocationView[]
+) => {
+  const consultationCosts = invocations
+    .filter(
+      (item): item is JevInvocationView & { cost: number } =>
+        item.trigger === "turn-gate" && typeof item.cost === "number"
+    )
+    .map((item) => item.cost);
+  const gateSpend = consultationCosts.reduce((sum, cost) => sum + cost, 0);
+  return `Turn gate: ${gate.checks} check${gate.checks === 1 ? "" : "s"} (Jev ${formatJevTokens(gate.usage)} · $${gate.usage.cost.toFixed(4)}), ${gate.consultations} consultation${gate.consultations === 1 ? "" : "s"} ($${gateSpend.toFixed(4)})`;
+};
+
+/** One session's Jev screening and turn-gate accounting plus summary lines. */
+export class AdvisorJevLedgerState {
+  #ledger = freshJevLedger();
+  #lastSkip: JevSkipRecord | undefined;
+
+  reset() {
+    this.#ledger = freshJevLedger();
+    this.#lastSkip = undefined;
+  }
+
+  get lastSkip() {
+    return this.#lastSkip;
+  }
+
+  recordFilterAllowed() {
+    this.#ledger.filter.allowed += 1;
+    this.#ledger.filter.screened += 1;
+  }
+
+  recordFilterSkipped(
+    repeat: boolean,
+    normalizedQuestion: string | undefined,
+    turn: number
+  ) {
+    this.#ledger.filter.skipped += 1;
+    this.#ledger.filter.screened += 1;
+    if (repeat) {
+      this.#ledger.filter.repeatSkipped += 1;
+    }
+    const skip: JevSkipRecord = { turn };
+    if (normalizedQuestion) {
+      skip.normalizedQuestion = normalizedQuestion;
+    }
+    this.#lastSkip = skip;
+  }
+
+  recordFilterOverride() {
+    this.#ledger.filter.overrides += 1;
+  }
+
+  recordFilterFailure() {
+    this.#ledger.filter.failures += 1;
+  }
+
+  recordFilterUsage(usage: AdvisorJevUsage) {
+    addJevUsage(this.#ledger.usage, usage);
+  }
+
+  recordGateCheck(usage?: AdvisorJevUsage) {
+    this.#ledger.gate.checks += 1;
+    if (usage) {
+      addJevUsage(this.#ledger.gate.usage, usage);
+    }
+  }
+
+  recordGateConsultation() {
+    this.#ledger.gate.consultations += 1;
+  }
+
+  recordGateFailure() {
+    this.#ledger.gate.failures += 1;
+  }
+
+  summaryLines(invocations: readonly JevInvocationView[]): string[] {
+    const lines: string[] = [];
+    const { filter, gate, usage } = this.#ledger;
+    const nonRepeatJevActivity =
+      filter.allowed +
+      (filter.skipped - filter.repeatSkipped) +
+      filter.failures;
+    if (nonRepeatJevActivity === 0 && filter.repeatSkipped > 0) {
+      // Only dedup fired — no Jev call ever happened, so the line must not
+      // claim Jev activity.
+      const parts = [
+        `${filter.repeatSkipped} repeat question${filter.repeatSkipped === 1 ? "" : "s"} skipped, earlier advice reattached`,
+      ];
+      if (filter.overrides > 0) {
+        parts.push(
+          `${filter.overrides} override${filter.overrides === 1 ? "" : "s"}`
+        );
+      }
+      lines.push(
+        `Consultation dedup: ${parts.join(", ")}`,
+        savingsLine(markdownCosts(invocations), filter.skipped)
+      );
+    } else if (this.#filterActive()) {
+      lines.push(filterLine(filter));
+      const jevTokens = usage.inputTokens + usage.outputTokens;
+      if (jevTokens > 0) {
+        lines.push(
+          `Jev cost: ${formatJevTokens(usage)} tokens · $${usage.cost.toFixed(4)} (input only; output free)`
+        );
+      }
+      if (filter.skipped > 0) {
+        lines.push(savingsLine(markdownCosts(invocations), filter.skipped));
+      }
+    }
+    if (gate.checks > 0 || gate.consultations > 0) {
+      lines.push(gateLine(gate, invocations));
+    }
+    return lines;
+  }
+
+  #filterActive() {
+    const { filter } = this.#ledger;
+    return filter.screened > 0 || filter.overrides > 0 || filter.failures > 0;
+  }
+}

package/src/jev/questions.ts

@@ -0,0 +1,122 @@
+import type { Questions } from "@typesafe-ai/sdk";
+
+import { isNumber, isRecordOf } from "../content-utils.ts";
+import type { JsonValue } from "../content-utils.ts";
+
+/** Exact rubric text for the stakes Score question; level 0 is the skip level. */
+export const STAKES_RUBRIC = [
+  "Negligible: routine, low-risk, mechanical, or reversible; a wrong call costs little and is easy to undo.",
+  "Moderate: some risk or rework, but bounded and recoverable.",
+  "High: material consequences for correctness, security, cost, user trust, or irreversibility.",
+] as const;
+
+const EVIDENCE_RULE =
+  "Judge from `executor_question` and `executor_draft` when present, otherwise from `recent_conversation`; when both are absent, `recent_conversation` is the evidence to judge from.";
+
+export const screeningQuestions: Questions = {
+  self_answerable: {
+    criteria: {
+      false: "The executor needs the Advisor's second opinion.",
+      true: "The executor can resolve this alone with available tools and context.",
+    },
+    instructions: `Can the executor confidently resolve this request alone, using available tools and context? ${EVIDENCE_RULE}`,
+    type: "noul",
+  },
+  stakes: {
+    criteria: [...STAKES_RUBRIC],
+    instructions: `How material are the stakes of the decision behind this consultation request? ${EVIDENCE_RULE}`,
+    type: "score",
+  },
+};
+
+export interface TurnGateQuestions {
+  instructions: string;
+}
+
+export interface ScreeningCriteria {
+  noulMargin: number;
+  skipConfidence: number;
+}
+
+export type ScreeningVerdict = { skip: false } | { skip: true };
+
+const NUMERIC_KEY_PATTERN = /^\d+$/u;
+
+const finiteNumber = (value: JsonValue | undefined): number | undefined =>
+  isNumber(value) && Number.isFinite(value) ? value : undefined;
+
+/**
+ * Probability mass on the lowest stakes level, resolved through the answer's
+ * legend (the key whose description equals level 0), falling back to the
+ * smallest numeric index key only when no legend resolves. Shape-independent:
+ * never hardcodes a level key and never uses `ceil(score)`.
+ */
+export const lowestStakesProbability = <Answer>(
+  answer: Answer
+): number | undefined => {
+  if (!isRecordOf(answer)) {
+    return undefined;
+  }
+  const probabilities = isRecordOf(answer.probabilities)
+    ? answer.probabilities
+    : {};
+  const legend = isRecordOf(answer.legend) ? answer.legend : undefined;
+  if (legend) {
+    const exact = Object.keys(legend).find(
+      (key) => legend[key] === STAKES_RUBRIC[0]
+    );
+    if (exact) {
+      return finiteNumber(probabilities[exact]);
+    }
+  }
+  const numericKeys = Object.keys(probabilities).filter((key) =>
+    NUMERIC_KEY_PATTERN.test(key)
+  );
+  if (numericKeys.length === 0) {
+    return undefined;
+  }
+  let [lowest] = numericKeys;
+  for (const key of numericKeys) {
+    if (Number(key) < Number(lowest)) {
+      lowest = key;
+    }
+  }
+  return finiteNumber(probabilities[lowest]);
+};
+
+const selfAnswerableNoul = <Answer>(answer: Answer): number | undefined =>
+  isRecordOf(answer) ? finiteNumber(answer.noul) : undefined;
+
+/** Pure composition: skip requires the hard conjunction of confident
+ * negligible stakes AND confident self-answerability. Any missing, NaN, or
+ * malformed input allows. Never a weighted sum. */
+export const composeScreeningVerdict = <Answers>(
+  answers: Answers,
+  { noulMargin, skipConfidence }: ScreeningCriteria
+): ScreeningVerdict => {
+  if (!isRecordOf(answers)) {
+    return { skip: false };
+  }
+  const negligibleMass = lowestStakesProbability(answers.stakes);
+  const noul = selfAnswerableNoul(answers.self_answerable);
+  if (negligibleMass === undefined || noul === undefined) {
+    return { skip: false };
+  }
+  const confidentlySelfAnswerable = noul >= 0.5 + noulMargin;
+  return {
+    skip: negligibleMass >= skipConfidence && confidentlySelfAnswerable,
+  };
+};
+
+/** Confident-true only; any uncertainty means no invocation. */
+export const composeTurnGateVerdict = <Answers>(
+  answers: Answers,
+  threshold: number
+): boolean => {
+  if (!isRecordOf(answers)) {
+    return false;
+  }
+  const answer = answers.should_consult;
+  const noul = isRecordOf(answer) ? finiteNumber(answer.noul) : undefined;
+  return noul !== undefined && noul >= threshold;
+};

package/src/jev/state.ts

@@ -0,0 +1,50 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { JsonValue } from "@typesafe-ai/sdk";
+
+import {
+  advisorJevDigestMaxCharsRef,
+  advisorRedactSecretsRef,
+} from "../config/state.ts";
+import { recentConversation } from "../conversation.ts";
+import { redactAndCapText } from "../redaction.ts";
+
+/** Per-field byte cap for executor question and draft sent to Jev. */
+export const JEV_TEXT_CAP_BYTES = 8 * 1024;
+
+export interface JevStateInput {
+  draft?: string;
+  question?: string;
+}
+
+export type JevState = Record<string, JsonValue>;
+
+/** Builds the Jev screening state: named fields, redacted and capped through
+ * the existing egress pipeline, with the conversation digest as fallback
+ * evidence when no explicit request exists. */
+export const buildJevState = (
+  ctx: ExtensionContext,
+  input: JevStateInput = {}
+) => {
+  const fields = new Map<string, string>([["role", "executor"]]);
+  if (input.question) {
+    fields.set(
+      "executor_question",
+      redactAndCapText(
+        input.question,
+        JEV_TEXT_CAP_BYTES,
+        advisorRedactSecretsRef
+      )
+    );
+  }
+  if (input.draft) {
+    fields.set(
+      "executor_draft",
+      redactAndCapText(input.draft, JEV_TEXT_CAP_BYTES, advisorRedactSecretsRef)
+    );
+  }
+  const digest = recentConversation(ctx, advisorJevDigestMaxCharsRef);
+  if (digest) {
+    fields.set("recent_conversation", digest);
+  }
+  return Object.fromEntries(fields);
+};