pi-advisor-flow 0.7.0 → 0.8.1-dev.1

package/src/scout-protocol.ts

@@ -1,4 +1,5 @@
-import { contentParts, isRecord, type RecordValue } from "./content-utils.ts";
+import { contentParts, isRecord, isString } from "./content-utils.ts";
+import type { RecordValue } from "./content-utils.ts";
 import { textFrom } from "./conversation.ts";
 import type { InvalidProtocolResult } from "./scout-types.ts";
 
@@ -12,7 +13,7 @@ export const invalid = (message: string): InvalidProtocolResult => ({
 export interface ToolCallIndex {
   callOwners: Map<string, { index: number; name: string }>;
   latestUserIndex: number;
-  resultsByCall: Map<string, Array<{ entry: RecordValue; index: number }>>;
+  resultsByCall: Map<string, { entry: RecordValue; index: number }[]>;
 }
 
 export const toolCalls = (message: RecordValue) =>
@@ -21,51 +22,51 @@ export const toolCalls = (message: RecordValue) =>
   );
 
 export const toolCallId = (part: RecordValue) =>
-  typeof part.id === "string" ? part.id : undefined;
+  isString(part.id) ? part.id : undefined;
 
-/** First entry pass: indexes assistant tool calls and their results, tracking
- * the latest user message. Returns an invalid result on protocol violations. */
-export const indexToolCalls = (
-  entries: unknown[]
-): { index: ToolCallIndex; ok: true } | InvalidProtocolResult => {
-  const callOwners = new Map<string, { index: number; name: string }>();
-  const resultsByCall = new Map<
-    string,
-    Array<{ entry: RecordValue; index: number }>
-  >();
-  const state = { latestUserIndex: -1 };
-  for (let index = 0; index < entries.length; index += 1) {
-    const failure = indexEntry(
-      entries[index] as unknown as RecordValue,
-      index,
-      callOwners,
-      resultsByCall,
-      state
-    );
-    if (failure) {
-      return failure;
+const indexAssistantCalls = (
+  message: RecordValue,
+  index: number,
+  callOwners: Map<string, { index: number; name: string }>
+): InvalidProtocolResult | undefined => {
+  for (const call of toolCalls(message)) {
+    const id = toolCallId(call);
+    if (!id || callOwners.has(id)) {
+      return invalid(
+        `Assistant tool calls at context entry ${index} have missing or duplicate IDs.`
+      );
     }
+    callOwners.set(id, {
+      index,
+      name: isString(call.name) ? call.name : "unknown",
+    });
   }
-  for (const [id, results] of resultsByCall) {
-    if (results.length > 1) {
-      return invalid(`Tool call ${id} has duplicate result messages.`);
-    }
+  return undefined;
+};
+
+const indexToolResult = (
+  entry: RecordValue,
+  message: RecordValue,
+  index: number,
+  resultsByCall: Map<string, { entry: RecordValue; index: number }[]>
+): InvalidProtocolResult | undefined => {
+  const id = message.toolCallId;
+  if (!isString(id)) {
+    return invalid(
+      `Tool result at context entry ${index} has no tool-call ID.`
+    );
   }
-  return {
-    index: {
-      callOwners,
-      latestUserIndex: state.latestUserIndex,
-      resultsByCall,
-    },
-    ok: true,
-  };
+  const results = resultsByCall.get(id) ?? [];
+  results.push({ entry, index });
+  resultsByCall.set(id, results);
+  return undefined;
 };
 
 const indexEntry = (
   entry: RecordValue,
   index: number,
   callOwners: Map<string, { index: number; name: string }>,
-  resultsByCall: Map<string, Array<{ entry: RecordValue; index: number }>>,
+  resultsByCall: Map<string, { entry: RecordValue; index: number }[]>,
   state: { latestUserIndex: number }
 ): InvalidProtocolResult | undefined => {
   if (entry.type !== "message" || !isRecord(entry.message)) {
@@ -83,40 +84,43 @@ const indexEntry = (
   return undefined;
 };
 
-const indexToolResult = (
-  entry: RecordValue,
-  message: RecordValue,
-  index: number,
-  resultsByCall: Map<string, Array<{ entry: RecordValue; index: number }>>
-): InvalidProtocolResult | undefined => {
-  const id = message.toolCallId;
-  if (typeof id !== "string") {
-    return invalid(
-      `Tool result at context entry ${index} has no tool-call ID.`
-    );
-  }
-  const results = resultsByCall.get(id) ?? [];
-  results.push({ entry, index });
-  resultsByCall.set(id, results);
-  return undefined;
-};
-
-const indexAssistantCalls = (
-  message: RecordValue,
-  index: number,
-  callOwners: Map<string, { index: number; name: string }>
-): InvalidProtocolResult | undefined => {
-  for (const call of toolCalls(message)) {
-    const id = toolCallId(call);
-    if (!id || callOwners.has(id)) {
-      return invalid(
-        `Assistant tool calls at context entry ${index} have missing or duplicate IDs.`
+/** First entry pass: indexes assistant tool calls and their results, tracking
+ * the latest user message. Returns an invalid result on protocol violations. */
+export const indexToolCalls = (
+  entries: unknown[]
+): { index: ToolCallIndex; ok: true } | InvalidProtocolResult => {
+  const callOwners = new Map<string, { index: number; name: string }>();
+  const resultsByCall = new Map<
+    string,
+    { entry: RecordValue; index: number }[]
+  >();
+  const state = { latestUserIndex: -1 };
+  for (let index = 0; index < entries.length; index += 1) {
+    const entry = entries[index];
+    if (isRecord(entry)) {
+      const failure = indexEntry(
+        entry,
+        index,
+        callOwners,
+        resultsByCall,
+        state
       );
+      if (failure) {
+        return failure;
+      }
     }
-    callOwners.set(id, {
-      index,
-      name: typeof call.name === "string" ? call.name : "unknown",
-    });
   }
-  return undefined;
+  for (const [id, results] of resultsByCall) {
+    if (results.length > 1) {
+      return invalid(`Tool call ${id} has duplicate result messages.`);
+    }
+  }
+  return {
+    index: {
+      callOwners,
+      latestUserIndex: state.latestUserIndex,
+      resultsByCall,
+    },
+    ok: true,
+  };
 };

package/src/scout-reconstruct.ts

@@ -20,7 +20,7 @@ export const reconstructScoutConversation = (
   const selected = new Set(selectedIds);
   const evidence = manifest.groups
     .filter((group) => group.required || selected.has(group.id))
-    .sort((left, right) => left.originalIndex - right.originalIndex)
+    .toSorted((left, right) => left.originalIndex - right.originalIndex)
     .map((group) => group.content);
   const evidenceText = evidence.join("\n\n");
   if (maxChars <= 0) {

package/src/scout.ts

@@ -1,20 +1,25 @@
 import type { Message } from "@earendil-works/pi-ai/compat";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { executorEffortRef, executorRef } from "./config/state.ts";
+
 import {
-  type CollectedTextStream,
-  collectTextStream,
-  type ResolvedConfiguredModel,
-  resolveConfiguredModel,
+  effectiveExecutorEffort,
+  effectiveExecutorRef,
+} from "./child-session.ts";
+import { isRecord, isString } from "./content-utils.ts";
+import { collectTextStream, resolveConfiguredModel } from "./model-stream.ts";
+import type {
+  CollectedTextStream,
+  ResolvedConfiguredModel,
 } from "./model-stream.ts";
 import { groupWire } from "./scout-groups.ts";
 import { reconstructScoutConversation } from "./scout-reconstruct.ts";
 import {
   SCOUT_SELECTION_MAX_IDS,
   SCOUT_SYNTHESIS_MAX_BYTES,
-  type ScoutManifest,
 } from "./scout-types.ts";
+import type { ScoutManifest } from "./scout-types.ts";
 import { snapshotAdvisorUsage } from "./usage.ts";
+import type { AdvisorUsageSnapshot } from "./usage.ts";
 
 const SCOUT_TIMEOUT_MS = 30_000;
 
@@ -48,7 +53,7 @@ interface ScoutMetrics {
   latencyMs: number;
   omittedBeforeScout: number;
   selectedCount: number;
-  usage?: unknown;
+  usage?: AdvisorUsageSnapshot;
 }
 
 export interface ScoutSelection {
@@ -100,8 +105,8 @@ const defaultDependencies: ScoutDependencies = {
   collect: collectTextStream,
   resolve: resolveConfiguredModel,
 };
-const byteLength = (value: string) => Buffer.byteLength(value, "utf8");
-const AUTH_ERROR_PATTERN = /api key|auth|login|credential/i;
+const byteLength = (value: string) => Buffer.byteLength(value, "utf-8");
+const AUTH_ERROR_PATTERN = /api key|auth|login|credential/iu;
 
 const manifestMessage = (manifest: ScoutManifest): Message => ({
   content: [
@@ -120,6 +125,9 @@ const manifestMessage = (manifest: ScoutManifest): Message => ({
   timestamp: Date.now(),
 });
 
+const isStringArray = (value: unknown): value is string[] =>
+  Array.isArray(value) && value.every(isString);
+
 export const parseScoutSelection = (
   text: string,
   manifest: ScoutManifest
@@ -133,11 +141,10 @@ export const parseScoutSelection = (
   } catch (error) {
     throw new Error("Scout response is not a JSON object.", { cause: error });
   }
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
+  if (!isRecord(value)) {
     throw new Error("Scout response must be a JSON object.");
   }
-  const record = value as Record<string, unknown>;
-  const keys = Object.keys(record).sort();
+  const keys = Object.keys(value).toSorted();
   if (
     keys.length !== 2 ||
     keys[0] !== "selectedIds" ||
@@ -147,15 +154,10 @@ export const parseScoutSelection = (
       "Scout response must contain only selectedIds and synthesis."
     );
   }
-  if (
-    !(
-      Array.isArray(record.selectedIds) &&
-      record.selectedIds.every((id) => typeof id === "string")
-    )
-  ) {
+  if (!isStringArray(value.selectedIds)) {
     throw new Error("Scout selectedIds must be an array of strings.");
   }
-  const selectedIds = record.selectedIds as string[];
+  const { selectedIds } = value;
   if (new Set(selectedIds).size !== selectedIds.length) {
     throw new Error("Scout selected duplicate group IDs.");
   }
@@ -177,17 +179,17 @@ export const parseScoutSelection = (
   const normalizedIds = manifest.groups
     .filter((group) => retained.has(group.id))
     .map((group) => group.id);
-  if (typeof record.synthesis !== "string") {
-    throw new Error("Scout synthesis must be a string.");
+  if (!isString(value.synthesis)) {
+    throw new TypeError("Scout synthesis must be a string.");
   }
-  if (byteLength(record.synthesis) > SCOUT_SYNTHESIS_MAX_BYTES) {
+  if (byteLength(value.synthesis) > SCOUT_SYNTHESIS_MAX_BYTES) {
     throw new Error(
       `Scout synthesis exceeds ${SCOUT_SYNTHESIS_MAX_BYTES} UTF-8 bytes.`
     );
   }
   return {
     selectedIds: normalizedIds,
-    synthesis: knownSelectedIds.length > 0 ? record.synthesis : "",
+    synthesis: knownSelectedIds.length > 0 ? value.synthesis : "",
   };
 };
 
@@ -212,6 +214,86 @@ const classifyResolutionError = (message: string): ScoutFallbackCategory => {
   return "provider-error";
 };
 
+const setupAbortWatch = (
+  parentSignal: AbortSignal | undefined,
+  timeoutMs: number
+) => {
+  const controller = new AbortController();
+  let timedOut = false;
+  const abortFromParent = () => controller.abort(parentSignal?.reason);
+  parentSignal?.addEventListener("abort", abortFromParent, { once: true });
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort(new Error("Scout timed out."));
+  }, timeoutMs);
+  timer.unref?.();
+  const { promise: abortPromise, reject: rejectOnAbort } =
+    Promise.withResolvers<never>();
+  const onControllerAbort = () =>
+    rejectOnAbort(controller.signal.reason ?? new Error("Scout aborted."));
+  controller.signal.addEventListener("abort", onControllerAbort, {
+    once: true,
+  });
+  return {
+    abortPromise,
+    controller,
+    teardown: () => {
+      clearTimeout(timer);
+      parentSignal?.removeEventListener("abort", abortFromParent);
+      controller.signal.removeEventListener("abort", onControllerAbort);
+    },
+    wasTimedOut: () => timedOut,
+  };
+};
+
+type ScoutStreamResult =
+  | { ok: true; streamed: CollectedTextStream }
+  | { ok: false; category: ScoutFallbackCategory; message: string };
+
+const streamScoutResponse = async (
+  dependencies: ScoutDependencies,
+  resolved: ResolvedConfiguredModel,
+  executorModel: string,
+  executorEffort: string | undefined,
+  manifest: ScoutManifest,
+  parentSignal: AbortSignal | undefined,
+  timeoutMs: number,
+  publish: (event: ScoutLifecycleEvent) => void
+): Promise<ScoutStreamResult> => {
+  const { abortPromise, controller, teardown, wasTimedOut } = setupAbortWatch(
+    parentSignal,
+    timeoutMs
+  );
+  try {
+    const collection = dependencies.collect(resolved, {
+      messages: [manifestMessage(manifest)],
+      onChunk: (thinking, text) => {
+        if (!controller.signal.aborted) {
+          publish({ model: executorModel, text, thinking, type: "chunk" });
+        }
+      },
+      reasoning: executorEffort,
+      signal: controller.signal,
+      systemPrompt: SCOUT_SYSTEM,
+    });
+    return {
+      ok: true,
+      streamed: await Promise.race([collection, abortPromise]),
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return wasTimedOut()
+      ? {
+          category: "timeout",
+          message: `Scout timed out after ${timeoutMs} ms.`,
+          ok: false,
+        }
+      : { category: "provider-error", message, ok: false };
+  } finally {
+    teardown();
+  }
+};
+
 export const runAdvisorScout = async (
   ctx: ExtensionContext,
   manifest: ScoutManifest,
@@ -231,7 +313,7 @@ export const runAdvisorScout = async (
   const fallback = (
     category: ScoutFallbackCategory,
     message: string,
-    usage?: unknown
+    usage?: AdvisorUsageSnapshot
   ): ScoutOutcome => {
     const outcome = {
       category,
@@ -240,7 +322,7 @@ export const runAdvisorScout = async (
         usage === undefined
           ? baseMetrics(manifest, startedAt)
           : { ...baseMetrics(manifest, startedAt), usage },
-      model: executorRef,
+      model: effectiveExecutorRef(ctx),
       ok: false as const,
     };
     publish({ outcome, type: "fallback" });
@@ -251,9 +333,11 @@ export const runAdvisorScout = async (
     return cancelled();
   }
 
+  const executorModel = effectiveExecutorRef(ctx);
+  const executorEffort = effectiveExecutorEffort(ctx);
   let resolved: ResolvedConfiguredModel;
   try {
-    resolved = await dependencies.resolve(ctx, executorRef, "Scout");
+    resolved = await dependencies.resolve(ctx, executorModel, "Scout");
   } catch (error) {
     if (parentSignal?.aborted) {
       return cancelled();
@@ -265,70 +349,37 @@ export const runAdvisorScout = async (
   if (parentSignal?.aborted) {
     return cancelled();
   }
-  publish({ model: executorRef, type: "call" });
-  const controller = new AbortController();
-  let timedOut = false;
-  const abortFromParent = () => controller.abort(parentSignal?.reason);
-  parentSignal?.addEventListener("abort", abortFromParent, { once: true });
-  const timer = setTimeout(() => {
-    timedOut = true;
-    controller.abort(new Error("Scout timed out."));
-  }, timeoutMs);
-  timer.unref?.();
+  publish({ model: executorModel, type: "call" });
 
-  let rejectOnAbort: ((reason?: unknown) => void) | undefined;
-  const onControllerAbort = () =>
-    rejectOnAbort?.(controller.signal.reason ?? new Error("Scout aborted."));
-  const abortPromise = new Promise<never>((_resolve, reject) => {
-    rejectOnAbort = reject;
-    controller.signal.addEventListener("abort", onControllerAbort, {
-      once: true,
-    });
-  });
-  const teardown = () => {
-    clearTimeout(timer);
-    parentSignal?.removeEventListener("abort", abortFromParent);
-    controller.signal.removeEventListener("abort", onControllerAbort);
-  };
-
-  let streamed: CollectedTextStream;
-  try {
-    const collection = dependencies.collect(resolved, {
-      messages: [manifestMessage(manifest)],
-      onChunk: (thinking, text) => {
-        if (!controller.signal.aborted) {
-          publish({ model: executorRef, text, thinking, type: "chunk" });
-        }
-      },
-      reasoning: executorEffortRef,
-      signal: controller.signal,
-      systemPrompt: SCOUT_SYSTEM,
-    });
-    streamed = await Promise.race([collection, abortPromise]);
-  } catch (error) {
-    teardown();
+  const streamed = await streamScoutResponse(
+    dependencies,
+    resolved,
+    executorModel,
+    executorEffort,
+    manifest,
+    parentSignal,
+    timeoutMs,
+    publish
+  );
+  if (!streamed.ok) {
     if (parentSignal?.aborted) {
       return cancelled();
     }
-    const message = error instanceof Error ? error.message : String(error);
-    return timedOut
-      ? fallback("timeout", `Scout timed out after ${timeoutMs} ms.`)
-      : fallback("provider-error", message);
+    return fallback(streamed.category, streamed.message);
   }
-  teardown();
   if (parentSignal?.aborted) {
     return cancelled();
   }
 
   let selection: ScoutSelection;
   try {
-    selection = parseScoutSelection(streamed.text, manifest);
+    selection = parseScoutSelection(streamed.streamed.text, manifest);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     return fallback(
-      streamed.text.trim() ? "invalid-selection" : "empty-response",
+      streamed.streamed.text.trim() ? "invalid-selection" : "empty-response",
       message,
-      snapshotAdvisorUsage(streamed.usage)
+      snapshotAdvisorUsage(streamed.streamed.usage)
     );
   }
 
@@ -346,9 +397,9 @@ export const runAdvisorScout = async (
           .filter((group) => group.required)
           .map((group) => group.id),
       ]).size,
-      usage: snapshotAdvisorUsage(streamed.usage),
+      usage: snapshotAdvisorUsage(streamed.streamed.usage),
     },
-    model: executorRef,
+    model: executorModel,
     ok: true as const,
     selectedLabels: manifest.groups
       .filter(