pi-jar 0.2.2 → 0.2.3

package/src/context-diet.ts

@@ -1,11 +1,20 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 /** Character counts are diagnostics, NOT token estimates: signatures can be opaque ciphertext. */
-export interface ContextDietStats {
+export interface ThinkingDietStats {
   removedThinkingParts: number;
   removedVisibleChars: number;
   removedSignatureChars: number;
 }
+/** Superseded `read` results replaced by a stub, and the characters of file text they carried. */
+export interface ReadDietStats {
+  stubbedReads: number;
+  stubbedReadChars: number;
+}
+export type ContextDietStats = ThinkingDietStats & ReadDietStats;
 
 export interface DietMessage {
   role: string;
@@ -13,24 +22,58 @@ export interface DietMessage {
   toolCallId?: string;
 }
 
-const emptyStats = (): ContextDietStats => ({ removedThinkingParts: 0, removedVisibleChars: 0, removedSignatureChars: 0 });
+const emptyStats = (): ContextDietStats => ({ removedThinkingParts: 0, removedVisibleChars: 0, removedSignatureChars: 0, stubbedReads: 0, stubbedReadChars: 0 });
 const record = (value: unknown): Record<string, unknown> | undefined =>
   value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
 
 /**
- * Opt-in provider-context projection; never edits the session or mutates its messages.
- * Only prior user turns are eligible. The complete current reasoning/tool chain is retained.
- * Ambiguous, unresolved or boundary-crossing historical tool calls make the whole projection
- * a no-op: reducing context is less important than preserving provider sequencing constraints.
+ * `details` of a read-cache stub (src/compact-tools.ts). Such a result points at an earlier read
+ * instead of carrying file text, so it never supersedes that read.
+ */
+export interface ReadStubDetails { unchangedSinceRead: number }
+export const isReadStub = (details: unknown): details is ReadStubDetails => typeof record(details)?.unchangedSinceRead === "number";
+
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+/**
+ * Pi's read/edit/write path resolution (odd spaces, `@path`, `~`, file URLs) without probing the
+ * filesystem. Undefined for a file URL Pi itself rejects; callers then just don't match the path.
  */
-export function trimCompletedThinking<T extends DietMessage>(messages: T[]): { messages: T[]; stats: ContextDietStats } {
-  const stats = emptyStats();
+export function resolveToolPath(path: string, cwd: string): string | undefined {
+  let value = path.replace(UNICODE_SPACES, " ");
+  if (value.startsWith("@")) value = value.slice(1);
+  if (value === "~" || value.startsWith("~/")) value = join(homedir(), value.slice(2));
+  else if (value.startsWith("file://")) {
+    try { value = fileURLToPath(value); } catch { return undefined; }
+  }
+  return resolve(cwd, value);
+}
+
+/**
+ * The line window a read returns; Pi treats a missing offset and offsets ≤ 1 alike. Undefined when the
+ * arguments are not plain numbers, so an unvalidated request never matches another.
+ */
+export function readRangeKey(offset: unknown, limit: unknown): string | undefined {
+  const start = offset === undefined ? 1 : typeof offset === "number" ? Math.max(offset, 1) : undefined;
+  if (start === undefined || (limit !== undefined && typeof limit !== "number")) return undefined;
+  return `${start}:${limit ?? ""}`;
+}
+
+/** Completed prior user turns span [firstUser, boundary); every call there has its result there. */
+interface History { firstUser: number; boundary: number; results: Map<string, number> }
+
+/**
+ * The completed prior-user-turn span a projection may rewrite; the complete current reasoning/tool
+ * chain is never eligible. Ambiguous, unresolved or boundary-crossing historical tool calls make it
+ * undefined, so every projection is a no-op: reducing context is less important than preserving
+ * provider sequencing constraints.
+ */
+function completedHistory(messages: readonly DietMessage[]): History | undefined {
   let boundary = -1;
   for (let index = messages.length - 1; index >= 0; index--) {
     if (messages[index]!.role === "user") { boundary = index; break; }
   }
   const firstUser = messages.findIndex(message => message.role === "user");
-  if (boundary <= 0 || firstUser === boundary) return { messages, stats };
+  if (boundary <= 0 || firstUser === boundary) return undefined;
 
   const calls = new Map<string, number>();
   const results = new Map<string, number>();
@@ -38,7 +81,7 @@ export function trimCompletedThinking<T extends DietMessage>(messages: T[]): { m
     const message = messages[index]!;
     if (message.role === "toolResult") {
       const id = message.toolCallId;
-      if (typeof id !== "string" || !id || results.has(id)) return { messages, stats };
+      if (typeof id !== "string" || !id || results.has(id)) return undefined;
       results.set(id, index);
     }
     if (message.role !== "assistant" || !Array.isArray(message.content)) continue;
@@ -46,19 +89,31 @@ export function trimCompletedThinking<T extends DietMessage>(messages: T[]): { m
       const part = record(value);
       if (part?.type !== "toolCall") continue;
       const id = part.id;
-      if (typeof id !== "string" || !id || calls.has(id)) return { messages, stats };
+      if (typeof id !== "string" || !id || calls.has(id)) return undefined;
       calls.set(id, index);
     }
   }
   for (const [id, index] of calls) {
     if (index >= boundary) continue;
     const result = results.get(id);
-    if (result === undefined || result <= index || result >= boundary) return { messages, stats };
+    if (result === undefined || result <= index || result >= boundary) return undefined;
   }
   // A detached historical result means the original reasoning sequence is not fully known.
   for (const [id, index] of results) {
-    if (index < boundary && !calls.has(id)) return { messages, stats };
+    if (index < boundary && !calls.has(id)) return undefined;
   }
+  return { firstUser, boundary, results };
+}
+
+/**
+ * Opt-in provider-context projection; never edits the session or mutates its messages.
+ * Only prior user turns are eligible (see completedHistory).
+ */
+export function trimCompletedThinking<T extends DietMessage>(messages: T[]): { messages: T[]; stats: ThinkingDietStats } {
+  const stats: ThinkingDietStats = { removedThinkingParts: 0, removedVisibleChars: 0, removedSignatureChars: 0 };
+  const history = completedHistory(messages);
+  if (!history) return { messages, stats };
+  const { firstUser, boundary } = history;
 
   let changed = false;
   const projected = messages.map((message, index) => {
@@ -79,15 +134,101 @@ export function trimCompletedThinking<T extends DietMessage>(messages: T[]): { m
   return { messages: changed ? projected : messages, stats };
 }
 
+/** Total text of an all-text result; undefined when it holds images or unknown parts. */
+function textLength(content: unknown): number | undefined {
+  if (!Array.isArray(content) || !content.length) return undefined;
+  let chars = 0;
+  for (const value of content) {
+    const part = record(value);
+    if (part?.type !== "text" || typeof part.text !== "string") return undefined;
+    chars += part.text.length;
+  }
+  return chars;
+}
+
+interface OpenRead { result: number; path: string; chars: number }
+
+/**
+ * Opt-in projection, under the same eligibility as trimCompletedThinking: a `read` result that a later
+ * read of the same file and line window, or a successful edit/write of the file, superseded becomes a
+ * one-line stub; the toolResult keeps its id, name and position. Only operations inside the read's own
+ * completed user turn count. A result's projection is therefore fixed when its turn completes and
+ * changes together with the thinking trim, never later: re-projecting an older message after newer
+ * ones arrive would re-bill the whole prefix after it (src/workflow-context.ts). Operations issued in
+ * the read's own assistant message may have run in parallel with it, so they never supersede it.
+ * Read-cache stubs, errors, images and results answered outside their turn are left alone.
+ */
+export function stubSupersededReads<T extends DietMessage>(messages: T[], cwd: string): { messages: T[]; stats: ReadDietStats } {
+  const stats: ReadDietStats = { stubbedReads: 0, stubbedReadChars: 0 };
+  const history = completedHistory(messages);
+  if (!history) return { messages, stats };
+  const { firstUser, boundary, results } = history;
+
+  const stubs = new Map<number, string>();
+  const supersede = (read: OpenRead, by: string) => {
+    const stub = `[superseded by a later ${by} of ${read.path}]`;
+    if (stubs.has(read.result) || stub.length >= read.chars) return;
+    stubs.set(read.result, stub);
+    stats.stubbedReads++;
+    stats.stubbedReadChars += read.chars;
+  };
+  for (let start = firstUser; start < boundary;) {
+    // The boundary is a user message, so every completed turn ends at one.
+    let end = start + 1;
+    while (messages[end]!.role !== "user") end++;
+    /** File → line window → newest read of this turn not yet superseded. */
+    const open = new Map<string, Map<string, OpenRead>>();
+    for (let index = start + 1; index < end; index++) {
+      const message = messages[index]!;
+      if (message.role !== "assistant" || !Array.isArray(message.content)) continue;
+      const added: Array<{ file: string; range: string; read: OpenRead }> = [];
+      for (const value of message.content) {
+        const part = record(value);
+        const args = record(part?.arguments);
+        const name = part?.name;
+        if (part?.type !== "toolCall" || (name !== "read" && name !== "edit" && name !== "write") || typeof args?.path !== "string") continue;
+        const result = results.get(part.id as string)!;
+        const outcome = record(messages[result]);
+        const file = resolveToolPath(args.path, cwd);
+        if (result >= end || !file || outcome?.isError === true) continue;
+        if (name !== "read") {
+          for (const read of open.get(file)?.values() ?? []) supersede(read, name);
+          open.delete(file);
+          continue;
+        }
+        const range = readRangeKey(args.offset, args.limit);
+        const chars = range === undefined || isReadStub(outcome?.details) ? undefined : textLength(outcome?.content);
+        if (range === undefined || chars === undefined) continue;
+        const prior = open.get(file)?.get(range);
+        if (prior) supersede(prior, "read");
+        added.push({ file, range, read: { result, path: args.path, chars } });
+      }
+      for (const { file, range, read } of added) {
+        let ranges = open.get(file);
+        if (!ranges) open.set(file, ranges = new Map());
+        ranges.set(range, read);
+      }
+    }
+    start = end;
+  }
+  if (!stubs.size) return { messages, stats };
+  const projected = messages.map((message, index) => {
+    const stub = stubs.get(index);
+    return stub === undefined ? message : { ...message, content: [{ type: "text", text: stub }] } as T;
+  });
+  return { messages: projected, stats };
+}
+
 /** Register a runtime-toggleable diet; caller owns its persisted, opt-in setting. */
 export function registerContextDiet(pi: ExtensionAPI, enabled: () => boolean): { stats: () => ContextDietStats } {
   let latest = emptyStats();
-  pi.on("context", event => {
+  pi.on("context", (event, ctx) => {
     latest = emptyStats();
     if (!enabled()) return;
-    const result = trimCompletedThinking(event.messages);
-    latest = result.stats;
-    if (result.messages !== event.messages) return { messages: result.messages };
+    const thinking = trimCompletedThinking(event.messages);
+    const reads = stubSupersededReads(thinking.messages, ctx.cwd);
+    latest = { ...thinking.stats, ...reads.stats };
+    if (reads.messages !== event.messages) return { messages: reads.messages };
   });
   pi.on("session_start", () => { latest = emptyStats(); });
   return { stats: () => ({ ...latest }) };

package/src/{democracy.ts → council.ts}

@@ -5,7 +5,7 @@ import { askOne } from "./ask-tool.ts";
 import { MAX_RESUME_CHARS, type DelegateController, type SubagentReport } from "./delegate.ts";
 
 export interface DecisionOption { id: string; label: string; evidence: string }
-export interface DemocracyRequest {
+export interface CouncilRequest {
   complexity: "super-complex";
   issue: string;
   justification: string;
@@ -16,7 +16,7 @@ export interface DemocracyRequest {
   voters?: number;
 }
 export interface Ballot { agent: string; option: string; rationale: string }
-export interface DemocracyResult {
+export interface CouncilResult {
   status: "majority" | "needs-user";
   electorate: number;
   ballots: Ballot[];
@@ -33,15 +33,15 @@ export const BALLOT_TIMEOUT_MS = 10 * 60_000;
 const MAX_RATIONALE = 600;
 const MAX_FAILURE = 200;
 
-/** Runtime gates as well as a schema: democracy is not an ordinary task-selection shortcut. */
-export function validateDemocracy(request: DemocracyRequest): void {
+/** Runtime gates as well as a schema: the council is not an ordinary task-selection shortcut. */
+export function validateCouncil(request: CouncilRequest): void {
   if (request.complexity !== "super-complex" || !request.issue?.trim() || !request.justification?.trim()) {
     throw new Error("Voting requires a persistent super-complex issue and a concrete complexity justification.");
   }
   if (!Array.isArray(request.failedApproaches) || request.failedApproaches.length < 2 ||
     request.failedApproaches.some((item) => typeof item !== "string" || !item.trim()) ||
     new Set(request.failedApproaches.map((item) => item.trim())).size < 2) {
-    throw new Error("Provide evidence of at least two distinct failed approaches; routine decisions must not use democracy.");
+    throw new Error("Provide evidence of at least two distinct failed approaches; routine decisions must not use the council.");
   }
   if (!Array.isArray(request.options) || request.options.length < 2 || request.options.length > 8 ||
     request.options.some((option) => !/^[a-zA-Z0-9_-]{1,40}$/.test(option.id) || !option.label?.trim() || !option.evidence?.trim()) ||
@@ -65,7 +65,7 @@ export function parseBallot(report: SubagentReport, nonce: string, options: read
 }
 
 export function tallyBallots(options: readonly DecisionOption[], electorate: number, ballots: Ballot[],
-  failures: DemocracyResult["failures"] = []): DemocracyResult {
+  failures: CouncilResult["failures"] = []): CouncilResult {
   if (!Number.isInteger(electorate) || electorate < 2 || ballots.length > electorate ||
     new Set(ballots.map((ballot) => ballot.agent)).size !== ballots.length) throw new Error("Invalid electorate or duplicate ballot");
   const counts = Object.fromEntries(options.map((option) => [option.id, 0]));
@@ -85,9 +85,9 @@ export function tallyBallots(options: readonly DecisionOption[], electorate: num
  * Same retained pool and launch cap as jar_delegate; no forks, writable workers or extra process launcher.
  * Scouts spawned only to vote are retired after the tally so they never hold pool slots; nominated scouts stay.
  */
-export async function conductDemocracy(controller: DelegateController, request: DemocracyRequest,
-  maxSubagents: number, signal?: AbortSignal, timeoutMs = BALLOT_TIMEOUT_MS): Promise<DemocracyResult> {
-  validateDemocracy(request);
+export async function conductCouncil(controller: DelegateController, request: CouncilRequest,
+  maxSubagents: number, signal?: AbortSignal, timeoutMs = BALLOT_TIMEOUT_MS): Promise<CouncilResult> {
+  validateCouncil(request);
   if (signal?.aborted) throw new Error("Vote aborted");
   const agents = request.agents ?? [];
   const voters = request.voters ?? Math.max(2, agents.length || Math.min(4, maxSubagents));
@@ -135,7 +135,7 @@ export async function conductDemocracy(controller: DelegateController, request:
     const results = await Promise.allSettled(jobs.map((job) => job()));
     if (signal?.aborted) throw new Error("Vote aborted; do not act on incomplete ballots");
     const ballots: Ballot[] = [];
-    const failures: DemocracyResult["failures"] = [];
+    const failures: CouncilResult["failures"] = [];
     results.forEach((result, index) => {
       if (result.status === "fulfilled") ballots.push(result.value);
       else failures.push({ agent: agents[index] ?? `new-scout-${index + 1}`,
@@ -161,19 +161,16 @@ async function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<
   } finally { if (abort) signal.removeEventListener("abort", abort); }
 }
 
-export function registerDemocracy(pi: ExtensionAPI, controller: () => DelegateController | undefined,
+export function registerCouncil(pi: ExtensionAPI, controller: () => DelegateController | undefined,
   maxSubagents: () => number): void {
   if (typeof pi.registerTool !== "function") return;
   let running = false;
   pi.registerTool({
-    name: "jar_democracy", label: "exceptional decision vote",
-    description: "Only for persistent super-complex issues after at least two distinct failed approaches: open evidence-backed options, spawn or resume relevant fresh read-only scouts, collect private ballots, and return a strict-majority recommendation. Ties or no majority require the user's choice; this tool never implements a decision.",
-    promptSnippet: "Reserve jar_democracy for persistent super-complex issues with several viable options, never routine tasks.",
+    name: "jar_council", label: "exceptional decision vote",
+    description: "Exceptional decision vote. Explain why the issue is super-complex and cite at least two distinct failed approaches, then open 2–8 evidence-backed options. Prefer relevant idle fresh-context scouts (`agents`) over forks; fresh scouts avoid discussion bias. All voters share the retained pool cap. A strict majority of the invited electorate wins; ties, insufficient ballots and plurality go to the user — present leading options with evidence-based tradeoffs, never invented probabilities. Never implements a decision.",
+    promptSnippet: "jar_council is exceptional: only for a persistent super-complex issue with several viable options after two failed approaches, never routine choices.",
     promptGuidelines: [
-      "Explain why the task is super-complex and cite at least two failed approaches before opening a vote.",
-      "Prefer relevant idle fresh-context scouts over forks; use fresh scouts where prior discussion could bias the decision. All voters share the configured retained pool cap.",
-      "A strict majority of the invited electorate wins. Ties, insufficient ballots, and plurality without majority go to the user. Present leading options with evidence-based likelihood/tradeoffs, not invented probabilities.",
-      "If userChoice is absent or cancelled, use jar_ask to resolve needs-user; never treat the moderator's preferred option as a winner. Safety and approval requirements still apply to majority outcomes."
+      "If the result needs the user and userChoice is absent or cancelled, resolve it with jar_ask; a majority is a recommendation, not approval to skip safety checks."
     ],
     parameters: Type.Object({
       complexity: Type.Literal("super-complex"),
@@ -186,22 +183,22 @@ export function registerDemocracy(pi: ExtensionAPI, controller: () => DelegateCo
       voters: Type.Optional(Type.Integer({ minimum: 2, maximum: 16 }))
     }),
     async execute(_id, params, signal, _update, ctx) {
-      if (running) return { content: [{ type: "text", text: "A democracy round is already running." }], isError: true, details: undefined };
+      if (running) return { content: [{ type: "text", text: "A council round is already running." }], isError: true, details: undefined };
       const fleet = controller();
       if (!fleet) return { content: [{ type: "text", text: "Delegation is unavailable in this session." }], isError: true, details: undefined };
       running = true;
       try {
-        const result = await conductDemocracy(fleet, params, maxSubagents(), signal);
+        const result = await conductCouncil(fleet, params, maxSubagents(), signal);
         let userChoice: Awaited<ReturnType<typeof askOne>> | undefined;
         let selectionError: string | undefined;
         if (result.status === "needs-user" && ctx.hasUI && ctx.mode === "tui" && !signal?.aborted) {
           const choices = params.options.filter((option) => result.shortlist.includes(option.id));
-          try { userChoice = await abortable(askOne(ctx, { id: "democracy", header: "Moderator decision",
+          try { userChoice = await abortable(askOne(ctx, { id: "council", header: "Moderator decision",
             question: "No strict majority. Leading options: " + choices.map((option) => `${option.id}: ${result.counts[option.id]} votes`).join("; ") +
               ". Pick based on the evidence/tradeoffs, or discuss before deciding.",
             options: choices.map((option) => ({ label: option.id + ": " + option.label, description: option.evidence.slice(0, 320) })), allowCustom: true }, 0, 1, signal), signal); }
           catch (error) { selectionError = String(error); }
-          if (signal?.aborted) userChoice = { id: "democracy", cancelled: true };
+          if (signal?.aborted) userChoice = { id: "council", cancelled: true };
         }
         const details = { ...result, ...(userChoice ? { userChoice } : {}), ...(selectionError ? { selectionError } : {}) };
         return { content: [{ type: "text", text: JSON.stringify({ ...details,