pi-advisor-flow 0.5.6 → 0.7.0

package/src/scout-reconstruct.ts

@@ -0,0 +1,44 @@
+import type { ScoutManifest } from "./scout-types.ts";
+
+const prefixWithinCharBudget = (value: string, maxChars: number) => {
+  let result = "";
+  for (const character of value) {
+    if (result.length + character.length > maxChars) {
+      break;
+    }
+    result += character;
+  }
+  return result;
+};
+
+export const reconstructScoutConversation = (
+  manifest: ScoutManifest,
+  selectedIds: string[],
+  synthesis?: string,
+  maxChars = Number.MAX_SAFE_INTEGER
+): string => {
+  const selected = new Set(selectedIds);
+  const evidence = manifest.groups
+    .filter((group) => group.required || selected.has(group.id))
+    .sort((left, right) => left.originalIndex - right.originalIndex)
+    .map((group) => group.content);
+  const evidenceText = evidence.join("\n\n");
+  if (maxChars <= 0) {
+    return "";
+  }
+  if (evidenceText.length >= maxChars) {
+    return prefixWithinCharBudget(evidenceText, maxChars);
+  }
+  const inference = synthesis?.trim()
+    ? `[Scout synthesis — untrusted, non-authoritative inference; not evidence]\n${synthesis.trim()}`
+    : undefined;
+  if (!inference) {
+    return evidenceText;
+  }
+  const separator = evidenceText ? "\n\n" : "";
+  const remaining = maxChars - evidenceText.length - separator.length;
+  if (remaining <= 0) {
+    return evidenceText;
+  }
+  return `${evidenceText}${separator}${prefixWithinCharBudget(inference, remaining)}`;
+};

package/src/scout-types.ts

@@ -0,0 +1,66 @@
+/** Shared Scout manifest types and transport limits. */
+
+import type { AdvisorToolPolicies } from "./config/types.ts";
+
+export const SCOUT_MANIFEST_MAX_BYTES = 64 * 1024;
+export const SCOUT_MANIFEST_MAX_GROUPS = 64;
+export const SCOUT_GROUP_MAX_BYTES = 24 * 1024;
+export const SCOUT_LABEL_MAX_CHARS = 160;
+export const SCOUT_SELECTION_MAX_IDS = 32;
+export const SCOUT_SYNTHESIS_MAX_BYTES = 4 * 1024;
+
+export type ScoutGroupKind =
+  | "compaction"
+  | "user"
+  | "assistant"
+  | "tool-exchange"
+  | "pending-invocation";
+
+export interface ScoutContextGroup {
+  bytes: number;
+  content: string;
+  id: string;
+  kind: ScoutGroupKind;
+  label: string;
+  originalIndex: number;
+  required: boolean;
+}
+
+export interface ScoutManifest {
+  availableBytes: number;
+  availableCount: number;
+  groups: ScoutContextGroup[];
+  omittedBytes: number;
+  omittedCount: number;
+}
+
+export type ScoutManifestResult =
+  | { ok: true; manifest: ScoutManifest }
+  | {
+      ok: false;
+      reason: "invalid-protocol" | "required-group-overflow";
+      message: string;
+    };
+
+/** The invalid-protocol failure shape produced by protocol passes. */
+export interface InvalidProtocolResult {
+  message: string;
+  ok: false;
+  reason: "invalid-protocol";
+}
+
+export interface BuildScoutManifestOptions {
+  currentInvocationId?: string;
+  /** @deprecated Use maxManifestBytes for the Scout transport budget. */
+  maxBytes?: number;
+  /** Maximum reconstructed Advisor conversation characters. */
+  maxConversationChars?: number;
+  maxGroupBytes?: number;
+  maxGroups?: number;
+  /** Maximum serialized group-manifest bytes sent to Scout. */
+  maxManifestBytes?: number;
+  policies?: AdvisorToolPolicies;
+  redact?: boolean;
+  toolResultMaxBytes?: number;
+  toolResultMaxLines?: number;
+}

package/src/scout.ts

@@ -1,21 +1,22 @@
 import type { Message } from "@earendil-works/pi-ai/compat";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { executorEffortRef, executorRef } from "./config/state.js";
+import { executorEffortRef, executorRef } from "./config/state.ts";
 import {
   type CollectedTextStream,
   collectTextStream,
   type ResolvedConfiguredModel,
   resolveConfiguredModel,
-} from "./model-stream.js";
+} from "./model-stream.ts";
+import { groupWire } from "./scout-groups.ts";
+import { reconstructScoutConversation } from "./scout-reconstruct.ts";
 import {
-  reconstructScoutConversation,
   SCOUT_SELECTION_MAX_IDS,
   SCOUT_SYNTHESIS_MAX_BYTES,
   type ScoutManifest,
-} from "./scout-context.js";
-import { snapshotAdvisorUsage } from "./usage.js";
+} from "./scout-types.ts";
+import { snapshotAdvisorUsage } from "./usage.ts";
 
-export const SCOUT_TIMEOUT_MS = 30_000;
+const SCOUT_TIMEOUT_MS = 30_000;
 
 export const SCOUT_SYSTEM = [
   "You are Scout, a context curator serving a separate engineering Advisor.",
@@ -30,7 +31,7 @@ export const SCOUT_SYSTEM = [
   "Do not use Markdown fences or add any other keys or prose.",
 ].join(" ");
 
-export type ScoutFallbackCategory =
+type ScoutFallbackCategory =
   | "required-group-overflow"
   | "invalid-protocol"
   | "missing-model"
@@ -41,7 +42,7 @@ export type ScoutFallbackCategory =
   | "invalid-selection"
   | "timeout";
 
-export interface ScoutMetrics {
+interface ScoutMetrics {
   availableCount: number;
   inputBytes: number;
   latencyMs: number;
@@ -106,14 +107,7 @@ const manifestMessage = (manifest: ScoutManifest): Message => ({
   content: [
     {
       text: JSON.stringify({
-        groups: manifest.groups.map((group) => ({
-          bytes: group.bytes,
-          content: group.content,
-          id: group.id,
-          kind: group.kind,
-          label: group.label,
-          required: group.required,
-        })),
+        groups: manifest.groups.map(groupWire),
         omittedBeforeScout: {
           bytes: manifest.omittedBytes,
           groups: manifest.omittedCount,
@@ -225,15 +219,36 @@ export const runAdvisorScout = async (
   onEvent?: (event: ScoutLifecycleEvent) => void,
   timeoutMs = SCOUT_TIMEOUT_MS,
   dependencies: ScoutDependencies = defaultDependencies
-  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: cancellation, timeout, provider, and schema outcomes remain explicitly distinct.
 ): Promise<ScoutOutcome> => {
   const startedAt = Date.now();
   const publish = (event: ScoutLifecycleEvent) => {
     onEvent?.(event);
   };
-  if (parentSignal?.aborted) {
+  const cancelled = (): ScoutOutcome => {
     publish({ type: "cancelled" });
     return { cancelled: true, ok: false };
+  };
+  const fallback = (
+    category: ScoutFallbackCategory,
+    message: string,
+    usage?: unknown
+  ): ScoutOutcome => {
+    const outcome = {
+      category,
+      message,
+      metrics:
+        usage === undefined
+          ? baseMetrics(manifest, startedAt)
+          : { ...baseMetrics(manifest, startedAt), usage },
+      model: executorRef,
+      ok: false as const,
+    };
+    publish({ outcome, type: "fallback" });
+    return outcome;
+  };
+
+  if (parentSignal?.aborted) {
+    return cancelled();
   }
 
   let resolved: ResolvedConfiguredModel;
@@ -241,24 +256,14 @@ export const runAdvisorScout = async (
     resolved = await dependencies.resolve(ctx, executorRef, "Scout");
   } catch (error) {
     if (parentSignal?.aborted) {
-      publish({ type: "cancelled" });
-      return { cancelled: true, ok: false };
+      return cancelled();
     }
     const message = error instanceof Error ? error.message : String(error);
-    const outcome = {
-      category: classifyResolutionError(message),
-      message,
-      metrics: baseMetrics(manifest, startedAt),
-      model: executorRef,
-      ok: false as const,
-    };
-    publish({ outcome, type: "fallback" });
-    return outcome;
+    return fallback(classifyResolutionError(message), message);
   }
 
   if (parentSignal?.aborted) {
-    publish({ type: "cancelled" });
-    return { cancelled: true, ok: false };
+    return cancelled();
   }
   publish({ model: executorRef, type: "call" });
   const controller = new AbortController();
@@ -280,6 +285,12 @@ export const runAdvisorScout = async (
       once: true,
     });
   });
+  const teardown = () => {
+    clearTimeout(timer);
+    parentSignal?.removeEventListener("abort", abortFromParent);
+    controller.signal.removeEventListener("abort", onControllerAbort);
+  };
+
   let streamed: CollectedTextStream;
   try {
     const collection = dependencies.collect(resolved, {
@@ -295,30 +306,18 @@ export const runAdvisorScout = async (
     });
     streamed = await Promise.race([collection, abortPromise]);
   } catch (error) {
-    clearTimeout(timer);
-    parentSignal?.removeEventListener("abort", abortFromParent);
-    controller.signal.removeEventListener("abort", onControllerAbort);
+    teardown();
     if (parentSignal?.aborted) {
-      publish({ type: "cancelled" });
-      return { cancelled: true, ok: false };
+      return cancelled();
     }
     const message = error instanceof Error ? error.message : String(error);
-    const outcome = {
-      category: timedOut ? ("timeout" as const) : ("provider-error" as const),
-      message: timedOut ? `Scout timed out after ${timeoutMs} ms.` : message,
-      metrics: baseMetrics(manifest, startedAt),
-      model: executorRef,
-      ok: false as const,
-    };
-    publish({ outcome, type: "fallback" });
-    return outcome;
+    return timedOut
+      ? fallback("timeout", `Scout timed out after ${timeoutMs} ms.`)
+      : fallback("provider-error", message);
   }
-  clearTimeout(timer);
-  parentSignal?.removeEventListener("abort", abortFromParent);
-  controller.signal.removeEventListener("abort", onControllerAbort);
+  teardown();
   if (parentSignal?.aborted) {
-    publish({ type: "cancelled" });
-    return { cancelled: true, ok: false };
+    return cancelled();
   }
 
   let selection: ScoutSelection;
@@ -326,20 +325,11 @@ export const runAdvisorScout = async (
     selection = parseScoutSelection(streamed.text, manifest);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    const outcome = {
-      category: streamed.text.trim()
-        ? ("invalid-selection" as const)
-        : ("empty-response" as const),
+    return fallback(
+      streamed.text.trim() ? "invalid-selection" : "empty-response",
       message,
-      metrics: {
-        ...baseMetrics(manifest, startedAt),
-        usage: snapshotAdvisorUsage(streamed.usage),
-      },
-      model: executorRef,
-      ok: false as const,
-    };
-    publish({ outcome, type: "fallback" });
-    return outcome;
+      snapshotAdvisorUsage(streamed.usage)
+    );
   }
 
   const outcome = {