@neruok/pi-advisor 0.0.0-stage → 0.1.1

package/lib/completions.ts

@@ -0,0 +1,88 @@
+import { getAgentDir, type ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { fuzzyFilter, type AutocompleteItem } from '@earendil-works/pi-tui';
+import { REASONING_LEVELS, parseSelection, parseTimeoutMs } from './protocol.ts';
+import { supportedReasoning } from './reasoning.ts';
+import { loadSettings, settingsPaths } from './settings.ts';
+
+export type CompletionContext = Pick<ExtensionContext, 'cwd' | 'modelRegistry' | 'isProjectTrusted'>;
+interface Choice { value: string; description: string }
+interface Syntax { base: string; fragment: string; args: string[]; scoped: boolean; project: boolean }
+const commands: Choice[] = [
+  { value: 'show', description: 'Show effective advisor settings' },
+  { value: 'model', description: 'Set the advisor provider and model' },
+  { value: 'reasoning', description: 'Inspect or set advisor reasoning effort' },
+  { value: 'timeout', description: 'Inspect or set the advisor deadline in milliseconds' },
+];
+const scopes: Choice[] = [
+  { value: '--global', description: 'Use global settings (default save scope)' },
+  { value: '--project', description: 'Use project settings (writes require trust)' },
+];
+function syntax(prefix: string): Syntax | undefined {
+  const fragment = prefix.match(/\S*$/)![0];
+  const base = prefix.slice(0, prefix.length - fragment.length);
+  const tokens = base.trim() ? base.trim().split(/\s+/) : [];
+  const flags = tokens.filter(token => token.startsWith('--'));
+  if (flags.length > 1 || flags.some(flag => !scopes.some(choice => choice.value === flag))) return undefined;
+  const args = tokens.filter(token => !token.startsWith('--'));
+  const [command, argument] = args;
+  if (command === 'show') {
+    if (args.length > 1) return undefined;
+  } else if (command === 'reasoning') {
+    if (args.length > 2 || (argument && !REASONING_LEVELS.some(level => level === argument))) return undefined;
+  } else if (command === 'timeout') {
+    if (args.length > 2) return undefined;
+    if (argument && argument !== 'default') {
+      if (!/^[0-9]+$/.test(argument)) return undefined;
+      try { parseTimeoutMs(Number(argument)); } catch { return undefined; }
+    }
+  } else if (command === 'model') {
+    if (args.length > 3) return undefined;
+  } else if (command) return undefined;
+  return { base, fragment, args, scoped: flags.length > 0, project: flags[0] === '--project' };
+}
+async function choices(input: Syntax, ctx?: CompletionContext): Promise<Choice[]> {
+  const { args, fragment, scoped, project } = input;
+  const [command, provider] = args;
+  const availableScopes = scoped ? [] : scopes;
+  if (fragment.startsWith('--')) return availableScopes;
+  if (!command) return [...commands, ...availableScopes];
+  if (command === 'show' || ((command === 'reasoning' || command === 'timeout') && args.length === 2) || args.length === 3) return availableScopes;
+  if (command === 'timeout') return [{ value: 'default', description: 'Remove the scoped timeout and restore inheritance' }];
+  if (!ctx) return [];
+  if (command === 'reasoning') {
+    if (project && !ctx.isProjectTrusted()) return [];
+    const pair = (await loadSettings(settingsPaths(ctx.cwd, getAgentDir()), project)).settings.model;
+    if (!pair) return [];
+    const model = ctx.modelRegistry.find(pair.provider, pair.model);
+    if (!model || model.api === 'pi-virtual') return [];
+    return supportedReasoning(model).map(value => ({ value, description: value === 'default' ? 'Keep legacy provider behavior' : `Set advisor reasoning to ${value}` }));
+  }
+  const models = ctx.modelRegistry.getAvailable().filter(model => model.api !== 'pi-virtual');
+  if (!provider) {
+    return [...new Set(models.map(model => model.provider))].sort((a, b) => a.localeCompare(b))
+      .filter(value => value.toLowerCase().startsWith(fragment.toLowerCase()))
+      .map(value => ({ value, description: 'Available advisor provider' }));
+  }
+  const candidates = models.filter(model => model.provider === provider).sort((a, b) => a.id.localeCompare(b.id));
+  return fuzzyFilter(candidates, fragment, model => `${model.id} ${model.name ?? ''}`)
+    .map(model => ({ value: model.id, description: model.name || 'Available advisor model' }));
+}
+export async function argumentCompletions(prefix: string, ctx?: CompletionContext): Promise<AutocompleteItem[] | null> {
+  const input = syntax(prefix);
+  if (!input) return null;
+  try {
+    const catalogArgument = input.args[0] === 'model' && input.args.length < 3 && !input.fragment.startsWith('--');
+    const candidates = await choices(input, ctx);
+    const matched = catalogArgument ? candidates : candidates.filter(choice => choice.value.startsWith(input.fragment));
+    const items = matched.filter(choice => {
+      if (!catalogArgument) return true;
+      if (choice.value.startsWith('--')) return false;
+      try { parseSelection({ provider: input.args[1] ?? choice.value, model: input.args[1] ? choice.value : 'placeholder' }); return true; }
+      catch { return false; }
+    }).map(choice => ({ value: `${input.base}${choice.value} `, label: choice.value, description: choice.description }));
+    return items.length ? items : null;
+  } catch {
+    // Completion failures stay silent and never trigger a retry or write.
+    return null;
+  }
+}

package/lib/context.ts

@@ -0,0 +1,17 @@
+import type { Context } from '@earendil-works/pi-ai';
+import { calculateContextTokens, estimateTokens } from '@earendil-works/pi-coding-agent';
+
+export type ContextUsage = { tokens: number; contextWindow: number; percent: number };
+// Match Pi's usage-backed context estimate. Ciphertext bytes are not model tokens.
+export function contextUsage(messages: Context['messages'], contextWindow: number): ContextUsage {
+  let trailing = 0;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message.role === 'assistant' && message.stopReason !== 'error' && message.stopReason !== 'aborted') {
+      const reported = calculateContextTokens(message.usage);
+      if (reported > 0) return { tokens: reported + trailing, contextWindow, percent: (reported + trailing) / contextWindow * 100 };
+    }
+    trailing += estimateTokens(message);
+  }
+  return { tokens: trailing, contextWindow, percent: trailing / contextWindow * 100 };
+}

package/lib/model-picker.ts

@@ -0,0 +1,85 @@
+import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import { fuzzyFilter, getKeybindings, Input, SelectList, truncateToWidth } from '@earendil-works/pi-tui';
+import { AdvisorError, type Selection } from './protocol.ts';
+
+type PickerModel = { provider: string; id: string; name?: string };
+const key = (model: PickerModel) => `${model.provider} / ${model.id}`;
+
+/** Copy pi-magic8ball's /model-style inline picker without its decision dependencies. */
+export async function selectModel(ctx: ExtensionCommandContext, title: string, models: readonly PickerModel[], current?: Selection): Promise<Selection | undefined> {
+  const entries = new Map(models.map(model => [key(model), model]));
+  if (ctx.mode !== 'tui') {
+    // Preserve advisor's existing non-TUI labels.
+    const choices = new Map(models.map(model => [`${model.provider}/${model.id}`, model]));
+    const selected = await ctx.ui.select(title, [...choices.keys()]);
+    if (selected === undefined) return undefined;
+    const model = choices.get(selected);
+    if (!model) throw new AdvisorError('model-unavailable');
+    return { provider: model.provider, model: model.id };
+  }
+  return ctx.ui.custom<Selection | undefined>((tui, theme, _keybindings, done) => {
+    const isCurrent = (model: PickerModel) => model.provider === current?.provider && model.id === current.model;
+    const items = [...entries.values()]
+      .sort((a, b) => Number(isCurrent(b)) - Number(isCurrent(a)) || a.provider.localeCompare(b.provider))
+      .map(model => ({ value: key(model), label: `${isCurrent(model) ? '✓ ' : '  '}${model.id} [${model.provider}]`, model }));
+    const search = new Input();
+    const style = {
+      selectedPrefix: (text: string) => theme.fg('accent', text),
+      selectedText: (text: string) => theme.fg('accent', text),
+      description: (text: string) => theme.fg('muted', text),
+      scrollInfo: (text: string) => theme.fg('muted', text),
+      noMatch: () => theme.fg('muted', '  No matching models'),
+    };
+    let filtered = items, selectedIndex = 0, visible = 10;
+    function makeList(): SelectList {
+      const next = new SelectList(filtered, visible, style);
+      next.setSelectedIndex(selectedIndex);
+      next.onSelectionChange = item => { selectedIndex = filtered.findIndex(entry => entry.value === item.value); };
+      next.onSelect = item => {
+        const model = entries.get(item.value)!;
+        done({ provider: model.provider, model: model.id });
+      };
+      next.onCancel = () => done(undefined);
+      return next;
+    }
+    let list = makeList();
+    search.onSubmit = () => list.handleInput('\r');
+    function filter(query: string): void {
+      // Same search text order and token ranking as Pi's /model selector.
+      filtered = fuzzyFilter(items, query, ({ model }) => `${model.provider} ${model.provider}/${model.id} ${model.provider} ${model.id}${model.name ? ` ${model.name}` : ''}`);
+      selectedIndex = query ? 0 : Math.min(selectedIndex, Math.max(0, filtered.length - 1));
+      list = makeList();
+    }
+    return {
+      get focused() { return search.focused; },
+      set focused(value: boolean) { search.focused = value; },
+      render(width: number) {
+        const height = Math.max(1, tui.terminal.rows - 2);
+        const full = height >= 10;
+        const border = theme.fg('accent', '─'.repeat(Math.max(0, width)));
+        const heading = theme.fg('accent', theme.bold(title));
+        const prefix = full ? [border, heading, ...search.render(width), '']
+          : height >= 4 ? [heading, ...search.render(width)] : height >= 2 ? search.render(width) : [];
+        const selected = filtered[selectedIndex]?.model;
+        const suffix = full ? ['', theme.fg('muted', `  Model Name: ${selected?.name ?? selected?.id ?? ''}`), theme.fg('dim', '↑↓ navigate • enter select • esc cancel'), border] : [];
+        const listHeight = height - prefix.length - suffix.length;
+        // Count SelectList's position indicator within the viewport budget.
+        const count = Math.max(1, Math.min(10, filtered.length, listHeight - (filtered.length > Math.min(10, listHeight) ? 1 : 0)));
+        if (count !== visible) { visible = count; list = makeList(); }
+        return [...prefix, ...list.render(width).slice(0, listHeight), ...suffix].map(line => truncateToWidth(line, width));
+      },
+      invalidate() { search.invalidate(); list.invalidate(); },
+      handleInput(data: string) {
+        const kb = getKeybindings();
+        if (kb.matches(data, 'tui.select.up') || kb.matches(data, 'tui.select.down') || kb.matches(data, 'tui.select.confirm') || kb.matches(data, 'tui.select.cancel')) {
+          list.handleInput(data);
+        } else {
+          const before = search.getValue();
+          search.handleInput(data);
+          if (search.getValue() !== before) filter(search.getValue());
+        }
+        tui.requestRender();
+      },
+    };
+  });
+}

package/lib/prompt.ts

@@ -0,0 +1,21 @@
+export const ADVISOR_PROMPT = `You are an advisor to another software-engineering agent.
+You have no repository, filesystem, shell, tools, parent conversation, or runtime access.
+Only this consultation's explicit messages describe the current system.
+Distinguish reported observations and test results from interpretations, assumptions, and hypotheses.
+Reported evidence is not independently verified by you. Do not invent repository facts.
+Ask the main agent to inspect, test, measure, or clarify missing evidence.
+Prefer investigations that distinguish competing explanations. Challenge unsupported framing.
+Help the main agent reach a next action or identify a user-owned decision.
+Your advice is not evidence or authorization. The main agent owns verification and action.
+Do not grant approval for product, policy, architecture, spending, or destructive choices.
+Do not repeat private reasoning. Give a concise explanation and concrete questions or recommendations.
+Reply with natural-language advice. Ask for missing evidence or describe a user-owned decision when needed.`;
+
+export const MAIN_GUIDANCE = [
+  'Use advisor for independent reasoning about debugging, design, or diagnosis. It cannot inspect code or inherit this conversation.',
+  'Explain your objective, current understanding, observations, evidence, constraints, and uncertainty. Do not substitute a code dump for an explanation.',
+  'Continue the same session for the same issue. Gather requested evidence yourself and return your findings.',
+  'Advisor claims are not evidence or authorization. Verify factual claims and obtain user approval when required before acting.',
+  'Use advisor_sessions to recover active identifiers and advisor_close when finished.',
+  'Consultations are ephemeral. Parent transcript arguments/results can still persist. Configured provider calls may incur charges.'
+];

package/lib/protocol.ts

@@ -0,0 +1,131 @@
+import type { AssistantMessage, Usage } from '@earendil-works/pi-ai';
+import type { ContextUsage } from './context.ts';
+
+export const LIMITS = Object.freeze({ timeoutMs: 300000 });
+export const MAX_TIMEOUT_MS = 2147483647;
+export const REASONING_LEVELS = ['default', 'off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] as const;
+export type Reasoning = typeof REASONING_LEVELS[number];
+export type Selection = { provider: string; model: string; reasoning?: Reasoning };
+export type ErrorCode = 'invalid-argument' | 'not-found' | 'busy' | 'limit-exceeded' | 'not-configured' | 'invalid-config' | 'settings-unavailable' | 'model-unavailable' | 'unsupported-reasoning' | 'provider-failed' | 'invalid-response' | 'cancelled' | 'timeout';
+const ERRORS: Record<ErrorCode, string> = {
+  'invalid-argument': 'Use a nonblank message and an existing session identifier, if supplied.',
+  'not-found': 'Consultation not found. It may have closed or its parent session may have changed.',
+  busy: 'Consultation has a pending request. Wait for it before sending or closing.',
+  'limit-exceeded': 'Advisor context limit exceeded. Start a new consultation with an explicit summary.',
+  'not-configured': 'No advisor model configured. Use /advisor model <provider> <model>.',
+  'invalid-config': 'Advisor settings must be strict JSON with an optional model selection and integer timeoutMs.',
+  'settings-unavailable': 'Cannot safely read or save advisor settings. Inspect settings and locks before retrying.',
+  'model-unavailable': 'Configured advisor model is unavailable, virtual, or lacks authentication.',
+  'unsupported-reasoning': 'Configured advisor reasoning is not supported by the selected model. Use /advisor reasoning to inspect supported levels.',
+  'provider-failed': 'Advisor provider request failed. No exchange was committed.',
+  'invalid-response': 'Advisor reply was not a usable text completion. No exchange was committed.',
+  cancelled: 'Advisor request cancelled. No exchange was committed.',
+  timeout: 'Advisor request deadline exceeded. No exchange was committed.'
+};
+export type LimitResource = 'context-tokens';
+export type LimitDetails = { resource: LimitResource; maximum: number; actual: number };
+const LIMIT_MESSAGES: Record<LimitResource, string> = {
+  'context-tokens': 'Advisor context limit exceeded. Start a new consultation with an explicit summary.'
+};
+const REPLY_MESSAGES = {
+  completion: 'Advisor completion did not stop normally.',
+  content: 'Advisor reply contained unsupported or malformed content.',
+  text: 'Advisor reply contained no nonblank text.'
+} as const;
+export class AdvisorError extends Error {
+  readonly code: ErrorCode;
+  readonly limit?: LimitDetails;
+  constructor(code: ErrorCode, limit?: LimitDetails, replyReason?: keyof typeof REPLY_MESSAGES) {
+    super(replyReason && code === 'invalid-response'
+      ? REPLY_MESSAGES[replyReason] + ' No exchange was committed.'
+      : limit && code === 'limit-exceeded' ? LIMIT_MESSAGES[limit.resource] : ERRORS[code]);
+    this.name = 'AdvisorError'; this.code = code; this.limit = limit;
+  }
+}
+export function parseTimeoutMs(value: unknown, code: 'invalid-config' | 'invalid-argument' = 'invalid-config'): number {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > MAX_TIMEOUT_MS) throw new AdvisorError(code);
+  return value;
+}
+export function checkLimit(resource: LimitResource, maximum: number, actual: number): void {
+  if (actual > maximum) throw new AdvisorError('limit-exceeded', { resource, maximum, actual });
+}
+export function zeroUsage(): Usage { return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } }; }
+export function addUsage(a: Usage, b: Usage): Usage {
+  const result = zeroUsage();
+  for (const key of ['input', 'output', 'cacheRead', 'cacheWrite', 'totalTokens'] as const) result[key] = a[key] + b[key];
+  for (const key of ['input', 'output', 'cacheRead', 'cacheWrite', 'total'] as const) result.cost[key] = a.cost[key] + b.cost[key];
+  for (const key of ['reasoning', 'cacheWrite1h'] as const) if (a[key] !== undefined || b[key] !== undefined) result[key] = (a[key] ?? 0) + (b[key] ?? 0);
+  return result;
+}
+export const FAILURE_PHASES = ['validation', 'preparation', 'completion', 'response-validation', 'commit'] as const;
+export const FAILURE_CATEGORIES = ['advisor-error', 'local-error', 'unknown', 'provider-error', 'provider-aborted', 'authentication', 'provider-rejection', 'rate-limit', 'transport', 'sdk-error'] as const;
+export type SelectionSource = 'global' | 'project' | 'unknown';
+export type Diagnostics = { phase: typeof FAILURE_PHASES[number]; category: typeof FAILURE_CATEGORIES[number]; model?: Selection; selectionSource?: SelectionSource; code?: 'sdk-invalid-timeout' | 'tool-choice-without-tools'; httpStatus?: number };
+// Only recognized structured fields are used. Never inspect messages, causes, headers or payloads.
+export function completionCategory(error: unknown): Diagnostics['category'] {
+  try {
+    if (!error || typeof error !== 'object') return 'unknown';
+    const status = Object.getOwnPropertyDescriptor(error, 'status')?.value;
+    if (status === 401 || status === 403) return 'authentication';
+    if (status === 429) return 'rate-limit';
+    if ([400, 404, 409, 413, 422].includes(status)) return 'provider-rejection';
+    if ([408, 500, 502, 503, 504].includes(status)) return 'transport';
+    const code = Object.getOwnPropertyDescriptor(error, 'code')?.value;
+    if (['ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'ENOTFOUND', 'EAI_AGAIN'].includes(code)) return 'transport';
+  } catch { /* Unknown diagnostic metadata must not replace the original failure. */ }
+  return 'unknown';
+}
+// Read only fixed SDK diagnostics and an exact known xAI rejection. Never return the provider body.
+export function terminalDiagnostics(reply: AssistantMessage, provider: string): Pick<Diagnostics, 'category' | 'code' | 'httpStatus'> {
+  const fallback = { category: 'provider-error' as const };
+  try {
+    const message = Object.getOwnPropertyDescriptor(reply, 'errorMessage')?.value;
+    if (typeof message !== 'string') return fallback;
+    if (message === 'timeout must be an integer' || message === 'timeout must be a positive integer') {
+      return { category: 'sdk-error', code: 'sdk-invalid-timeout' };
+    }
+    const prefix = `${provider === 'openai' ? 'OpenAI' : provider} API error (`;
+    if (!message.startsWith(prefix)) return fallback;
+    const match = /^([45][0-9]{2})\): /.exec(message.slice(prefix.length, prefix.length + 7));
+    if (!match) return fallback;
+    const httpStatus = Number(match[1]);
+    const category = completionCategory({ status: httpStatus });
+    const rejection = 'Invalid request content: A tool_choice was set on the request but no tools were specified.';
+    const detail = message.slice(prefix.length + match[0].length);
+    const noTools = provider === 'xai' && httpStatus === 400 && [rejection, rejection.slice('Invalid request content: '.length), `400 ${rejection}`].includes(detail);
+    return { category: category === 'unknown' ? 'provider-error' : category, httpStatus, ...(noTools ? { code: 'tool-choice-without-tools' as const } : {}) };
+  } catch { return fallback; }
+}
+export type UsageTotals = { totalUsage: Usage; totalUsageComplete: boolean };
+export type Failure = { ok: false; error: { code: ErrorCode; message: string; limit?: LimitDetails; diagnostics?: Diagnostics }; usage: Usage; usageComplete: boolean; session?: string; contextUsage?: ContextUsage } & Partial<UsageTotals>;
+export function failure(error: unknown, usage = zeroUsage(), session?: string, usageComplete = true): Failure {
+  const safe = error instanceof AdvisorError ? error : new AdvisorError('provider-failed');
+  return { ok: false, error: { code: safe.code, message: safe.message, ...(safe.limit ? { limit: { ...safe.limit } } : {}) }, usage, usageComplete, ...(session === undefined ? {} : { session }) };
+}
+export function object(value: unknown, keys: string[], code: ErrorCode): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !keys.includes(key))) throw new AdvisorError(code);
+  return value as Record<string, unknown>;
+}
+export function parseSelection(value: unknown): Selection {
+  const pair = object(value, ['provider', 'model', 'reasoning'], 'invalid-config');
+  for (const value of [pair.provider, pair.model]) if (typeof value !== 'string' || !value || /[\s\x00-\x1f\x7f-\x9f]/u.test(value)) throw new AdvisorError('invalid-config');
+  if (pair.reasoning !== undefined && !REASONING_LEVELS.includes(pair.reasoning as Reasoning)) throw new AdvisorError('invalid-config');
+  return { provider: pair.provider as string, model: pair.model as string, ...(pair.reasoning === undefined ? {} : { reasoning: pair.reasoning as Reasoning }) };
+}
+export function parseInput(value: unknown): { message: string; session?: string; diagnostics?: boolean } {
+  const input = object(value, ['message', 'session', 'diagnostics'], 'invalid-argument');
+  if (input.diagnostics !== undefined && typeof input.diagnostics !== 'boolean') throw new AdvisorError('invalid-argument');
+  if (typeof input.message !== 'string' || !input.message.trim() || (input.session !== undefined && (typeof input.session !== 'string' || !input.session.trim()))) throw new AdvisorError('invalid-argument');
+  return { message: input.message, ...(input.session === undefined ? {} : { session: input.session as string }), ...(input.diagnostics === undefined ? {} : { diagnostics: input.diagnostics as boolean }) };
+}
+export function replyText(message: AssistantMessage): string {
+  if (message.stopReason === 'error' || message.stopReason === 'aborted') throw new AdvisorError('provider-failed');
+  if (message.stopReason !== 'stop') throw new AdvisorError('invalid-response', undefined, 'completion');
+  if (!Array.isArray(message.content) || message.content.some(block => !block ||
+    (block.type !== 'text' && block.type !== 'thinking') || (block.type === 'text' && typeof block.text !== 'string'))) {
+    throw new AdvisorError('invalid-response', undefined, 'content');
+  }
+  const text = message.content.filter(block => block.type === 'text').map(block => block.text).join('\n');
+  if (!text.trim()) throw new AdvisorError('invalid-response', undefined, 'text');
+  return text;
+}

package/lib/reasoning.ts

@@ -0,0 +1,9 @@
+import { getSupportedThinkingLevels, type Api, type Model } from '@earendil-works/pi-ai';
+import { AdvisorError, type Reasoning } from './protocol.ts';
+
+export function supportedReasoning(model: Model<Api>): Reasoning[] {
+  return ['default', ...getSupportedThinkingLevels(model)];
+}
+export function assertReasoning(model: Model<Api>, level?: Reasoning): void {
+  if (level !== undefined && !supportedReasoning(model).includes(level)) throw new AdvisorError('unsupported-reasoning');
+}

package/lib/render.ts

@@ -0,0 +1,121 @@
+import type { Theme, ToolRenderResultOptions } from '@earendil-works/pi-coding-agent';
+import { truncateToWidth, wrapTextWithAnsi, type Component } from '@earendil-works/pi-tui';
+import type { Usage } from '@earendil-works/pi-ai';
+import type { Advice, Metadata, Phase } from './session.ts';
+import type { Failure } from './protocol.ts';
+import type { ContextUsage } from './context.ts';
+
+const PREVIEW_ROWS = 8;
+type Kind = 'advisor' | 'advisor_sessions' | 'advisor_close';
+type Data = Advice | Failure | { ok: true; sessions: Metadata[] } | { ok: true; session: string };
+const safe = (text: string): string => text.replace(/\t/g, ' ').replace(/[\x00-\x09\x0b-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/gu, '');
+const value = (text: unknown): string => typeof text === 'string' ? safe(text) : '?';
+const label = (text: unknown): string => value(text).replace(/\n/g, ' ');
+function component(lines: (width: number) => string[]): Component {
+  return { render: width => width < 1 ? [] : lines(width).map(line => truncateToWidth(line, width)), invalidate() {} };
+}
+function usageLine(usage: Usage | undefined, complete: boolean | undefined): string {
+  const tokens = usage?.totalTokens ?? 0, cost = usage?.cost?.total;
+  return `${tokens} reported tokens${typeof cost === 'number' && Number.isFinite(cost) ? `, $${cost.toFixed(6)} reported cost` : ''}${complete === true ? '' : ' (incomplete: remote usage may be missing)'}`;
+}
+// Pi 1.0.4 footer thresholds, without subscription or auto-compaction labels.
+function formatTokens(count: number | undefined): string {
+  if (typeof count !== 'number' || !Number.isFinite(count)) return '?';
+  if (count < 1000) return `${count}`;
+  if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+  if (count < 1000000) return `${Math.round(count / 1000)}k`;
+  if (count < 10000000) return `${(count / 1000000).toFixed(1)}M`;
+  return `${Math.round(count / 1000000)}M`;
+}
+function contextLine(context: ContextUsage | undefined): string {
+  return context ? `${context.percent.toFixed(1)}%/${formatTokens(context.contextWindow)}` : '?/?';
+}
+function statusLine(data: Advice | Failure): string {
+  const total = data.totalUsage ?? data.usage, latest = data.usage;
+  const input = latest.input + latest.cacheRead + latest.cacheWrite;
+  const hit = data.usageComplete && input > 0 ? `${(latest.cacheRead / input * 100).toFixed(1)}%` : '?';
+  const parts = [`↑${formatTokens(total.input)}`, `↓${formatTokens(total.output)}`, `R${formatTokens(total.cacheRead)}`];
+  if (total.cacheWrite) parts.push(`W${formatTokens(total.cacheWrite)}`);
+  parts.push(`CH${hit}`, Number.isFinite(total.cost.total) ? `$${total.cost.total.toFixed(3)}` : '$?', contextLine(data.contextUsage));
+  if (!(data.totalUsageComplete ?? data.usageComplete)) parts.push('(incomplete: remote usage may be missing)');
+  return parts.join(' ');
+}
+function header(data: Advice): string {
+  return `Advisory • ${label(data.session)} • turn ${data.turns}`;
+}
+function sessionLines(entry: Metadata, expanded: boolean): string[] {
+  return [
+    `${label(entry.session)}${entry.busy ? ' • busy' : ''} • ${entry.turns} exchanges`,
+    ...(expanded ? [label(entry.label), `${label(entry.model?.provider)}/${label(entry.model?.model)} • ${contextLine(entry.contextUsage)} advisor context`, usageLine(entry.totalUsage, entry.totalUsageComplete)] : [])
+  ];
+}
+function details(value: unknown): Data | undefined {
+  if (!value || typeof value !== 'object' || !('ok' in value)) return undefined;
+  const data = value as Data;
+  if (data.ok === false) return data.error && typeof data.error.code === 'string' && typeof data.error.message === 'string' ? data : undefined;
+  if (data.ok !== true) return undefined;
+  if ('response' in data) return typeof data.response === 'string' && data.model && typeof data.session === 'string' ? data : undefined;
+  if ('sessions' in data) return Array.isArray(data.sessions) ? data : undefined;
+  return 'session' in data && typeof data.session === 'string' ? data : undefined;
+}
+function resultLines(kind: Kind, data: Data | undefined, options: ToolRenderResultOptions, theme: Theme, width: number): string[] {
+  const styled = (color: 'muted' | 'error' | 'toolOutput' | 'accent', text: string) => wrapTextWithAnsi(theme.fg(color, safe(text)), width);
+  if (!data) return styled('muted', 'Advisor result details unavailable.');
+  if (!data.ok) {
+    const lines = [theme.fg('error', safe(`${label(data.error.code)}: ${value(data.error.message)}`))];
+    if (data.error.limit) lines.push(theme.fg('muted', safe(`${data.error.limit.resource}: ${data.error.limit.actual} / ${data.error.limit.maximum}`)));
+    if (data.error.diagnostics) {
+      const diagnostic = data.error.diagnostics;
+      lines.push(theme.fg('muted', safe(`Failure phase: ${label(diagnostic.phase)} • category: ${label(diagnostic.category)}`)));
+      if (diagnostic.code === 'sdk-invalid-timeout') lines.push(theme.fg('error', 'SDK timeout must be a positive integer. No exchange was committed.'));
+      if (diagnostic.code === 'tool-choice-without-tools') lines.push(theme.fg('error', 'xAI rejected tool_choice without tools. No exchange was committed.'));
+      if (diagnostic.httpStatus !== undefined) lines.push(theme.fg('muted', safe(`HTTP status: ${diagnostic.httpStatus}`)));
+      if (diagnostic.model) lines.push(theme.fg('muted', safe(`${label(diagnostic.model.provider)}/${label(diagnostic.model.model)} • ${label(diagnostic.selectionSource)} • reasoning: ${label(diagnostic.model.reasoning ?? 'default')}`)));
+    }
+    if (data.totalUsage) lines.push(theme.fg('muted', statusLine(data)));
+    lines.push(theme.fg('muted', usageLine(data.usage, data.usageComplete)));
+    if (options.expanded && data.totalUsage) lines.push(theme.fg('muted', `Consultation total: ${usageLine(data.totalUsage, data.totalUsageComplete)}`));
+    return lines.flatMap(line => wrapTextWithAnsi(line, width));
+  }
+  if (kind === 'advisor' && 'response' in data) {
+    const lines = [...styled('accent', header(data)), ...styled('muted', statusLine(data))];
+    if (options.expanded) {
+      lines.push(...styled('muted', usageLine(data.usage, data.usageComplete)));
+      lines.push(...styled('muted', `${label(data.model.provider)}/${label(data.model.model)}`));
+      lines.push(...styled('muted', `Reasoning: ${data.model.reasoning ?? 'default (legacy provider behavior)'}`));
+      lines.push(...styled('muted', `Consultation total: ${usageLine(data.totalUsage, data.totalUsageComplete)}`));
+    }
+    const adviceRows = styled('toolOutput', value(data.response));
+    const preview = !options.expanded && adviceRows.length > PREVIEW_ROWS;
+    lines.push(...(preview ? adviceRows.slice(0, PREVIEW_ROWS) : adviceRows));
+    if (preview) lines.push(...styled('muted', '… Expand for full advice.'));
+    return lines;
+  }
+  if (kind === 'advisor_sessions' && 'sessions' in data) {
+    return [...styled('muted', `${data.sessions.length} active advisor consultations`), ...data.sessions.flatMap(entry => sessionLines(entry, options.expanded).flatMap(line => styled('toolOutput', line)))];
+  }
+  if (kind === 'advisor_close' && 'session' in data) return styled('muted', `Advisor consultation closed: ${label(data.session)}. Parent transcript remains.`);
+  return styled('muted', 'Advisor result details unavailable.');
+}
+export function toolRenderers(kind: Kind) {
+  return {
+    renderCall(args: object, theme: Theme): Component {
+      const session = 'session' in args ? args.session : undefined;
+      return component(width => [theme.fg('toolTitle', theme.bold(kind === 'advisor'
+        ? `Advisor • ${typeof session === 'string' ? `continue ${label(session)}` : 'new consultation'}`
+        : kind === 'advisor_sessions' ? 'Advisor • active consultations' : `Advisor • close ${label(session)}`)),
+        ...(kind === 'advisor' && 'message' in args && typeof args.message === 'string'
+          ? wrapTextWithAnsi(theme.fg('toolOutput', `Agent → advisor:\n${safe(args.message)}`), width) : [])]);
+    },
+    renderResult(result: { details?: unknown }, options: ToolRenderResultOptions, theme: Theme): Component {
+      return component(width => {
+        if (options.isPartial) {
+          const phase = (result.details as { phase?: Phase } | undefined)?.phase;
+          const text = phase === 'preparing' ? 'Advisor: preparing model…' : phase === 'waiting' ? 'Advisor: waiting for validated reply…' : 'Advisor request pending…';
+          return wrapTextWithAnsi(theme.fg('muted', text), width);
+        }
+        return resultLines(kind, details(result.details), options, theme, width);
+      });
+    }
+  };
+}

package/lib/replay.ts

@@ -0,0 +1,55 @@
+import type { AssistantMessage, TextContent, ThinkingContent } from '@earendil-works/pi-ai';
+import type { Selection } from './protocol.ts';
+
+export type Replay = { api: AssistantMessage['api']; content: (TextContent | ThinkingContent)[] };
+const responsesApis = new Set(['openai-responses', 'openai-codex-responses', 'azure-openai-responses']);
+const googleApis = new Set(['google-generative-ai', 'google-vertex']);
+const redactedApis = new Set(['anthropic-messages', 'bedrock-converse-stream']);
+// Optional metadata must not execute accessors, retain arbitrary fields, or invalidate advice.
+function own(value: unknown, key: string): unknown {
+  if (!value || typeof value !== 'object') return undefined;
+  try { return Object.getOwnPropertyDescriptor(value, key)?.value; } catch { return undefined; }
+}
+function nonempty(value: unknown): value is string { return typeof value === 'string' && value.length > 0; }
+function parsed(value: unknown): unknown {
+  if (typeof value !== 'string') return undefined;
+  try { return JSON.parse(value); } catch { return undefined; }
+}
+function reasoningSignature(value: unknown): string | undefined {
+  const item = parsed(value), id = own(item, 'id'), encrypted = own(item, 'encrypted_content');
+  if (own(item, 'type') !== 'reasoning' || !nonempty(id) || !nonempty(encrypted)) return undefined;
+  const status = own(item, 'status');
+  return JSON.stringify({ type: 'reasoning', id, encrypted_content: encrypted, summary: [],
+    ...(['completed', 'incomplete', 'in_progress'].includes(status as string) ? { status } : {}) });
+}
+function textSignature(value: unknown): string | undefined {
+  const signature = parsed(value), id = own(signature, 'id'), phase = own(signature, 'phase');
+  if (own(signature, 'v') !== 1 || typeof id !== 'string') return undefined;
+  return JSON.stringify({ v: 1, id, ...(phase === 'commentary' || phase === 'final_answer' ? { phase } : {}) });
+}
+function googleSignature(value: unknown): string | undefined {
+  return nonempty(value) && value.length % 4 === 0 && /^[A-Za-z0-9+/]+={0,2}$/.test(value) ? value : undefined;
+}
+
+// Called only after replyText validates the completion. Never keep the original reply.
+export function replay(message: AssistantMessage, model: Selection): Replay | undefined {
+  const api = own(message, 'api');
+  if (own(message, 'provider') !== model.provider || own(message, 'model') !== model.model || typeof api !== 'string') return undefined;
+  const responses = responsesApis.has(api), google = googleApis.has(api);
+  if (!responses && !google && !redactedApis.has(api)) return undefined;
+  const content: Replay['content'] = [];
+  for (const block of message.content) {
+    if (block.type === 'text') {
+      const text = own(block, 'text');
+      if (typeof text !== 'string') return undefined;
+      const signature = responses ? textSignature(own(block, 'textSignature')) : google ? googleSignature(own(block, 'textSignature')) : undefined;
+      content.push({ type: 'text', text, ...(signature ? { textSignature: signature } : {}) });
+    } else {
+      const signature = responses ? reasoningSignature(own(block, 'thinkingSignature'))
+        : google ? googleSignature(own(block, 'thinkingSignature'))
+        : own(block, 'redacted') === true && nonempty(own(block, 'thinkingSignature')) ? own(block, 'thinkingSignature') as string : undefined;
+      if (signature) content.push({ type: 'thinking', thinking: '', thinkingSignature: signature, ...(!responses && !google ? { redacted: true } : {}) });
+    }
+  }
+  return { api, content };
+}

package/lib/schemas.ts

@@ -0,0 +1,36 @@
+import { Type } from 'typebox';
+import { FAILURE_PHASES, FAILURE_CATEGORIES, REASONING_LEVELS } from './protocol.ts';
+const text = Type.String({ minLength: 1 });
+const object = { additionalProperties: false };
+export const ModelSchema = Type.Object({ provider: text, model: text, reasoning: Type.Optional(Type.Union(REASONING_LEVELS.map(level => Type.Literal(level)))) }, object);
+export const UsageSchema = Type.Object({ input: Type.Number(), output: Type.Number(), cacheRead: Type.Number(), cacheWrite: Type.Number(), totalTokens: Type.Number(), reasoning: Type.Optional(Type.Number()), cacheWrite1h: Type.Optional(Type.Number()), cost: Type.Object({ input: Type.Number(), output: Type.Number(), cacheRead: Type.Number(), cacheWrite: Type.Number(), total: Type.Number() }, object) }, object);
+const totals = { totalUsage: UsageSchema, totalUsageComplete: Type.Boolean() };
+export const ContextUsageSchema = Type.Object({ tokens: Type.Number({ minimum: 0 }), contextWindow: Type.Integer({ minimum: 1 }), percent: Type.Number({ minimum: 0 }) }, object);
+const LimitSchema = Type.Object({
+  resource: Type.Literal('context-tokens'),
+  maximum: Type.Integer({ minimum: 0 }), actual: Type.Integer({ minimum: 0 })
+}, object);
+export const DiagnosticsSchema = Type.Object({
+  phase: Type.Union(FAILURE_PHASES.map(s => Type.Literal(s))),
+  category: Type.Union(FAILURE_CATEGORIES.map(s => Type.Literal(s))),
+  code: Type.Optional(Type.Union([Type.Literal('sdk-invalid-timeout'), Type.Literal('tool-choice-without-tools')])),
+  httpStatus: Type.Optional(Type.Integer({ minimum: 400, maximum: 599 })),
+  model: Type.Optional(ModelSchema),
+  selectionSource: Type.Optional(Type.Union(['global', 'project', 'unknown'].map(s => Type.Literal(s))))
+}, object);
+const failure = {
+  ok: Type.Literal(false), error: Type.Object({ code: text, message: text, limit: Type.Optional(LimitSchema), diagnostics: Type.Optional(DiagnosticsSchema) }, object),
+  usage: UsageSchema, usageComplete: Type.Boolean(), session: Type.Optional(text), contextUsage: Type.Optional(ContextUsageSchema)
+};
+// Cumulative usage and its completeness indicator must appear together.
+export const FailureSchema = Type.Union([Type.Object(failure, object), Type.Object({ ...failure, ...totals }, object)]);
+export const InputSchema = Type.Object({ message: text, session: Type.Optional(text), diagnostics: Type.Optional(Type.Boolean({ description: 'Opt in for safe failure phase, category and selected model metadata. No raw provider errors. Does not retry.' })) }, object);
+export const CloseInputSchema = Type.Object({ session: text }, object);
+export const EmptyInputSchema = Type.Object({}, object);
+export const AdviceSchema = Type.Union([Type.Object({ ok: Type.Literal(true), advisory: Type.Literal(true), session: text, response: text, turns: Type.Integer({ minimum: 1 }), model: ModelSchema, usage: UsageSchema, usageComplete: Type.Boolean(), contextUsage: ContextUsageSchema, ...totals }, object), FailureSchema]);
+export const ListSchema = Type.Union([Type.Object({ ok: Type.Literal(true), sessions: Type.Array(Type.Object({
+  session: text, label: text, turns: Type.Integer({ minimum: 0 }), model: ModelSchema, busy: Type.Boolean(),
+  ...totals,
+  historyBytes: Type.Integer({ minimum: 0 }), contextUsage: ContextUsageSchema
+}, object)) }, object), FailureSchema]);
+export const CloseSchema = Type.Union([Type.Object({ ok: Type.Literal(true), session: text }, object), FailureSchema]);