pi-better-subagents 0.6.0 → 0.7.1

package/shared-failure-observations.ts

@@ -75,7 +75,8 @@ export function failureIdentity(...parts: unknown[]): string {
   return createHash("sha256").update(JSON.stringify(parts)).digest("hex").slice(0, 32);
 }
 function text(value: string | undefined, fallback: string): string {
-  return (value || fallback).replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 400);
+  // The 400-unit cut can split a surrogate pair; a lone half would render as U+FFFD (#332).
+  return dropLoneSurrogates((value || fallback).replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 400));
 }
 
 /** Agent tool attempts: the agent handles its own tool errors, so one failure is not yet actionable. */
@@ -104,24 +105,60 @@ export interface CommandIntent {
 export type CommandIntentField = keyof CommandIntent;
 const INTENT_FIELDS: readonly CommandIntentField[] = ["operationId", "attemptId", "expectedExitCodes"];
 /**
- * The one normalization of intent-bearing arguments: an explicit `null` intent field means
- * "not declared", exactly like an omitted one. Models routinely send optional fields as null, and
- * Pi's argument validation (0.87+) drops optional nulls before a tool runs, while the process log
- * and session record keep the raw arguments. Every reader of intent, the executing tool and the
- * replay alike, goes through this so both sides see the same declaration from the same input.
+ * Pi's own argument coercion for the intent fields (pi-ai `validateToolArguments` against the confined
+ * bash schema, where each field is `anyOf: [field schema, null]`). Pi applies it before execute, but the
+ * process log and session record keep the raw arguments; mirroring it lets the parent's replay read
+ * the declaration the child executed with (#332).
+ * - ids: a number or boolean becomes its string; `""` fails the pattern and falls through to null.
+ * - exit codes: array items that read as integers become integers (null -> 0, true -> 1);
+ *   a scalar `0`, `""`, or `false` falls through to null.
+ */
+function coerceInteger(value: unknown): unknown {
+  if (value === null) return 0;
+  if (typeof value === "string" && value.trim() !== "" && Number.isInteger(Number(value))) return Number(value);
+  if (typeof value === "boolean") return value ? 1 : 0;
+  return value;
+}
+function normalizeIntentField(key: CommandIntentField, value: unknown): unknown {
+  if (value == null) return undefined;
+  if (key === "expectedExitCodes") {
+    if (value === 0 || value === "" || value === false) return undefined;
+    if (!Array.isArray(value)) return value;
+    // 0 is a no-op declaration: exit 0 is already success. A list of only zeros declares nothing.
+    const codes = value.map(coerceInteger).filter((code) => code !== 0);
+    if (codes.length === 0 && value.length > 0) return undefined;
+    return codes.length === value.length && codes.every((code, index) => code === value[index]) ? value : codes;
+  }
+  if (value === "") return undefined;
+  return typeof value === "number" || typeof value === "boolean" ? String(value) : value;
+}
+/**
+ * The one normalization of intent-bearing arguments. An explicit `null` intent field means "not
+ * declared", exactly like an omitted one: models routinely send optional fields as null, and Pi's
+ * argument validation drops or nulls them before a tool runs, while the process log and session
+ * record keep the raw arguments. Values Pi would coerce are coerced the same way, and `0` is dropped
+ * from `expectedExitCodes`. Every reader of intent, the executing tool and the replay alike, and the
+ * exact operation identity go through this, so all see the same declaration from the same input.
+ * Malformed values are kept as they are for the validator to refuse.
  */
 export function withoutAbsentIntent<T>(args: T): T {
   if (!args || typeof args !== "object" || Array.isArray(args)) return args;
   const input = args as Record<string, unknown>;
-  if (!INTENT_FIELDS.some((key) => key in input && input[key] == null)) return args;
-  const out = { ...input };
-  for (const key of INTENT_FIELDS) if (key in out && out[key] == null) delete out[key];
-  return out as T;
+  let out: Record<string, unknown> | undefined;
+  for (const key of INTENT_FIELDS) {
+    if (!(key in input)) continue;
+    const value = normalizeIntentField(key, input[key]);
+    if (value === input[key]) continue;
+    out ??= { ...input };
+    if (value === undefined) delete out[key];
+    else out[key] = value;
+  }
+  return (out ?? args) as T;
 }
 /**
- * Validate structured intent fields. Absent fields (omitted, undefined, or null) are fine; malformed
+ * Validate structured intent fields after `withoutAbsentIntent`. Absent fields are fine; malformed
  * ones are an error, and the caller must not run the command. `names` renames fields in the error
- * (e.g. snake_case parameters).
+ * (e.g. snake_case parameters). `0` in `expectedExitCodes` is accepted and dropped (#332).
  */
 export function readCommandIntent(args: unknown, names: Partial<Record<CommandIntentField, string>> = {}): { intent: CommandIntent; error?: string } {
   const input = withoutAbsentIntent((args && typeof args === "object" ? args : {}) as Record<string, unknown>);
@@ -138,7 +175,7 @@ export function readCommandIntent(args: unknown, names: Partial<Record<CommandIn
   if (codes !== undefined) {
     if (!Array.isArray(codes) || codes.length === 0 || codes.length > MAX_EXPECTED_EXIT_CODES ||
       !codes.every((code) => Number.isInteger(code) && code >= 1 && code <= 255) || new Set(codes).size !== codes.length) {
-      return { intent: {}, error: `${names.expectedExitCodes ?? "expectedExitCodes"} must be 1-${MAX_EXPECTED_EXIT_CODES} distinct integers from 1 to 255` };
+      return { intent: {}, error: `${names.expectedExitCodes ?? "expectedExitCodes"} must be 1-${MAX_EXPECTED_EXIT_CODES} distinct integers from 1 to 255 (0 is allowed and ignored)` };
     }
     intent.expectedExitCodes = [...codes] as number[];
   }
@@ -481,6 +518,8 @@ export interface TerminalFailureParts {
   rows: string[];
   /** Counts and separate facts: earlier-reported, unclassified, expected, closed history, correctness. */
   notes: string[];
+  /** The unclassified-count note, when it is among `notes`: a byte budget keeps it longer than the others. */
+  unclassifiedNote?: string;
 }
 /**
  * Terminal/completion facts: actionable and incomplete incidents from `incidents` as rows,
@@ -494,12 +533,14 @@ export function terminalFailureParts(state: FailureState, incidents: readonly st
   const earlier = activeFailures(state).filter((x) => !wanted.has(x.id) && reportable(x)).length;
   if (earlier) notes.push(`${earlier} actionable incident${earlier === 1 ? " was" : "s were"} reported earlier; not repeated here.`);
   const counts = failureCounts(state);
-  if (counts.unclassified) notes.push(`${counts.unclassified} earlier tool failure${counts.unclassified === 1 ? "" : "s"} remain${counts.unclassified === 1 ? "s" : ""} unclassified.`);
+  const unclassifiedNote = counts.unclassified
+    ? `${counts.unclassified} earlier tool failure${counts.unclassified === 1 ? "" : "s"} remain${counts.unclassified === 1 ? "s" : ""} unclassified.` : undefined;
+  if (unclassifiedNote) notes.push(unclassifiedNote);
   if (counts.expected) notes.push(`${counts.expected} expected failure${counts.expected === 1 ? "" : "s"} recorded.`);
   const history = closedHistoryLine(state);
   if (history) notes.push(history);
   if (counts.unclassified || counts.actionRequired) notes.push(CORRECTNESS_NOTE);
-  return { rows, notes };
+  return { rows, notes, ...(unclassifiedNote ? { unclassifiedNote } : {}) };
 }
 export function formatTerminalFailureFacts(state: FailureState, incidents: readonly string[] = []): string {
   const { rows, notes } = terminalFailureParts(state, incidents);
@@ -607,7 +648,10 @@ export interface IncidentPageRequest extends IncidentRowOptions {
  * Caller-owned incident pages. Whole rows are preferred; a row larger than the
  * page is split at a code-point boundary and resumes at that byte, so pages
  * reconstruct formatFailureLines() exactly (join with "\n" except after a page
- * that `endsPartial`). A page never exceeds `maxBytes`.
+ * that `endsPartial`). A page never exceeds `maxBytes`, so one smaller than the
+ * next code point (up to 4 bytes) returns no text, `hasMore`, and a `nextCursor`
+ * equal to `cursor`: the caller retries with a larger page, as with
+ * pageVerbatimText. Consumers never ask for fewer than 4 bytes.
  */
 export function pageFailureIncidents(state: FailureState, request: IncidentPageRequest = {}): FailureIncidentPage {
   // A cursor carries its view: following a history cursor stays in history without the flag.
@@ -725,14 +769,19 @@ export function incidentVerbatimPage(state: FailureState, request: IncidentPageR
  * it, so a cache keyed by it never serves stale incident counts.
  */
 export function failureJournalFingerprint(path: string): string {
-  let file: string;
+  return `${fileChangeIdentity(path)}|${existsSync(`${path}.observed`) ? 1 : 0}|${pendingWrites.get(path)?.length ?? 0}`;
+}
+/**
+ * A file's identity and change stamp (device, inode, size, and nanosecond mtime/ctime), or its read
+ * error. Any append, rewrite, replacement, or deletion changes it; for cache keys, never for trust.
+ */
+export function fileChangeIdentity(path: string): string {
   try {
     const stats = statSync(path, { bigint: true });
-    file = `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeNs}:${stats.ctimeNs}`;
+    return `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeNs}:${stats.ctimeNs}`;
   } catch (error) {
-    file = `unreadable:${(error as NodeJS.ErrnoException).code ?? "error"}`;
+    return `unreadable:${(error as NodeJS.ErrnoException).code ?? "error"}`;
   }
-  return `${file}|${existsSync(`${path}.observed`) ? 1 : 0}|${pendingWrites.get(path)?.length ?? 0}`;
 }
 
 export function incidentCursorAt(state: FailureState, offset: number, resource?: string, options: IncidentRowOptions = {}): string {
@@ -867,7 +916,7 @@ export function formatTerminalIncidentSummary(state: FailureState, options: Inci
   //    cursor's retrieval hint, the unclassified count, the cursor, and the count line. The
   //    correctness note goes last, and only when it alone does not fit.
   const correctness: string[] = notes.filter((x) => x === CORRECTNESS_NOTE);
-  const unclassified = notes.filter((x) => x !== CORRECTNESS_NOTE && /remains? unclassified\.$/.test(x));
+  const unclassified = notes.filter((x) => x === parts.unclassifiedNote);
   const low = notes.filter((x) => !correctness.includes(x) && !unclassified.includes(x));
   const ladder: Array<{ mode: Header | undefined; notes: string[] }> = [];
   for (let keep = low.length - 1; keep >= 0; keep -= 1) ladder.push({ mode: "full", notes: [...low.slice(0, keep), ...unclassified, ...correctness] });

package/shared-log-utils.ts

@@ -819,29 +819,22 @@ export interface OutputControls {
   maxBytes?: unknown;
   /** Raw requested line count (canonical `lines`, else deprecated `tail_lines`). */
   lines?: unknown;
-  /** Deprecated alias names the caller used (whether or not the canonical name won). */
-  deprecated: string[];
 }
 
 /**
  * Resolve output-control parameters. Both spellings work; when both are given
- * the canonical name wins. Values are returned unvalidated so each surface
- * keeps its own defaults and hard caps.
+ * the canonical name wins. An explicit `null` is "not given", so a null
+ * canonical value never hides an alias value (#332). Values are returned
+ * unvalidated so each surface keeps its own defaults and hard caps.
  */
 export function readOutputControls(params: unknown): OutputControls {
   const p = (params && typeof params === "object" ? params : {}) as Record<string, unknown>;
-  const deprecated: string[] = [];
-  const pick = (canonical: keyof typeof OUTPUT_CONTROL_ALIASES): unknown => {
-    const alias = OUTPUT_CONTROL_ALIASES[canonical];
-    if (p[alias] !== undefined) deprecated.push(alias);
-    return p[canonical] !== undefined ? p[canonical] : p[alias];
-  };
+  const pick = (canonical: keyof typeof OUTPUT_CONTROL_ALIASES): unknown => p[canonical] ?? p[OUTPUT_CONTROL_ALIASES[canonical]] ?? undefined;
   const maxBytes = pick("max_bytes");
   const lines = pick("lines");
   return {
     ...(maxBytes !== undefined ? { maxBytes } : {}),
     ...(lines !== undefined ? { lines } : {}),
-    deprecated,
   };
 }
 
@@ -851,7 +844,8 @@ export type OutputInclude = (typeof OUTPUT_INCLUDE_VALUES)[number];
 
 /** Parse an `include` request into known values and unknown ones (both deduplicated). */
 export function readOutputInclude(value: unknown): { include: Set<OutputInclude>; unknown: string[] } {
-  const raw = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
+  // Any other non-null value (a number, boolean, or object) is one unknown entry, never silently nothing (#332).
+  const raw = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : value == null ? [] : [value];
   const include = new Set<OutputInclude>();
   const unknown: string[] = [];
   for (const entry of raw) {