pi-advisor-flow 0.6.0 → 0.8.0

package/src/jev/transport.ts

@@ -0,0 +1,63 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { advisorJevTransportRef } from "../config/state.ts";
+import { resolveTypeSafeKey } from "./key-store.ts";
+import type { JevKeySource } from "./key-store.ts";
+
+export type JevTransportKind = "typesafe" | "openrouter";
+
+export interface JevCredentials {
+  apiKey: string;
+  /** Where the TypeSafe key came from; present on the typesafe transport. */
+  source?: JevKeySource;
+  transport: JevTransportKind;
+}
+
+export interface JevTransportDeps {
+  /** Reads a pi-stored provider login; injectable for tests. */
+  getProviderKey?: (provider: string) => Promise<string | undefined>;
+  /** Resolves the TypeSafe key chain; injectable for tests. */
+  resolveTypesafe?: () => ReturnType<typeof resolveTypeSafeKey>;
+}
+
+const OPENROUTER_PROVIDER = "openrouter";
+
+const openRouterKey = async (
+  ctx: ExtensionContext | undefined,
+  deps: JevTransportDeps
+): Promise<string | undefined> => {
+  const key = deps.getProviderKey
+    ? await deps.getProviderKey(OPENROUTER_PROVIDER)
+    : await ctx?.modelRegistry?.getApiKeyForProvider(OPENROUTER_PROVIDER);
+  return key?.trim() || undefined;
+};
+
+/** Resolves how Jev calls authenticate: a dedicated TypeSafe key first, then
+ * the existing pi OpenRouter login (reuse per advisorJevTransport). */
+export const resolveJevTransport = async (
+  ctx?: ExtensionContext,
+  deps: JevTransportDeps = {}
+): Promise<JevCredentials | undefined> => {
+  const preference = advisorJevTransportRef;
+  if (preference !== "openrouter") {
+    const resolveTypesafe = deps.resolveTypesafe ?? resolveTypeSafeKey;
+    const resolution = await resolveTypesafe();
+    if (resolution.key) {
+      const credentials: JevCredentials = {
+        apiKey: resolution.key,
+        transport: "typesafe",
+      };
+      if (resolution.source) {
+        credentials.source = resolution.source;
+      }
+      return credentials;
+    }
+  }
+  if (preference === "typesafe") {
+    return undefined;
+  }
+  const openrouter = await openRouterKey(ctx, deps);
+  return openrouter
+    ? { apiKey: openrouter, transport: "openrouter" }
+    : undefined;
+};

package/src/model-stream.ts

@@ -1,11 +1,12 @@
-import {
-  type Api,
-  type AssistantMessage,
-  type Message,
-  type Model,
-  stream,
+import { stream } from "@earendil-works/pi-ai/compat";
+import type {
+  Api,
+  AssistantMessage,
+  Message,
+  Model,
 } from "@earendil-works/pi-ai/compat";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
 import { splitRef } from "./config/state.ts";
 
 export interface ResolvedConfiguredModel {
@@ -25,13 +26,14 @@ export const resolveConfiguredModel = async (
     throw new Error(`${label} model not configured`);
   }
   const [provider, modelId] = splitRef(ref);
-  const model = ctx.modelRegistry.find(provider, modelId);
+  const lookup: [string, string] = [provider, modelId];
+  const model = ctx.modelRegistry.find(...lookup);
   if (!model) {
     throw new Error(`${label} model not found: ${ref}`);
   }
   const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
   if (!auth.ok) {
-    throw new Error((auth as { error: string }).error);
+    throw new Error(auth.error);
   }
   if (!auth.apiKey) {
     throw new Error(`No API key for ${ref}`);
@@ -61,6 +63,12 @@ export interface CollectedTextStream {
 
 export const ADVISOR_STREAM_UPDATE_INTERVAL_MS = 90;
 
+const defaultScheduler: CoalescedUpdateScheduler = {
+  clearTimeout,
+  now: Date.now,
+  setTimeout: (callback, delay) => setTimeout(callback, delay),
+};
+
 interface CoalescedUpdateResult {
   error?: unknown;
   failed: boolean;
@@ -85,19 +93,14 @@ export interface CoalescedUpdateScheduler {
 export const createCoalescedUpdate = <T>(
   publish: (value: T) => void,
   intervalMs = ADVISOR_STREAM_UPDATE_INTERVAL_MS,
-  scheduler: CoalescedUpdateScheduler = {
-    clearTimeout,
-    now: Date.now,
-    setTimeout: (callback, delay) => setTimeout(callback, delay),
-  }
+  scheduler: CoalescedUpdateScheduler | undefined = defaultScheduler
 ): CoalescedUpdate<T> => {
   if (!Number.isFinite(intervalMs) || intervalMs <= 0) {
     throw new Error("Coalesced update interval must be positive and finite.");
   }
 
   let closed = false;
-  let hasPending = false;
-  let pending: T | undefined;
+  let pending: { value: T } | undefined;
   let lastPublishedAt: number | undefined;
   let timer: ReturnType<typeof setTimeout> | undefined;
   let publishError: unknown;
@@ -112,12 +115,11 @@ export const createCoalescedUpdate = <T>(
 
   const publishPending = () => {
     timer = undefined;
-    if (!hasPending) {
+    if (!pending) {
       return;
     }
-    const value = pending as T;
+    const { value } = pending;
     pending = undefined;
-    hasPending = false;
     lastPublishedAt = scheduler.now();
     try {
       publish(value);
@@ -150,7 +152,6 @@ export const createCoalescedUpdate = <T>(
       closed = true;
       clearTimer();
       pending = undefined;
-      hasPending = false;
     },
     flush: () => {
       if (!closed) {
@@ -167,8 +168,7 @@ export const createCoalescedUpdate = <T>(
       if (publishFailed) {
         throw publishError;
       }
-      pending = value;
-      hasPending = true;
+      pending = { value };
       if (timer === undefined) {
         schedule();
       }
@@ -186,22 +186,22 @@ export const collectTextStream = async (
 ): Promise<CollectedTextStream> => {
   let thinking = "";
   let text = "";
+  const streamOptions: Parameters<typeof streamModel>[2] = {
+    apiKey: resolved.apiKey,
+    env: resolved.env,
+    headers: resolved.headers,
+    // SAFETY: stream() models the provider-facing reasoning field as never; options.reasoning is the Pi-facing effort string.
+    reasoning: options.reasoning as never,
+    signal: options.signal,
+  };
+  if (options.reasoning !== undefined) {
+    // SAFETY: reasoningEffort takes the same effort string; kept absent when reasoning is unset.
+    streamOptions.reasoningEffort = options.reasoning as never;
+  }
   const eventStream = streamModel(
     resolved.model,
     { messages: options.messages, systemPrompt: options.systemPrompt },
-    {
-      apiKey: resolved.apiKey,
-      env: resolved.env,
-      headers: resolved.headers,
-      // `stream()` uses the provider-facing name while the extension's public
-      // option keeps the Pi-facing `reasoning` name. Preserve both so the
-      // configured effort reaches providers that serialize reasoning_effort.
-      reasoning: options.reasoning as never,
-      ...(options.reasoning === undefined
-        ? {}
-        : { reasoningEffort: options.reasoning as never }),
-      signal: options.signal,
-    }
+    streamOptions
   );
 
   for await (const event of eventStream) {
@@ -242,8 +242,6 @@ export const collectTextStream = async (
   return {
     text: finalText,
     thinking,
-    usage: (
-      lastAssistant as (AssistantMessage & { usage?: unknown }) | undefined
-    )?.usage,
+    usage: lastAssistant?.usage,
   };
 };

package/src/outcomes.ts

@@ -11,11 +11,17 @@ import {
   writeFile,
 } from "node:fs/promises";
 import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+
 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 = "manual" | "executor-requested" | "repeated-tool-call";
+type OutcomeTrigger =
+  | "manual"
+  | "executor-requested"
+  | "turn-gate"
+  | "repeated-tool-call";
 export const ADOPTIONS: OutcomeAdoption[] = [
   "followed",
   "not-followed",
@@ -40,12 +46,15 @@ const statePath = () => join(getAgentDir(), "advisor-outcomes-salt");
 export const outcomeLogPath = () =>
   join(getAgentDir(), "advisor-outcomes.jsonl");
 
+const isErrnoException = (error: unknown): error is NodeJS.ErrnoException =>
+  error instanceof Error && "code" in error;
+
 const salt = async () => {
   const path = statePath();
   await mkdir(getAgentDir(), { mode: 0o700, recursive: true });
   for (let attempt = 0; attempt < 20; attempt += 1) {
     try {
-      // biome-ignore lint/performance/noAwaitInLoops: contenders retry sequentially until one salt is atomically published.
+      // Contenders retry sequentially until one salt is atomically published.
       const existing = await readFile(path);
       if (existing.length === 32) {
         return existing;
@@ -53,7 +62,7 @@ const salt = async () => {
       // Recover a salt file left incomplete by an interrupted older writer.
       await unlink(path);
     } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      if (!isErrnoException(error) || error.code !== "ENOENT") {
         throw error;
       }
     }
@@ -64,7 +73,7 @@ const salt = async () => {
       await link(temporary, path);
       return value;
     } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+      if (!isErrnoException(error) || error.code !== "EEXIST") {
         throw error;
       }
     } finally {
@@ -82,7 +91,7 @@ const withOutcomeLock = async <T>(run: () => Promise<T>): Promise<T> => {
   const lockPath = `${outcomeLogPath()}.lock`;
   for (let attempt = 0; attempt < 200; attempt += 1) {
     try {
-      // biome-ignore lint/performance/noAwaitInLoops: lock acquisition must retry sequentially across processes.
+      // Lock acquisition must retry sequentially across processes.
       const lock = await open(lockPath, "wx", 0o600);
       const identity = await lock.stat();
       try {
@@ -95,7 +104,7 @@ const withOutcomeLock = async <T>(run: () => Promise<T>): Promise<T> => {
         }
       }
     } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+      if (!isErrnoException(error) || error.code !== "EEXIST") {
         throw error;
       }
       const observed = await stat(lockPath).catch(() => undefined);
@@ -106,7 +115,7 @@ const withOutcomeLock = async <T>(run: () => Promise<T>): Promise<T> => {
         }
         continue;
       }
-      await new Promise((resolve) => setTimeout(resolve, 5));
+      await sleep(5);
     }
   }
   throw new Error("Timed out waiting to append an Advisor outcome.");
@@ -141,11 +150,10 @@ export const appendOutcome = async (
         }
         throw error;
       });
-    if (currentBytes + Buffer.byteLength(line) > MAX_LOG_BYTES) {
-      await writeFile(path, line, { encoding: "utf8", mode: 0o600 });
-    } else {
-      await appendFile(path, line, { encoding: "utf8", mode: 0o600 });
-    }
+    const overflow = currentBytes + Buffer.byteLength(line) > MAX_LOG_BYTES;
+    await (overflow
+      ? writeFile(path, line, { encoding: "utf-8", mode: 0o600 })
+      : appendFile(path, line, { encoding: "utf-8", mode: 0o600 }));
     await chmod(path, 0o600);
     return next;
   });

package/src/pi-settings.ts

@@ -1,10 +1,9 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
+
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
-interface PiGlobalSettings {
-  hideThinkingBlock?: boolean;
-}
+import { isRecord } from "./content-utils.ts";
 
 interface CachedSetting {
   hidden: boolean;
@@ -27,12 +26,8 @@ const settingsIdentity = (path: string): string => {
 
 const readHideThinking = (path: string): boolean => {
   try {
-    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
-    return (
-      typeof parsed === "object" &&
-      parsed !== null &&
-      (parsed as PiGlobalSettings).hideThinkingBlock === true
-    );
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    return isRecord(parsed) && parsed.hideThinkingBlock === true;
   } catch {
     return false;
   }

package/src/preferences.ts

@@ -1,6 +1,8 @@
 import { lstat, open, realpath } from "node:fs/promises";
 import { join, relative } from "node:path";
+
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
 import { redactAndCapText } from "./redaction.ts";
 
 const PREFERENCES_MAX_BYTES = 8 * 1024;
@@ -40,9 +42,9 @@ export const readProjectPreferences = async (
     try {
       const buffer = Buffer.alloc(maxBytes + 1);
       const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
-      const source = buffer.subarray(0, bytesRead).toString("utf8");
+      const source = buffer.subarray(0, bytesRead).toString("utf-8");
       const capped = redactAndCapText(source, maxBytes, redact);
-      return { bytes: Buffer.byteLength(capped, "utf8"), text: capped };
+      return { bytes: Buffer.byteLength(capped, "utf-8"), text: capped };
     } finally {
       await file.close();
     }

package/src/redaction.ts

@@ -1,15 +1,15 @@
-import { capUtf8Bytes } from "./content-utils.ts";
+import { capUtf8Bytes, isString } from "./content-utils.ts";
 
 const REDACTION_MARKER = "[REDACTED SECRET]";
-const PEM_BEGIN_PATTERN = /-----BEGIN(?: [A-Z0-9]+)? PRIVATE KEY-----/gi;
-const PEM_END_PATTERN = /-----END(?: [A-Z0-9]+)? PRIVATE KEY-----/i;
+const PEM_BEGIN_PATTERN = /-----BEGIN(?: [A-Z0-9]+)? PRIVATE KEY-----/giu;
+const PEM_END_PATTERN = /-----END(?: [A-Z0-9]+)? PRIVATE KEY-----/iu;
 const SECRET_PATTERNS = [
-  /-----BEGIN(?: [A-Z0-9]+)? PRIVATE KEY-----[\s\S]*?-----END(?: [A-Z0-9]+)? PRIVATE KEY-----/gi,
-  /\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi,
-  /\b(?:api[_-]?key|token|secret|password|passwd)\s*[:=]\s*(?:"[^"]*"|'[^']*'|[^\s"'&,;)}\]]+)/gi,
-  /([a-z][a-z0-9+.-]*:\/\/)[^\s/@:]+:[^\s/@]+@/gi,
-  /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g,
-  /\b(?:aws_secret_access_key|aws_session_token)\s*[:=]\s*[^\s"'&,;)}\]]+/gi,
+  /-----BEGIN(?: [A-Z0-9]+)? PRIVATE KEY-----[\s\S]*?-----END(?: [A-Z0-9]+)? PRIVATE KEY-----/giu,
+  /\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/giu,
+  /\b(?:api[_-]?key|token|secret|password|passwd)\s*[:=]\s*(?:"[^"]*"|'[^']*'|[^\s"'&,;)}\]]+)/giu,
+  /(?<scheme>[a-z][a-z0-9+.-]*:\/\/)[^\s/@:]+:[^\s/@]+@/giu,
+  /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/gu,
+  /\b(?:aws_secret_access_key|aws_session_token)\s*[:=]\s*[^\s"'&,;)}\]]+/giu,
 ] as const;
 
 const redactUnterminatedPem = (value: string): string => {
@@ -31,9 +31,7 @@ export const redactSecrets = (value: string): string => {
   let redacted = redactUnterminatedPem(value);
   for (const pattern of SECRET_PATTERNS) {
     redacted = redacted.replace(pattern, (_match, scheme) =>
-      typeof scheme === "string"
-        ? `${scheme}${REDACTION_MARKER}@`
-        : REDACTION_MARKER
+      isString(scheme) ? `${scheme}${REDACTION_MARKER}@` : REDACTION_MARKER
     );
   }
   return redacted;

package/src/scout-context.ts

@@ -1,27 +1,26 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
 import {
   advisorRedactSecretsRef,
   advisorToolPoliciesRef,
   advisorToolResultMaxBytesRef,
   advisorToolResultMaxLinesRef,
 } from "./config/state.ts";
-import {
-  buildGroups,
-  type DisclosureCaps,
-  type GroupPass,
-  groupWireBytes,
-} from "./scout-groups.ts";
+import { buildGroups, groupWireBytes } from "./scout-groups.ts";
+import type { DisclosureCaps, GroupPass } from "./scout-groups.ts";
 import { indexToolCalls } from "./scout-protocol.ts";
 import {
-  type BuildScoutManifestOptions,
   SCOUT_GROUP_MAX_BYTES,
   SCOUT_MANIFEST_MAX_BYTES,
   SCOUT_MANIFEST_MAX_GROUPS,
-  type ScoutContextGroup,
-  type ScoutManifestResult,
+} from "./scout-types.ts";
+import type {
+  BuildScoutManifestOptions,
+  ScoutContextGroup,
+  ScoutManifestResult,
 } from "./scout-types.ts";
 
-// biome-ignore lint/performance/noBarrelFile: re-export preserves scout-context's historical public import surface.
+// Re-exports preserve scout-context's historical public import surface.
 export { reconstructScoutConversation } from "./scout-reconstruct.ts";
 export type {
   BuildScoutManifestOptions,
@@ -54,21 +53,44 @@ const resolveCaps = (
 });
 
 /** Builds disclosed, indivisible history groups from Pi's compaction-aware branch. */
-export const buildScoutManifest = (
-  ctx: ExtensionContext,
-  options: BuildScoutManifestOptions = {}
-): ScoutManifestResult => {
-  const entries = ctx.sessionManager.buildContextEntries();
-  const caps = resolveCaps(options);
-  const indexed = indexToolCalls(entries);
-  if (!indexed.ok) {
-    return indexed;
+const contentChars = (items: ScoutContextGroup[]) =>
+  items.reduce((sum, group) => sum + group.content.length, 0) +
+  Math.max(0, items.length - 1) * 2;
+
+const requiredOverflow = (
+  required: ScoutContextGroup[],
+  caps: {
+    maxConversationChars?: number;
+    maxGroupBytes: number;
+    maxGroups: number;
+    maxManifestBytes: number;
   }
-  const built = buildGroups(entries, indexed.index, caps);
-  if (!built.ok) {
-    return built;
+): ScoutManifestResult | undefined => {
+  if (
+    required.some((group) => group.bytes > caps.maxGroupBytes) ||
+    required.length > caps.maxGroups ||
+    required.reduce((sum, group) => sum + groupWireBytes(group), 0) >
+      caps.maxManifestBytes
+  ) {
+    return {
+      message:
+        "Required Scout context exceeds the Scout manifest transport limit.",
+      ok: false,
+      reason: "required-group-overflow",
+    };
   }
-  return fitToBudget(built, caps);
+  if (
+    caps.maxConversationChars !== undefined &&
+    contentChars(required) > caps.maxConversationChars
+  ) {
+    return {
+      message:
+        "Required Scout context exceeds the Advisor conversation budget.",
+      ok: false,
+      reason: "required-group-overflow",
+    };
+  }
+  return undefined;
 };
 
 const fits = (
@@ -86,10 +108,6 @@ const fits = (
   (caps.maxConversationChars === undefined ||
     contentChars(selected) <= caps.maxConversationChars);
 
-const contentChars = (items: ScoutContextGroup[]) =>
-  items.reduce((sum, group) => sum + group.content.length, 0) +
-  Math.max(0, items.length - 1) * 2;
-
 const fitToBudget = (
   built: GroupPass,
   caps: {
@@ -126,7 +144,7 @@ const fitToBudget = (
   );
   while (!fits(selected, caps)) {
     const optionalIndex = selected.findIndex((group) => !group.required);
-    if (optionalIndex < 0) {
+    if (optionalIndex === -1) {
       return {
         message: "Required Scout context exceeds fixed manifest limits.",
         ok: false,
@@ -151,38 +169,19 @@ const fitToBudget = (
   };
 };
 
-const requiredOverflow = (
-  required: ScoutContextGroup[],
-  caps: {
-    maxConversationChars?: number;
-    maxGroupBytes: number;
-    maxGroups: number;
-    maxManifestBytes: number;
-  }
-): ScoutManifestResult | undefined => {
-  if (
-    required.some((group) => group.bytes > caps.maxGroupBytes) ||
-    required.length > caps.maxGroups ||
-    required.reduce((sum, group) => sum + groupWireBytes(group), 0) >
-      caps.maxManifestBytes
-  ) {
-    return {
-      message:
-        "Required Scout context exceeds the Scout manifest transport limit.",
-      ok: false,
-      reason: "required-group-overflow",
-    };
+export const buildScoutManifest = (
+  ctx: ExtensionContext,
+  options: BuildScoutManifestOptions = {}
+): ScoutManifestResult => {
+  const entries = ctx.sessionManager.buildContextEntries();
+  const caps = resolveCaps(options);
+  const indexed = indexToolCalls(entries);
+  if (!indexed.ok) {
+    return indexed;
   }
-  if (
-    caps.maxConversationChars !== undefined &&
-    contentChars(required) > caps.maxConversationChars
-  ) {
-    return {
-      message:
-        "Required Scout context exceeds the Advisor conversation budget.",
-      ok: false,
-      reason: "required-group-overflow",
-    };
+  const built = buildGroups(entries, indexed.index, caps);
+  if (!built.ok) {
+    return built;
   }
-  return undefined;
+  return fitToBudget(built, caps);
 };

package/src/scout-curation.ts

@@ -1,15 +1,13 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
 import { advisorScoutEnabledRef, executorRef } from "./config/state.ts";
-import {
-  runAdvisorScout,
-  type ScoutLifecycleEvent,
-  type ScoutOutcome,
-} from "./scout.ts";
 import {
   buildScoutManifest,
   reconstructScoutConversation,
   SCOUT_MANIFEST_MAX_BYTES,
 } from "./scout-context.ts";
+import { runAdvisorScout } from "./scout.ts";
+import type { ScoutLifecycleEvent, ScoutOutcome } from "./scout.ts";
 
 /** Runs Scout over the manifested branch and reconstructs the curated
  * conversation, falling back to the exact legacy conversation on any
@@ -55,14 +53,7 @@ export const curateAdvisorConversation = async (
     onScout?.({ outcome: scout, type: "fallback" });
     return { conversation: legacyConversation, scout };
   }
-  const outcome = await runScout(
-    ctx,
-    built.manifest,
-    signal,
-    onScout,
-    undefined,
-    undefined
-  );
+  const outcome = await runScout(ctx, built.manifest, signal, onScout);
   if (!outcome.ok && outcome.cancelled) {
     throw signal?.reason instanceof Error
       ? signal.reason