pi-advisor-flow 0.6.0 → 0.8.0

package/src/scout-groups.ts

@@ -1,18 +1,20 @@
 import { createHash } from "node:crypto";
+
 import type { AdvisorToolPolicies } from "./config/types.ts";
 import {
   byteLength,
   contentParts,
   isRecord,
-  type RecordValue,
+  isString,
 } from "./content-utils.ts";
+import type { RecordValue } from "./content-utils.ts";
 import { conversationEntry } from "./conversation.ts";
 import { invalid, toolCallId, toolCalls } from "./scout-protocol.ts";
-import {
-  type InvalidProtocolResult,
-  SCOUT_LABEL_MAX_CHARS,
-  type ScoutContextGroup,
-  type ScoutGroupKind,
+import { SCOUT_LABEL_MAX_CHARS } from "./scout-types.ts";
+import type {
+  InvalidProtocolResult,
+  ScoutContextGroup,
+  ScoutGroupKind,
 } from "./scout-types.ts";
 
 export interface GroupPass {
@@ -22,10 +24,10 @@ export interface GroupPass {
   protocolOmittedCount: number;
 }
 
-const SPEAKER_PREFIX = /^(User|Executor):\s*/;
+const SPEAKER_PREFIX = /^(?<speaker>User|Executor):\s*/u;
 
 const boundedLabel = (value: string) =>
-  [...value.replace(/\s+/g, " ").trim()]
+  [...value.replaceAll(/\s+/gu, " ").trim()]
     .slice(0, SCOUT_LABEL_MAX_CHARS)
     .join("");
 
@@ -81,10 +83,8 @@ const createGroup = (
   required,
 });
 
-const pendingAdvisorArguments = (value: unknown): RecordValue => {
-  if (!isRecord(value)) {
-    return {};
-  }
+const pendingAdvisorArguments = (part: RecordValue): RecordValue => {
+  const value = isRecord(part.arguments) ? part.arguments : {};
   const allowed: RecordValue = {};
   for (const key of ["gitContext", "question"]) {
     if (key in value) {
@@ -106,7 +106,8 @@ const pendingInvocationDisclosure = (
   if (!isRecord(entry.message)) {
     return disclosed;
   }
-  const content = contentParts(entry.message.content).map((part) => {
+  const message: RecordValue = entry.message;
+  const content = contentParts(message.content).map((part) => {
     if (
       !isRecord(part) ||
       part.type !== "toolCall" ||
@@ -115,10 +116,10 @@ const pendingInvocationDisclosure = (
     ) {
       return part;
     }
-    return { ...part, arguments: pendingAdvisorArguments(part.arguments) };
+    return { ...part, arguments: pendingAdvisorArguments(part) };
   });
   return conversationEntry(
-    { ...entry, message: { ...entry.message, content } },
+    { ...entry, message: { ...message, content } },
     toolResultMaxLines,
     toolResultMaxBytes,
     policies,
@@ -139,88 +140,19 @@ type ToolExchangeOutcome =
   | { kind: "omitted"; bytes: number }
   | { kind: "invalid"; message: string };
 
-/** Groups an assistant message with its tool calls and matched results into
- * one indivisible tool-exchange (or pending-invocation) group. */
-const toolExchangeGroup = (
-  entry: RecordValue,
-  index: number,
-  entryId: string,
-  disclosed: string,
-  immediate: unknown,
-  indexed: {
-    callOwners: Map<string, { index: number; name: string }>;
-    resultsByCall: Map<string, Array<{ entry: RecordValue; index: number }>>;
-  },
-  consumedResultIndexes: Set<number>,
-  caps: DisclosureCaps
-): ToolExchangeOutcome => {
-  const calls = toolCalls(entry.message as RecordValue);
-  const callIds = calls.map(toolCallId) as string[];
-  const adjacentFailure = adjacentResultMismatch(
-    immediate,
-    index,
-    callIds,
-    indexed.callOwners
-  );
-  if (adjacentFailure) {
-    return { kind: "invalid", message: adjacentFailure };
-  }
-  const missing = new Set<string>();
-  const resultParts: string[] = [];
-  const resultEntryIds: string[] = [];
-  const matchFailure = collectResults(
-    calls,
-    callIds,
-    index,
-    indexed.resultsByCall,
-    consumedResultIndexes,
-    caps,
-    missing,
-    resultParts,
-    resultEntryIds
-  );
-  if (matchFailure) {
-    return { kind: "invalid", message: matchFailure };
-  }
-  if (missing.size > 0) {
-    return missingOutcome(
-      entry,
-      index,
-      entryId,
-      disclosed,
-      callIds,
-      missing,
-      resultParts,
-      resultEntryIds,
-      caps
-    );
-  }
-  return {
-    group: createGroup(
-      index,
-      [entryId, ...resultEntryIds],
-      "tool-exchange",
-      [disclosed, ...resultParts].join("\n\n"),
-      false
-    ),
-    kind: "group",
-  };
-};
-
 const adjacentResultMismatch = (
-  immediate: unknown,
+  immediate: RecordValue | undefined,
   index: number,
   callIds: string[],
   callOwners: Map<string, { index: number; name: string }>
 ): string | undefined => {
-  const next = immediate as RecordValue | undefined;
   if (
-    next?.type === "message" &&
-    isRecord(next.message) &&
-    next.message.role === "toolResult" &&
-    typeof next.message.toolCallId === "string" &&
-    !callIds.includes(next.message.toolCallId) &&
-    !callOwners.has(next.message.toolCallId)
+    immediate?.type === "message" &&
+    isRecord(immediate.message) &&
+    immediate.message.role === "toolResult" &&
+    isString(immediate.message.toolCallId) &&
+    !callIds.includes(immediate.message.toolCallId) &&
+    !callOwners.has(immediate.message.toolCallId)
   ) {
     return `Tool result at context entry ${index + 1} does not match its adjacent assistant group.`;
   }
@@ -231,7 +163,7 @@ const collectResults = (
   calls: RecordValue[],
   callIds: string[],
   index: number,
-  resultsByCall: Map<string, Array<{ entry: RecordValue; index: number }>>,
+  resultsByCall: Map<string, { entry: RecordValue; index: number }[]>,
   consumedResultIndexes: Set<number>,
   caps: DisclosureCaps,
   missing: Set<string>,
@@ -248,10 +180,8 @@ const collectResults = (
       return `Tool result at context entry ${resultMatch.index} precedes its assistant call.`;
     }
     const resultMessage = resultMatch.entry.message;
-    const expectedName =
-      typeof calls[callIndex].name === "string"
-        ? calls[callIndex].name
-        : "unknown";
+    const call = calls[callIndex];
+    const expectedName = isString(call.name) ? call.name : "unknown";
     if (!isRecord(resultMessage) || resultMessage.toolName !== expectedName) {
       return `Tool result at context entry ${resultMatch.index} conflicts with call ${callId}.`;
     }
@@ -267,7 +197,7 @@ const collectResults = (
       resultParts.push(resultText);
     }
     resultEntryIds.push(
-      typeof resultMatch.entry.id === "string"
+      isString(resultMatch.entry.id)
         ? resultMatch.entry.id
         : String(resultMatch.index)
     );
@@ -319,82 +249,130 @@ const missingOutcome = (
   };
 };
 
-/** Second entry pass: groups each disclosed entry, delegating
- * assistant-with-calls entries to the tool-exchange builder. */
-export const buildGroups = (
-  entries: unknown[],
+/** Groups an assistant message with its tool calls and matched results into
+ * one indivisible tool-exchange (or pending-invocation) group. */
+const toolExchangeGroup = (
+  entry: RecordValue,
+  message: RecordValue,
+  index: number,
+  entryId: string,
+  disclosed: string,
+  immediate: RecordValue | undefined,
   indexed: {
     callOwners: Map<string, { index: number; name: string }>;
-    latestUserIndex: number;
-    resultsByCall: Map<string, Array<{ entry: RecordValue; index: number }>>;
+    resultsByCall: Map<string, { entry: RecordValue; index: number }[]>;
   },
-  caps: DisclosureCaps & {
-    maxGroupBytes: number;
+  consumedResultIndexes: Set<number>,
+  caps: DisclosureCaps
+): ToolExchangeOutcome => {
+  const calls = toolCalls(message);
+  const callIds = calls.map(toolCallId).filter(isString);
+  const adjacentFailure = adjacentResultMismatch(
+    immediate,
+    index,
+    callIds,
+    indexed.callOwners
+  );
+  if (adjacentFailure) {
+    return { kind: "invalid", message: adjacentFailure };
   }
-): GroupPass | InvalidProtocolResult => {
-  const groups: ScoutContextGroup[] = [];
-  const consumedResultIndexes = new Set<number>();
-  let protocolOmittedBytes = 0;
-  let protocolOmittedCount = 0;
-  for (let index = 0; index < entries.length; index += 1) {
-    const entry = entries[index] as unknown as RecordValue;
-    const disclosed = conversationEntry(
-      entry,
-      caps.toolResultMaxLines,
-      caps.toolResultMaxBytes,
-      caps.policies,
-      caps.redact
-    );
-    if (!disclosed) {
-      continue;
-    }
-    const outcome = groupForEntry(
+  const missing = new Set<string>();
+  const resultParts: string[] = [];
+  const resultEntryIds: string[] = [];
+  const matchFailure = collectResults(
+    calls,
+    callIds,
+    index,
+    indexed.resultsByCall,
+    consumedResultIndexes,
+    caps,
+    missing,
+    resultParts,
+    resultEntryIds
+  );
+  if (matchFailure) {
+    return { kind: "invalid", message: matchFailure };
+  }
+  if (missing.size > 0) {
+    return missingOutcome(
       entry,
       index,
+      entryId,
       disclosed,
-      entries[index + 1],
-      indexed,
-      consumedResultIndexes,
+      callIds,
+      missing,
+      resultParts,
+      resultEntryIds,
       caps
     );
-    if (outcome.kind === "invalid") {
-      return invalid(outcome.message);
-    }
-    if (outcome.kind === "omitted") {
-      protocolOmittedCount += 1;
-      protocolOmittedBytes += outcome.bytes;
-    } else if (outcome.kind === "group") {
-      groups.push(outcome.group);
-    }
   }
   return {
-    groups,
-    ok: true,
-    protocolOmittedBytes,
-    protocolOmittedCount,
+    group: createGroup(
+      index,
+      [entryId, ...resultEntryIds],
+      "tool-exchange",
+      [disclosed, ...resultParts].join("\n\n"),
+      false
+    ),
+    kind: "group",
   };
 };
 
+const ownerOf = (
+  message: RecordValue,
+  callOwners: Map<string, { index: number; name: string }>
+) =>
+  isString(message.toolCallId) ? callOwners.get(message.toolCallId) : undefined;
+
+const contentPartsOf = (message: RecordValue) =>
+  Array.isArray(message.content) ? message.content : [];
+
+const hasCalls = (message: RecordValue) =>
+  contentPartsOf(message).some(
+    (part) => isRecord(part) && part.type === "toolCall"
+  );
+
 type EntryOutcome =
   | { kind: "group"; group: ScoutContextGroup }
   | { kind: "omitted"; bytes: number }
   | { kind: "invalid"; message: string }
   | { kind: "skipped" };
 
+const toolResultOutcome = (
+  message: RecordValue,
+  index: number,
+  disclosed: string,
+  callOwners: Map<string, { index: number; name: string }>,
+  consumedResultIndexes: Set<number>
+): EntryOutcome => {
+  if (consumedResultIndexes.has(index)) {
+    return { kind: "skipped" };
+  }
+  if (ownerOf(message, callOwners)) {
+    return {
+      kind: "invalid",
+      message: `Tool result at context entry ${index} precedes or conflicts with its retained call.`,
+    };
+  }
+  // Retained results without their call are unavailable optional evidence
+  // and are never offered to Scout.
+  return { bytes: byteLength(disclosed), kind: "omitted" };
+};
+
 const groupForEntry = (
   entry: RecordValue,
   index: number,
   disclosed: string,
-  immediate: unknown,
+  immediate: RecordValue | undefined,
   indexed: {
     callOwners: Map<string, { index: number; name: string }>;
     latestUserIndex: number;
-    resultsByCall: Map<string, Array<{ entry: RecordValue; index: number }>>;
+    resultsByCall: Map<string, { entry: RecordValue; index: number }[]>;
   },
   consumedResultIndexes: Set<number>,
   caps: DisclosureCaps
 ): EntryOutcome => {
-  const entryId = typeof entry.id === "string" ? entry.id : String(index);
+  const entryId = isString(entry.id) ? entry.id : String(index);
   if (entry.type !== "message" || !isRecord(entry.message)) {
     return {
       group: createGroup(index, [entryId], "compaction", disclosed, false),
@@ -434,6 +412,7 @@ const groupForEntry = (
   }
   return toolExchangeGroup(
     entry,
+    message,
     index,
     entryId,
     disclosed,
@@ -444,42 +423,66 @@ const groupForEntry = (
   );
 };
 
-const toolResultOutcome = (
-  message: RecordValue,
-  index: number,
-  disclosed: string,
-  callOwners: Map<string, { index: number; name: string }>,
-  consumedResultIndexes: Set<number>
-): EntryOutcome => {
-  if (consumedResultIndexes.has(index)) {
-    return { kind: "skipped" };
+/** Second entry pass: groups each disclosed entry, delegating
+ * assistant-with-calls entries to the tool-exchange builder. */
+export const buildGroups = (
+  entries: unknown[],
+  indexed: {
+    callOwners: Map<string, { index: number; name: string }>;
+    latestUserIndex: number;
+    resultsByCall: Map<string, { entry: RecordValue; index: number }[]>;
+  },
+  caps: DisclosureCaps & {
+    maxGroupBytes: number;
   }
-  if (ownerOf(message, callOwners)) {
-    return {
-      kind: "invalid",
-      message: `Tool result at context entry ${index} precedes or conflicts with its retained call.`,
-    };
+): GroupPass | InvalidProtocolResult => {
+  const groups: ScoutContextGroup[] = [];
+  const consumedResultIndexes = new Set<number>();
+  let protocolOmittedBytes = 0;
+  let protocolOmittedCount = 0;
+  for (let index = 0; index < entries.length; index += 1) {
+    const entry = entries[index];
+    if (!isRecord(entry)) {
+      continue;
+    }
+    const disclosed = conversationEntry(
+      entry,
+      caps.toolResultMaxLines,
+      caps.toolResultMaxBytes,
+      caps.policies,
+      caps.redact
+    );
+    if (!disclosed) {
+      continue;
+    }
+    const next = entries[index + 1];
+    const immediate = isRecord(next) ? next : undefined;
+    const outcome = groupForEntry(
+      entry,
+      index,
+      disclosed,
+      immediate,
+      indexed,
+      consumedResultIndexes,
+      caps
+    );
+    if (outcome.kind === "invalid") {
+      return invalid(outcome.message);
+    }
+    if (outcome.kind === "omitted") {
+      protocolOmittedCount += 1;
+      protocolOmittedBytes += outcome.bytes;
+    } else if (outcome.kind === "group") {
+      groups.push(outcome.group);
+    }
   }
-  // Retained results without their call are unavailable optional evidence
-  // and are never offered to Scout.
-  return { bytes: byteLength(disclosed), kind: "omitted" };
+  return {
+    groups,
+    ok: true,
+    protocolOmittedBytes,
+    protocolOmittedCount,
+  };
 };
 
-const ownerOf = (
-  message: RecordValue,
-  callOwners: Map<string, { index: number; name: string }>
-) =>
-  typeof message.toolCallId === "string"
-    ? callOwners.get(message.toolCallId)
-    : undefined;
-
-const hasCalls = (message: RecordValue) =>
-  contentPartsOf(message).some(
-    (part) => isRecord(part) && part.type === "toolCall"
-  );
-
-const contentPartsOf = (message: RecordValue) =>
-  Array.isArray(message.content) ? message.content : [];
-
 /** Final pass: selects groups within the transport and conversation budgets,
  * keeping every required group. */

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) {