pi-advisor-flow 0.9.2-dev.4 → 0.10.0

package/src/follow-up.ts

@@ -0,0 +1,85 @@
+import type { Message } from "@earendil-works/pi-ai/compat";
+
+export const FOLLOW_UP_TTL_MS = 5 * 60 * 1000;
+export const FOLLOW_UP_MAX_DEPTH = 3;
+export const FOLLOW_UP_MAX_TOOL_CALLS = 3;
+
+export interface AdvisorFollowUpPayload {
+  depth: number;
+  messages: Message[];
+  model: string;
+  privacyKey: string;
+  redacted: boolean;
+  systemPrompt: string;
+}
+
+export interface AdvisorFollowUpLookup {
+  payload?: AdvisorFollowUpPayload;
+  reason?: string;
+}
+
+interface StoredFollowUpPayload extends AdvisorFollowUpPayload {
+  expiresAt: number;
+  toolCallsSince: number;
+}
+
+const copy = <Value>(value: Value): Value => structuredClone(value);
+
+export class AdvisorFollowUpCache {
+  readonly #entries = new Map<string, StoredFollowUpPayload>();
+  readonly #now: () => number;
+
+  constructor(now: () => number = Date.now) {
+    this.#now = now;
+  }
+
+  clear() {
+    this.#entries.clear();
+  }
+
+  advanceToolCall() {
+    const now = this.#now();
+    for (const [adviceId, entry] of this.#entries) {
+      if (
+        now >= entry.expiresAt ||
+        entry.toolCallsSince + 1 >= FOLLOW_UP_MAX_TOOL_CALLS
+      ) {
+        this.#entries.delete(adviceId);
+        continue;
+      }
+      entry.toolCallsSince += 1;
+    }
+  }
+
+  capture(
+    adviceId: string,
+    payload: AdvisorFollowUpPayload,
+    replacesAdviceId?: string
+  ) {
+    if (replacesAdviceId) {
+      this.#entries.delete(replacesAdviceId);
+    }
+    this.#entries.set(adviceId, {
+      ...copy(payload),
+      expiresAt: this.#now() + FOLLOW_UP_TTL_MS,
+      toolCallsSince: 0,
+    });
+  }
+
+  get(adviceId: string): AdvisorFollowUpLookup {
+    const entry = this.#entries.get(adviceId);
+    if (!entry) {
+      return { reason: "the adviceId is unknown or no longer cached" };
+    }
+    if (this.#now() >= entry.expiresAt) {
+      this.#entries.delete(adviceId);
+      return { reason: "the cached payload has expired" };
+    }
+    if (entry.depth >= FOLLOW_UP_MAX_DEPTH) {
+      return {
+        reason: `the follow-up chain is limited to ${FOLLOW_UP_MAX_DEPTH} follow-ups`,
+      };
+    }
+    return { payload: copy(entry) };
+  }
+}

package/src/outcome-stats.ts

@@ -0,0 +1,154 @@
+import { readFile } from "node:fs/promises";
+
+import { isRecord, isString } from "./content-utils.ts";
+import {
+  ADOPTIONS,
+  OUTCOME_TRIGGERS,
+  VALIDATIONS,
+  outcomeLogPath,
+} from "./outcomes.ts";
+import type {
+  OutcomeAdoption,
+  OutcomeRecord,
+  OutcomeTrigger,
+} from "./outcomes.ts";
+
+interface OutcomeValidationStats {
+  failed: number;
+  notRun: number;
+  passed: number;
+  passRate?: number;
+  total: number;
+  unknown: number;
+}
+export interface OutcomeStats {
+  adoption: Record<OutcomeAdoption, number>;
+  byTrigger: Record<OutcomeTrigger, number>;
+  distinctAdvices: number;
+  firstTimestamp?: string;
+  lastTimestamp?: string;
+  malformedLines: number;
+  total: number;
+  validationByAdoption: Record<OutcomeAdoption, OutcomeValidationStats>;
+}
+export interface OutcomeLogRead {
+  malformedLines: number;
+  missing: boolean;
+  records: OutcomeRecord[];
+}
+
+const ADOPTION_SET = new Set<string>(ADOPTIONS);
+const VALIDATION_SET = new Set<string>(VALIDATIONS);
+const TRIGGER_SET = new Set<string>(OUTCOME_TRIGGERS);
+const isErrnoException = (error: unknown): error is NodeJS.ErrnoException =>
+  error instanceof Error && "code" in error;
+
+const isOutcomeRecord = (value: unknown): value is OutcomeRecord =>
+  isRecord(value) &&
+  value.v === 1 &&
+  isString(value.adoption) &&
+  ADOPTION_SET.has(value.adoption) &&
+  isString(value.adviceHash) &&
+  isString(value.timestamp) &&
+  Number.isFinite(Date.parse(value.timestamp)) &&
+  isString(value.trigger) &&
+  TRIGGER_SET.has(value.trigger) &&
+  isString(value.validationStatus) &&
+  VALIDATION_SET.has(value.validationStatus);
+
+export const parseOutcomeLog = (text: string): OutcomeLogRead => {
+  const records: OutcomeRecord[] = [];
+  let malformedLines = 0;
+  for (const line of text.split(/\r?\n/u)) {
+    if (!line.trim()) {
+      continue;
+    }
+    try {
+      const value: unknown = JSON.parse(line);
+      if (isOutcomeRecord(value)) {
+        records.push(value);
+      } else {
+        malformedLines += 1;
+      }
+    } catch {
+      malformedLines += 1;
+    }
+  }
+  return { malformedLines, missing: false, records };
+};
+
+export const readOutcomeLog = async (
+  path = outcomeLogPath()
+): Promise<OutcomeLogRead> => {
+  try {
+    return parseOutcomeLog(await readFile(path, "utf-8"));
+  } catch (error) {
+    if (isErrnoException(error) && error.code === "ENOENT") {
+      return { malformedLines: 0, missing: true, records: [] };
+    }
+    throw error;
+  }
+};
+
+const emptyValidationStats = (): OutcomeValidationStats => ({
+  failed: 0,
+  notRun: 0,
+  passed: 0,
+  total: 0,
+  unknown: 0,
+});
+
+export const aggregateOutcomeRecords = (
+  records: readonly OutcomeRecord[],
+  malformedLines = 0
+): OutcomeStats => {
+  // SAFETY: ADOPTIONS enumerates every key in the returned adoption record.
+  const adoption = Object.fromEntries(
+    ADOPTIONS.map((value) => [value, 0])
+  ) as Record<OutcomeAdoption, number>;
+  // SAFETY: OUTCOME_TRIGGERS enumerates every key in the returned trigger record.
+  const byTrigger = Object.fromEntries(
+    OUTCOME_TRIGGERS.map((value) => [value, 0])
+  ) as Record<OutcomeTrigger, number>;
+  // SAFETY: ADOPTIONS enumerates every key and each value gets a fresh stats object.
+  const validationByAdoption = Object.fromEntries(
+    ADOPTIONS.map((value) => [value, emptyValidationStats()])
+  ) as Record<OutcomeAdoption, OutcomeValidationStats>;
+  const adviceHashes = new Set<string>();
+  let first: { timestamp: string; time: number } | undefined;
+  let last: { timestamp: string; time: number } | undefined;
+
+  for (const record of records) {
+    adoption[record.adoption] += 1;
+    byTrigger[record.trigger] += 1;
+    adviceHashes.add(record.adviceHash);
+    const validation = validationByAdoption[record.adoption];
+    validation.total += 1;
+    validation[
+      record.validationStatus === "not-run" ? "notRun" : record.validationStatus
+    ] += 1;
+    const time = Date.parse(record.timestamp);
+    if (!first || time < first.time) {
+      first = { time, timestamp: record.timestamp };
+    }
+    if (!last || time > last.time) {
+      last = { time, timestamp: record.timestamp };
+    }
+  }
+  for (const value of Object.values(validationByAdoption)) {
+    const validated = value.passed + value.failed;
+    if (validated > 0) {
+      value.passRate = value.passed / validated;
+    }
+  }
+  return {
+    adoption,
+    byTrigger,
+    distinctAdvices: adviceHashes.size,
+    firstTimestamp: first?.timestamp,
+    lastTimestamp: last?.timestamp,
+    malformedLines,
+    total: records.length,
+    validationByAdoption,
+  };
+};

package/src/outcomes.ts

@@ -17,7 +17,7 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 export type OutcomeAdoption = "followed" | "not-followed" | "unknown";
 export type OutcomeValidation = "passed" | "failed" | "not-run" | "unknown";
-type OutcomeTrigger =
+export type OutcomeTrigger =
   | "manual"
   | "executor-requested"
   | "turn-gate"
@@ -33,6 +33,12 @@ export const VALIDATIONS: OutcomeValidation[] = [
   "not-run",
   "unknown",
 ];
+export const OUTCOME_TRIGGERS: OutcomeTrigger[] = [
+  "manual",
+  "executor-requested",
+  "turn-gate",
+  "repeated-tool-call",
+];
 export interface OutcomeRecord {
   adoption: OutcomeAdoption;
   adviceHash: string;
@@ -42,6 +48,7 @@ export interface OutcomeRecord {
   validationStatus: OutcomeValidation;
 }
 const MAX_LOG_BYTES = 1024 * 1024;
+export const OUTCOME_LOG_MAX_BYTES = MAX_LOG_BYTES;
 const statePath = () => join(getAgentDir(), "advisor-outcomes-salt");
 export const outcomeLogPath = () =>
   join(getAgentDir(), "advisor-outcomes.jsonl");

package/src/preferences.ts

@@ -1,36 +1,67 @@
 import { constants } from "node:fs";
 import { lstat, open, realpath } from "node:fs/promises";
-import { join, relative } from "node:path";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
 
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import { redactAndCapText } from "./redaction.ts";
 
 const PREFERENCES_MAX_BYTES = 8 * 1024;
-// Keep the local filename components separate from Socket's URL-string heuristic.
+// Keep local filename components separate from Socket's URL-string heuristic.
 const PREFERENCES_FILENAME = ["advisor-preferences", "md"].join(".");
+const AGENTS_FILENAME = "AGENTS.md";
 export interface TextAttachment {
   bytes: number;
   text: string;
 }
 
+export interface ProjectRulesAttachment {
+  bytes: number;
+  global?: TextAttachment;
+  project?: TextAttachment;
+  withheldReason?: "untrusted";
+}
+
 const inside = (root: string, candidate: string) => {
   const path = relative(root, candidate);
-  return path === "" || !(path.startsWith("..") || path.includes("../"));
+  return (
+    path === "" ||
+    (path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path))
+  );
 };
 
-/** Reads trusted project preferences without following a file or root escape. */
-export const readProjectPreferences = async (
-  ctx: ExtensionContext,
-  maxBytes = PREFERENCES_MAX_BYTES,
-  redact = true
+const hasSymlinkBelow = async (rootCandidate: string, candidate: string) => {
+  const root = resolve(rootCandidate);
+  const target = resolve(candidate);
+  if (!inside(root, target)) {
+    return true;
+  }
+  let current = root;
+  for (const part of relative(root, target).split(sep).filter(Boolean)) {
+    current = join(current, part);
+    const stats = await lstat(current);
+    if (stats.isSymbolicLink()) {
+      return true;
+    }
+  }
+  return false;
+};
+
+const readTrustedText = async (
+  candidate: string,
+  rootCandidate: string,
+  maxBytes: number,
+  redact: boolean
 ): Promise<TextAttachment | undefined> => {
-  if (!ctx.isProjectTrusted()) {
+  if (maxBytes <= 0) {
     return;
   }
   try {
-    const root = await realpath(ctx.cwd);
-    const candidate = join(ctx.cwd, ".pi", PREFERENCES_FILENAME);
+    const root = await realpath(rootCandidate);
+    if (await hasSymlinkBelow(rootCandidate, candidate)) {
+      return;
+    }
     const stats = await lstat(candidate);
     if (stats.isSymbolicLink() || !stats.isFile()) {
       return;
@@ -39,6 +70,9 @@ export const readProjectPreferences = async (
     if (!inside(root, resolved)) {
       return;
     }
+    if (await hasSymlinkBelow(rootCandidate, candidate)) {
+      return;
+    }
     const flags = constants.O_NOFOLLOW
       ? constants.O_RDONLY + constants.O_NOFOLLOW
       : constants.O_RDONLY;
@@ -61,6 +95,50 @@ export const readProjectPreferences = async (
       await file.close();
     }
   } catch {
-    // Missing, unreadable, or unsafe preferences are intentionally withheld.
+    // Missing, unreadable, or unsafe files are intentionally withheld.
+  }
+};
+
+export const readProjectPreferences = (
+  ctx: ExtensionContext,
+  maxBytes = PREFERENCES_MAX_BYTES,
+  redact = true
+): Promise<TextAttachment | undefined> => {
+  if (!ctx.isProjectTrusted()) {
+    return Promise.resolve(undefined);
+  }
+  return readTrustedText(
+    join(ctx.cwd, ".pi", PREFERENCES_FILENAME),
+    ctx.cwd,
+    maxBytes,
+    redact
+  );
+};
+
+export const readProjectRules = async (
+  ctx: ExtensionContext,
+  maxBytes = PREFERENCES_MAX_BYTES,
+  redact = true
+): Promise<ProjectRulesAttachment> => {
+  if (!ctx.isProjectTrusted()) {
+    return { bytes: 0, withheldReason: "untrusted" };
   }
+  const project = await readTrustedText(
+    join(ctx.cwd, AGENTS_FILENAME),
+    ctx.cwd,
+    maxBytes,
+    redact
+  );
+  const remaining = Math.max(0, maxBytes * 2 - (project?.bytes ?? 0));
+  const global = await readTrustedText(
+    join(getAgentDir(), AGENTS_FILENAME),
+    getAgentDir(),
+    Math.min(maxBytes, remaining),
+    redact
+  );
+  return {
+    bytes: (project?.bytes ?? 0) + (global?.bytes ?? 0),
+    global,
+    project,
+  };
 };

package/src/session-state.ts

@@ -1,5 +1,10 @@
 import { isRecordOf, isString } from "./content-utils.ts";
 import type { JsonValue } from "./content-utils.ts";
+import { AdvisorFollowUpCache } from "./follow-up.ts";
+import type {
+  AdvisorFollowUpLookup,
+  AdvisorFollowUpPayload,
+} from "./follow-up.ts";
 import { AdvisorJevLedgerState } from "./jev/ledger.ts";
 import type { AdvisorJevUsage } from "./jev/ledger.ts";
 import {
@@ -22,6 +27,7 @@ type ExecutionEffect = "continued" | "tool-blocked" | "session-blocked";
 export interface AdvisorInvocationRecord {
   cost?: number;
   decision?: GateDecision;
+  followUp?: boolean;
   executionEffect: ExecutionEffect;
   failure?: string;
   kind: "markdown" | "gate";
@@ -179,9 +185,14 @@ export class AdvisorSessionState {
   #consumedCalls = 0;
   #callReservations = new Set<string>();
   readonly #jev = new AdvisorJevLedgerState();
+  readonly #followUps: AdvisorFollowUpCache;
   #sessionTurnOrdinal = 0;
   #turnsSinceConsultation = 0;
 
+  constructor(now?: () => number) {
+    this.#followUps = new AdvisorFollowUpCache(now);
+  }
+
   resetTask() {
     this.#repetition = freshRepetition();
     this.#blockedReason = undefined;
@@ -190,6 +201,7 @@ export class AdvisorSessionState {
     this.#consumedCalls = 0;
     this.#callReservations.clear();
     this.#jev.reset();
+    this.#followUps.clear();
     this.#sessionTurnOrdinal = 0;
     this.#turnsSinceConsultation = 0;
   }
@@ -268,6 +280,26 @@ export class AdvisorSessionState {
     return this.#consumedCalls;
   }
 
+  advanceFollowUpToolCall() {
+    this.#followUps.advanceToolCall();
+  }
+
+  clearFollowUps() {
+    this.#followUps.clear();
+  }
+
+  followUpFor(adviceId: string): AdvisorFollowUpLookup {
+    return this.#followUps.get(adviceId);
+  }
+
+  captureFollowUp(
+    adviceId: string,
+    payload: AdvisorFollowUpPayload,
+    replacesAdviceId?: string
+  ) {
+    this.#followUps.capture(adviceId, payload, replacesAdviceId);
+  }
+
   /** Counts one completed executor turn on both turn counters. The ordinal
    * feeds the filter override window and summary positions and is never reset
    * by anything; turnsSinceConsultation resets on every consultation. */
@@ -495,6 +527,7 @@ export class AdvisorSessionState {
       `Budget: ${budget}`,
       `Usage: ${formatAdvisorUsageTotals(totals)}`,
       `Markdown advice: ${markdown.length} responses (${this.#ledger.draftConsultations} with drafts)`,
+      `Follow-ups: ${markdown.filter((item) => item.followUp).length}`,
       `Outcome reports: ${this.#ledger.outcomes}`,
       `Gate decisions: ${this.#decisionsLine()}`,
       `Loop matching: normalized tool signatures; ${this.#repetition.interventions} gate intervention${this.#repetition.interventions === 1 ? "" : "s"}`,

package/src/tools/consult-context.ts

@@ -6,6 +6,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { readTrackedFiles, readUntrackedFiles } from "../attachments.ts";
 import type { UntrackedAttachment } from "../attachments.ts";
 import {
+  advisorAgentsMdContextRef,
   advisorGitContextMaxCharsRef,
   advisorGitContextRef,
   advisorRedactSecretsRef,
@@ -23,7 +24,7 @@ import {
   ADVISOR_IMAGES_TOTAL_MAX_BYTES,
   selectedConversationImages,
 } from "../images.ts";
-import { readProjectPreferences } from "../preferences.ts";
+import { readProjectPreferences, readProjectRules } from "../preferences.ts";
 import { redactAndCapText, redactSecrets } from "../redaction.ts";
 import { curateAdvisorConversation } from "../scout-curation.ts";
 import { runAdvisorScout } from "../scout.ts";
@@ -64,6 +65,8 @@ export interface ConsultationContext {
   supportsImages: boolean;
   /** Redacted project preferences, if present. */
   preferences?: { bytes: number; text: string };
+  /** Redacted trusted AGENTS.md files, or a withheld-project note. */
+  projectRules?: Awaited<ReturnType<typeof readProjectRules>>;
   /** Non-cancelling Scout outcome, when Scout ran. */
   scout?: Exclude<ScoutOutcome, { cancelled: true }>;
   /** Redacted tracked-file attachments. */
@@ -130,6 +133,13 @@ export const assembleConsultationContext = async (
     ATTACHMENT_TEXT_MAX_BYTES,
     advisorRedactSecretsRef
   );
+  const projectRules = advisorAgentsMdContextRef
+    ? await readProjectRules(
+        ctx,
+        ATTACHMENT_TEXT_MAX_BYTES,
+        advisorRedactSecretsRef
+      )
+    : undefined;
   const draftText = options.draft
     ? redactAndCapText(
         options.draft,
@@ -215,6 +225,7 @@ export const assembleConsultationContext = async (
     imagePartsSeen: census.imagePartsSeen,
     images,
     preferences,
+    projectRules,
     scout: curated.scout,
     supportsImages,
     tracked,