pi-maestro-teammate 2.8.1 → 2.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-maestro-teammate",
-  "version": "2.8.1",
+  "version": "2.9.0",
   "description": "Pi extension — teammate agent dispatch with DAG task graphs, RPC messaging, and compact TUI",
   "type": "module",
   "engines": {
@@ -177,7 +177,7 @@
   },
   "files": [
     "bin/*.mjs",
-    "src/**/*.{ts,json}",
+    "src/**/*.{ts,mjs,json}",
     "types/**/*.d.ts",
     "agents/",
     "README.md"

package/src/extension/teammate-helpers.ts

@@ -2148,7 +2148,8 @@ export async function handleChildInteractionRequest(
       const details = isRecord(response.details) ? response.details : {};
       result = response.isError || details.cancelled || !Array.isArray(details.answers)
         ? { action: "cancel", error: response.isError ? "Root question broker failed" : undefined }
-        : { action: "answer", answers: details.answers, ...(Array.isArray(details.decisions) ? { decisions: details.decisions } : {}) };
+        : { action: "answer", answers: details.answers, ...(Array.isArray(details.decisions) ? { decisions: details.decisions } : {}),
+          ...(Array.isArray(details.recommendations) ? { recommendations: details.recommendations } : {}) };
     } else if (!ctx?.hasUI) {
       decisionSource = "headless";
       result = interaction === "permission" ? { action: "deny" } : { action: "cancel" };

package/src/runs/execution-infra.ts

@@ -868,27 +868,50 @@ export function appendBoundedTranscriptMessage(
 
 export function createUtf8LineDecoder(
   maxBufferedBytes = EXECUTION_BUFFER_LIMITS.lineBytes,
+  onOverflow?: (info: { receivedBytes: number; maxBytes: number; prefix: string }) => void,
+  onLine?: (line: string) => void,
 ): Utf8LineDecoder {
   const decoder = new StringDecoder("utf8");
   let buffered = "";
+  let receivedBytes = 0;
+  let prefix = "";
+  let overflowReported = false;
+  const append = (text: string): void => {
+    receivedBytes += Buffer.byteLength(text);
+    if (Buffer.byteLength(prefix) < 256) prefix = truncateUtf8Head(prefix + text.slice(0, 256), 256);
+    buffered = appendUtf8Tail(buffered, text, maxBufferedBytes);
+    if (!overflowReported && receivedBytes > maxBufferedBytes) {
+      overflowReported = true;
+      onOverflow?.({ receivedBytes, maxBytes: maxBufferedBytes, prefix });
+    }
+  };
+  const emit = (lines: string[]): void => {
+    const line = buffered.endsWith("\r") ? buffered.slice(0, -1) : buffered;
+    if (onLine) onLine(line);
+    else lines.push(line);
+    buffered = "";
+    receivedBytes = 0;
+    prefix = "";
+    overflowReported = false;
+  };
   return {
     write(chunk: Buffer): string[] {
       const text = decoder.write(chunk);
       const lines: string[] = [];
       let start = 0;
       for (let newline = text.indexOf("\n"); newline !== -1; newline = text.indexOf("\n", start)) {
-        const line = appendUtf8Tail(buffered, text.slice(start, newline), maxBufferedBytes);
-        lines.push(line.endsWith("\r") ? line.slice(0, -1) : line);
-        buffered = "";
+        append(text.slice(start, newline));
+        emit(lines);
         start = newline + 1;
       }
-      buffered = appendUtf8Tail(buffered, text.slice(start), maxBufferedBytes);
+      append(text.slice(start));
       return lines;
     },
     end(): string[] {
-      const tail = appendUtf8Tail(buffered, decoder.end(), maxBufferedBytes);
-      buffered = "";
-      return tail ? [tail.endsWith("\r") ? tail.slice(0, -1) : tail] : [];
+      append(decoder.end());
+      const lines: string[] = [];
+      if (buffered) emit(lines);
+      return lines;
     },
   };
 }

package/src/runs/pi-subprocess-attempt.ts

@@ -106,6 +106,7 @@ import {
   releasePublishedTurnHistory,
   resetUsage,
   setUsageSnapshot,
+  truncateUtf8Head,
   truncateUtf8Tail,
   writeSchemaFile,
   writeSystemPromptFile,
@@ -875,6 +876,10 @@ export async function runSingleAttempt(
     forkSessionFile,
     params.fast ?? agentConfig.fast,
   );
+  const projectionImport = `--import=${new URL("./rpc-stdout-projection.mjs", import.meta.url).href}`;
+  if (!spawnEnv.NODE_OPTIONS?.split(/\s+/).includes(projectionImport)) {
+    spawnEnv.NODE_OPTIONS = [spawnEnv.NODE_OPTIONS, projectionImport].filter(Boolean).join(" ");
+  }
   const spawnSpec = getPiSpawnCommand(piArgs);
   const probedChildVersion = options.spawnChildProcess
     ? options.childPiVersion
@@ -1141,8 +1146,17 @@ export async function runSingleAttempt(
     // Parse JSON lines from stdout. Pi's agent_end event can repeat the full
     // message history even without structured output, so framing must allow the
     // bounded transcript plus JSON escaping and event metadata in every lane.
-    const stdoutLines = createUtf8LineDecoder(EXECUTION_BUFFER_LIMITS.transcriptBytes * 4);
+    const failStdoutProtocol = (reason: string): void => {
+      if (state.terminal) return;
+      state.receivedFirstActivity = true;
+      state.stdoutProtocolViolation = true;
+      addReplayEvidence("stdout-protocol", reason);
+      state.runtimeFailure = `Teammate stdout JSONL protocol violation (agent=${params.agent}, correlationId=${correlationId}): ${reason}`;
+      appendBoundedTranscriptMessage(messages, { role: "system", content: state.runtimeFailure });
+      completeTurn(undefined, true, 1, "failed");
+    };
     const processStdoutLine = (line: string) => {
+      if (state.terminal) return;
       const trimmed = line.trim();
       if (!trimmed) {
         state.receivedFirstActivity = true;
@@ -1150,24 +1164,34 @@ export async function runSingleAttempt(
         if (timers.firstActivity) clearTimeout(timers.firstActivity);
         return;
       }
+      let event: JsonLineEvent;
+      try {
+        event = JSON.parse(trimmed) as JsonLineEvent;
+      } catch (error) {
+        failStdoutProtocol(`malformed JSON, receivedBytes=${Buffer.byteLength(line)}: ${error instanceof Error ? truncateUtf8Head(error.message, 256) : String(error)}`);
+        return;
+      }
+      if (!event || typeof event !== "object" || typeof event.type !== "string") {
+        failStdoutProtocol(`invalid event envelope, receivedBytes=${Buffer.byteLength(line)}`);
+        return;
+      }
       try {
-        const event = JSON.parse(trimmed) as JsonLineEvent;
         processEvent(event);
-      } catch {
-        state.receivedFirstActivity = true;
-        addReplayEvidence("stdout-protocol", "malformed-json-line");
-        state.stdoutProtocolViolation = true;
-        if (timers.firstActivity) clearTimeout(timers.firstActivity);
-        state.lastContent = appendUtf8Tail(
-          state.lastContent,
-          trimmed + "\n",
-          EXECUTION_BUFFER_LIMITS.streamBytes,
-        );
+      } catch (error) {
+        failStdoutProtocol(`event processing failed, event=${truncateUtf8Head(event.type, 64)}: ${error instanceof Error ? truncateUtf8Head(error.message, 256) : String(error)}`);
       }
     };
+    const stdoutLines = createUtf8LineDecoder(
+      EXECUTION_BUFFER_LIMITS.transcriptBytes * 4,
+      ({ receivedBytes, maxBytes, prefix }) => {
+        const eventType = /"type"\s*:\s*"([\w-]{1,64})"/.exec(prefix)?.[1] ?? "unknown";
+        failStdoutProtocol(`oversized event=${eventType}, receivedBytes=${receivedBytes}, limitBytes=${maxBytes}`);
+      },
+      processStdoutLine,
+    );
     child.stdout?.on("data", (chunk: Buffer) => {
       pokeLifecycleDeadline();
-      for (const line of stdoutLines.write(chunk)) processStdoutLine(line);
+      stdoutLines.write(chunk);
     });
 
     const clearInterrupt = (): PendingInterrupt | undefined => {
@@ -1358,7 +1382,10 @@ export async function runSingleAttempt(
       exitCode = 0,
       terminalStatus: AgentTerminalStatus = exitCode === 0 ? "completed" : "failed",
     ): void {
-      if (state.terminal || state.turnLifecycleSettled) return;
+      if (state.terminal) return;
+      // A settled result stays published, but a later corrupt RPC line must
+      // retire the still-live runtime and report a failed lifecycle.
+      if (state.turnLifecycleSettled && !(state.stdoutProtocolViolation && terminalStatus === "failed")) return;
       if (state.stdoutProtocolViolation && exitCode === 0) {
         appendBoundedTranscriptMessage(messages, {
           role: "system",

package/src/runs/rpc-stdout-projection.mjs

@@ -0,0 +1,51 @@
+// The SDK serializes whole RPC events, including repeated tool-result images.
+// Project only telemetry; the model and persisted session retain the originals.
+function projectContent(value) {
+  if (!value || !Array.isArray(value.content)) return value;
+  let changed = false;
+  const content = value.content.map((part) => {
+    if (part?.type !== "image" || typeof part.data !== "string") return part;
+    changed = true;
+    return { type: "text", text: `[image omitted from teammate telemetry: ${Buffer.byteLength(part.data)} encoded bytes]` };
+  });
+  return changed ? { ...value, content } : value;
+}
+
+export function projectRpcEvent(event) {
+  const projected = { ...event };
+  for (const key of ["message", "result", "partialResult"]) {
+    if (event[key]) projected[key] = projectContent(event[key]);
+  }
+  for (const key of ["messages", "toolResults"]) {
+    if (Array.isArray(event[key])) projected[key] = event[key].map(projectContent);
+  }
+  return projected;
+}
+
+export function projectRpcWrite(chunk) {
+  if (typeof chunk !== "string" || !chunk.endsWith("\n") || !chunk.includes('"image"')) return chunk;
+  // RPC writes one complete JSONL event per write. Preserve malformed writes
+  // verbatim so the parent remains the protocol-failure authority.
+  let event;
+  try {
+    event = JSON.parse(chunk);
+  } catch (error) {
+    if (error instanceof SyntaxError) return chunk;
+    throw error;
+  }
+  if (!event || typeof event !== "object" || typeof event.type !== "string") return chunk;
+  return `${JSON.stringify(projectRpcEvent(event))}\n`;
+}
+
+export function installRpcStdoutProjection(stream) {
+  const originalWrite = stream.write;
+  stream.write = function (chunk, encodingOrCallback, callback) {
+    return originalWrite.call(this, projectRpcWrite(chunk), encodingOrCallback, callback);
+  };
+}
+
+// A child inherits NODE_OPTIONS into tools too; never intercept their stdout.
+if (process.env.PI_TEAMMATE_CHILD === "1"
+  && process.argv.some((arg, index, args) => arg === "--mode" && args[index + 1] === "rpc")) {
+  installRpcStdoutProjection(process.stdout);
+}

package/src/transcript/session-history.ts

@@ -98,7 +98,14 @@ export interface SessionHistoryOptions {
   signal?: AbortSignal;
 }
 export type SessionHistoryListOptions = SessionHistoryOptions;
-export type SessionHistorySearchOptions = SessionHistoryOptions;
+export interface SessionHistorySearchOptions extends SessionHistoryOptions {
+  /** Literal matching is the compatibility default; terms require every unique normalized term in one projected entry. */
+  mode?: "literal" | "terms";
+  /** Relevance ranks exact text, continuous phrase, then the tightest term span; ties retain source order. */
+  sort?: "source" | "relevance";
+  /** Zero-based match offset within this fresh scan (not a snapshot cursor). */
+  offset?: number;
+}
 export type SessionHistoryReadOptions = SessionHistoryOptions;
 export type SessionHistoryCompactionOptions = Omit<SessionHistoryOptions, "include">;
 
@@ -161,7 +168,10 @@ export interface SessionHistorySearchResult extends ScanMetrics {
   generation?: number;
   query: string;
   matches: readonly SessionHistorySearchMatch[];
+  /** Total matches in this scan, independent of pagination. */
   matchCount: number;
+  hasMore: boolean;
+  nextOffset?: number;
 }
 export interface SessionHistoryCompactionResult extends ScanMetrics {
   version: typeof SESSION_HISTORY_VERSION;
@@ -251,6 +261,7 @@ export class SessionHistoryService {
   }
 
   async list(options: SessionHistoryListOptions = {}): Promise<SessionHistoryListResult> {
+    rejectSearchOptions(options);
     const include = normalizedInclude(options.include);
     const limit = boundedLimit(options.limit);
     const scan = await this.#scan(include, options.signal);
@@ -268,36 +279,57 @@ export class SessionHistoryService {
 
   async search(query: string, options: SessionHistorySearchOptions = {}): Promise<SessionHistorySearchResult> {
     validateQuery(query);
+    const mode = options.mode ?? "literal";
+    const sort = options.sort ?? "source";
+    if (mode !== "literal" && mode !== "terms") throw new TypeError("mode must be literal or terms.");
+    if (sort !== "source" && sort !== "relevance") throw new TypeError("sort must be source or relevance.");
+    const offset = options.offset ?? 0;
+    if (!Number.isSafeInteger(offset) || offset < 0) throw new TypeError("offset must be a non-negative safe integer.");
+    const folded = mode === "terms" ? normalizedSearchText(query) : query.toLocaleLowerCase("en-US");
+    if (mode === "terms" && folded.length === 0) throw new TypeError("terms query must contain non-whitespace text.");
+    const terms = mode === "terms" ? [...new Set(folded.split(" "))] : [folded];
     const include = normalizedInclude(options.include);
     const limit = boundedLimit(options.limit);
     const scan = await this.#scan(include, options.signal);
-    const folded = query.toLocaleLowerCase("en-US");
-    const matches: SessionHistorySearchMatch[] = [];
-    let matchCount = 0;
+    const ranked: Array<{ entry: SessionHistoryEntry; index: number; rank: number; span: number; sourceOrder: number }> = [];
     for (const session of scan.sessions) {
       for (const entry of session.entries) {
-        const index = entry.text.toLocaleLowerCase("en-US").indexOf(folded);
-        if (index < 0) continue;
-        matchCount += 1;
-        if (matches.length >= limit) continue;
-        matches.push({
-          sessionId: entry.sessionId,
-          entryId: entry.entryId,
-          turn: entry.turn,
-          resourceUri: entry.resourceUri,
-          kind: entry.kind,
-          timestamp: entry.timestamp,
-          snippet: boundedSnippet(entry.text, index),
+        const text = mode === "terms" ? normalizedSearchText(entry.text) : entry.text.toLocaleLowerCase("en-US");
+        const indices = terms.map((term) => text.indexOf(term));
+        if (indices.some((index) => index < 0)) continue;
+        const phraseIndex = text.indexOf(folded);
+        ranked.push({
+          entry,
+          index: phraseIndex >= 0 ? phraseIndex : Math.min(...indices),
+          rank: text === folded ? 0 : phraseIndex >= 0 ? 1 : 2,
+          span: sort === "relevance" ? tightestTermSpan(text, terms, indices) : 0,
+          sourceOrder: ranked.length,
         });
       }
     }
+    if (sort === "relevance") ranked.sort((left, right) =>
+      left.rank - right.rank || left.span - right.span || left.sourceOrder - right.sourceOrder);
+    const page = ranked.slice(offset, offset + limit);
+    const matches: SessionHistorySearchMatch[] = page.map(({ entry, index }) => ({
+      sessionId: entry.sessionId,
+      entryId: entry.entryId,
+      turn: entry.turn,
+      resourceUri: entry.resourceUri,
+      kind: entry.kind,
+      timestamp: entry.timestamp,
+      snippet: boundedSnippet(entry.text, mode === "terms" && entry.text.length > MAX_SESSION_HISTORY_SNIPPET_CHARS
+        ? originalSearchIndex(entry.text, index) : index),
+    }));
+    const remaining = Math.max(0, ranked.length - offset - matches.length);
     return resultWithMetrics(scan, {
       version: SESSION_HISTORY_VERSION,
       ...(scan.generation === undefined ? {} : { generation: scan.generation }),
       query,
       matches: Object.freeze(matches),
-      matchCount,
-    }, matchCount - matches.length);
+      matchCount: ranked.length,
+      hasMore: remaining > 0,
+      ...(remaining > 0 ? { nextOffset: offset + matches.length } : {}),
+    }, remaining);
   }
 
   async searchSessions(query: string, options: SessionHistorySearchOptions = {}): Promise<SessionHistorySearchResult> {
@@ -305,6 +337,7 @@ export class SessionHistoryService {
   }
 
   async compactions(options: SessionHistoryCompactionOptions = {}): Promise<SessionHistoryCompactionResult> {
+    rejectSearchOptions(options);
     const limit = boundedLimit(options.limit);
     const scan = await this.#scan(new Set<SessionHistoryInclude>(["compaction"]), options.signal);
     const all = scan.sessions
@@ -331,6 +364,7 @@ export class SessionHistoryService {
     options: SessionHistoryReadOptions = {},
   ): Promise<SessionHistoryReadResult> {
     const request = typeof sessionOrRequest === "string" ? { sessionId: sessionOrRequest, ...options } : sessionOrRequest;
+    rejectSearchOptions(request);
     validateIdentifierInput(request.sessionId, "sessionId");
     if (request.entryId !== undefined) validateIdentifierInput(request.entryId, "entryId");
     if (request.turn !== undefined && (!Number.isSafeInteger(request.turn) || request.turn < 0)) {
@@ -775,6 +809,50 @@ function boundedLimit(value: number | undefined): number {
   }
   return value;
 }
+function rejectSearchOptions(options: SessionHistoryOptions): void {
+  for (const key of ["mode", "sort", "offset"] as const) {
+    if (key in options) throw new TypeError(`${key} is available only for search.`);
+  }
+}
+function normalizedSearchText(text: string): string {
+  return text.normalize("NFKC").toLocaleLowerCase("en-US").replace(/\s+/gu, " ").trim();
+}
+
+/** Map a non-whitespace match back via whole-prefix normalization, only for
+ * returned long snippets. Per-character/grapheme normalization is insufficient:
+ * compatibility Hangul jamo can compose across original grapheme boundaries.
+ * Prefix lengths account for composition, expansion and collapsed whitespace. */
+function originalSearchIndex(text: string, target: number): number {
+  let low = 0;
+  let high = text.length;
+  while (low < high) {
+    const middle = Math.floor((low + high) / 2);
+    if (normalizedSearchText(text.slice(0, middle)).length > target) high = middle;
+    else low = middle + 1;
+  }
+  let index = Math.max(0, low - 1);
+  // A normalized character may expand to several UTF-16 units; anchor an
+  // astral source character at its high surrogate, not in its middle.
+  if (index > 0 && /[\uDC00-\uDFFF]/.test(text[index]!)) index -= 1;
+  return index;
+}
+
+/** Smallest covering window over all unique substring terms; no tokenization
+ * beyond query whitespace and no matching across projected entries. */
+function tightestTermSpan(text: string, terms: readonly string[], initial: readonly number[]): number {
+  if (terms.length === 1) return terms[0]!.length;
+  const indices = [...initial];
+  let best = Infinity;
+  while (true) {
+    const start = Math.min(...indices);
+    const end = Math.max(...indices.map((index, term) => index + terms[term]!.length));
+    best = Math.min(best, end - start);
+    const earliest = indices.indexOf(start);
+    const next = text.indexOf(terms[earliest]!, start + 1);
+    if (next < 0) return best;
+    indices[earliest] = next;
+  }
+}
 function validateQuery(query: string): void {
   if (typeof query !== "string" || query.length === 0 || query.length > MAX_SESSION_HISTORY_QUERY_CHARS || query.includes("\0")) {
     throw new TypeError(`query must be a non-empty string of at most ${MAX_SESSION_HISTORY_QUERY_CHARS} characters.`);

package/types/runs/execution-infra.d.ts

@@ -522,7 +522,11 @@ export declare function appendBoundedTranscriptMessage(messages: Array<{
     role: string;
     content: string;
 }): void;
-export declare function createUtf8LineDecoder(maxBufferedBytes?: number): Utf8LineDecoder;
+export declare function createUtf8LineDecoder(maxBufferedBytes?: number, onOverflow?: (info: {
+    receivedBytes: number;
+    maxBytes: number;
+    prefix: string;
+}) => void, onLine?: (line: string) => void): Utf8LineDecoder;
 export declare function appendDistinctAssistantMessage(messages: Array<{
     role: string;
     content: string;

package/types/transcript/session-history.d.ts

@@ -59,7 +59,14 @@ export interface SessionHistoryOptions {
     signal?: AbortSignal;
 }
 export type SessionHistoryListOptions = SessionHistoryOptions;
-export type SessionHistorySearchOptions = SessionHistoryOptions;
+export interface SessionHistorySearchOptions extends SessionHistoryOptions {
+    /** Literal matching is the compatibility default; terms require every unique normalized term in one projected entry. */
+    mode?: "literal" | "terms";
+    /** Relevance ranks exact text, continuous phrase, then the tightest term span; ties retain source order. */
+    sort?: "source" | "relevance";
+    /** Zero-based match offset within this fresh scan (not a snapshot cursor). */
+    offset?: number;
+}
 export type SessionHistoryReadOptions = SessionHistoryOptions;
 export type SessionHistoryCompactionOptions = Omit<SessionHistoryOptions, "include">;
 export interface SessionHistorySession {
@@ -117,7 +124,10 @@ export interface SessionHistorySearchResult extends ScanMetrics {
     generation?: number;
     query: string;
     matches: readonly SessionHistorySearchMatch[];
+    /** Total matches in this scan, independent of pagination. */
     matchCount: number;
+    hasMore: boolean;
+    nextOffset?: number;
 }
 export interface SessionHistoryCompactionResult extends ScanMetrics {
     version: typeof SESSION_HISTORY_VERSION;