@monotykamary/pi-better-grok 0.1.0

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@monotykamary/pi-better-grok",
+  "version": "0.1.0",
+  "description": "Improve Grok/xAI in pi with fast mode, subscription usage stats, footer polish, and settings — mirroring pi-better-openai.",
+  "keywords": [
+    "footer",
+    "grok",
+    "pi",
+    "pi-extension",
+    "pi-package",
+    "supergrok",
+    "usage",
+    "xai"
+  ],
+  "homepage": "https://github.com/monotykamary/pi-better-grok#readme",
+  "bugs": {
+    "url": "https://github.com/monotykamary/pi-better-grok/issues"
+  },
+  "license": "MIT",
+  "author": "monotykamary",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/monotykamary/pi-better-grok.git"
+  },
+  "files": [
+    "index.ts",
+    "src/",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@earendil-works/pi-tui": "0.84.4",
+    "@types/node": "~22.19.0",
+    "oxfmt": "^0.47.0",
+    "oxlint": "^1.62.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "scripts": {
+    "check": "pnpm run typecheck && pnpm run lint && pnpm run format:check && pnpm test",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "lint": "oxlint --deny-warnings index.ts src/*.ts tests/*.ts",
+    "lint:fix": "oxlint --fix index.ts src/*.ts tests/*.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/config.ts

@@ -0,0 +1,314 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { CONFIG_BASENAME, logPrefix } from "./identity.ts";
+import { piAgentDir } from "./paths.ts";
+
+export const FOOTER_MODES = ["replace", "status", "off"] as const;
+export const FAST_EFFORTS = ["low", "medium", "high"] as const;
+
+export const DEFAULT_SUPPORTED_MODELS = [
+  "xai/grok-4.6",
+  "xai/grok-4.5",
+  "xai-oauth/grok-4.6",
+  "xai-oauth/grok-4.5",
+  "grok-build/grok-4.6",
+  "grok-build/grok-4.5",
+] as const;
+
+export type FooterMode = (typeof FOOTER_MODES)[number];
+export type FastEffort = (typeof FAST_EFFORTS)[number];
+
+export type FastConfig = { effort?: FastEffort };
+export type UsageConfig = {
+  enabled?: boolean;
+  refreshIntervalMs?: number;
+  showOnlyOnSubscriptionModels?: boolean;
+  showResetTimes?: boolean;
+};
+export type FooterConfig = { mode?: FooterMode };
+
+export interface ConfigFile {
+  persistState?: boolean;
+  active?: boolean;
+  desiredActive?: boolean;
+  supportedModels?: string[];
+  fast?: FastConfig;
+  usage?: UsageConfig;
+  footer?: FooterConfig;
+}
+
+export interface SupportedModel {
+  provider: string;
+  id: string;
+}
+
+export interface ResolvedConfig {
+  configPath: string;
+  projectConfigPath: string;
+  globalConfigPath: string;
+  projectConfigExists: boolean;
+  globalConfigExists: boolean;
+  persistState: boolean;
+  active: boolean;
+  desiredActive: boolean;
+  supportedModels: SupportedModel[];
+  fast: Required<FastConfig>;
+  usage: Required<UsageConfig>;
+  footer: Required<FooterConfig>;
+}
+
+export const DEFAULT_FAST_CONFIG: Required<FastConfig> = { effort: "low" };
+export const DEFAULT_USAGE_CONFIG: Required<UsageConfig> = {
+  enabled: true,
+  refreshIntervalMs: 60_000,
+  showOnlyOnSubscriptionModels: true,
+  showResetTimes: true,
+};
+export const DEFAULT_FOOTER_CONFIG: Required<FooterConfig> = { mode: "status" };
+export const DEFAULT_CONFIG: ConfigFile = {
+  persistState: true,
+  active: false,
+  desiredActive: false,
+  supportedModels: [...DEFAULT_SUPPORTED_MODELS],
+  fast: DEFAULT_FAST_CONFIG,
+  usage: DEFAULT_USAGE_CONFIG,
+  footer: DEFAULT_FOOTER_CONFIG,
+};
+
+type SettingsOptionSection = "footer" | "usage" | "fast";
+
+export type SettingsOptionDescriptor = {
+  id: string;
+  section: SettingsOptionSection;
+  key: string;
+  label: string;
+  description: string;
+  values?: readonly string[];
+  parse(rawValue: string): boolean | number | string;
+  current(config: ResolvedConfig): string;
+};
+
+function asBoolean(value: unknown, fallback: boolean): boolean {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+function asNumberInRange(value: unknown, fallback: number, min: number, max: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.min(max, Math.max(min, Math.round(value)));
+}
+
+function asEnum<T extends string>(value: unknown, allowed: readonly T[], fallback: T): T {
+  return typeof value === "string" && (allowed as readonly string[]).includes(value)
+    ? (value as T)
+    : fallback;
+}
+
+export function parseModelKey(key: string): SupportedModel | undefined {
+  const separator = key.indexOf("/");
+  if (separator <= 0 || separator === key.length - 1) return undefined;
+  const provider = key.slice(0, separator).trim();
+  const id = key.slice(separator + 1).trim();
+  if (!provider || !id) return undefined;
+  return { provider, id };
+}
+
+export function parseModels(value: unknown): SupportedModel[] {
+  const entries = Array.isArray(value) ? value : [...DEFAULT_SUPPORTED_MODELS];
+  const models: SupportedModel[] = [];
+  for (const entry of entries) {
+    if (typeof entry !== "string") continue;
+    const model = parseModelKey(entry);
+    if (model) models.push(model);
+  }
+  return models;
+}
+
+export function normalizeModelKeys(models: SupportedModel[]): string[] {
+  return models.map((model) => `${model.provider}/${model.id}`);
+}
+
+function mergedSection<T extends object>(
+  fallback: T,
+  globalValue: unknown,
+  projectValue: unknown,
+): Required<T> {
+  const global = globalValue && typeof globalValue === "object" ? globalValue : {};
+  const project = projectValue && typeof projectValue === "object" ? projectValue : {};
+  return { ...fallback, ...global, ...project } as Required<T>;
+}
+
+export const FOOTER_SETTING_DESCRIPTORS: SettingsOptionDescriptor[] = [
+  {
+    id: "footer.mode",
+    section: "footer",
+    key: "mode",
+    label: "Footer mode",
+    description: "replace: custom footer. status: status line widget. off: hide.",
+    values: FOOTER_MODES,
+    parse: (rawValue) => asEnum(rawValue, FOOTER_MODES, DEFAULT_FOOTER_CONFIG.mode),
+    current: (config) => config.footer.mode,
+  },
+];
+
+export const USAGE_SETTING_DESCRIPTORS: SettingsOptionDescriptor[] = [
+  {
+    id: "usage.enabled",
+    section: "usage",
+    key: "enabled",
+    label: "Usage display",
+    description: "Show Grok subscription usage in the footer.",
+    values: ["true", "false"],
+    parse: (rawValue) => rawValue === "true",
+    current: (config) => String(config.usage.enabled),
+  },
+  {
+    id: "usage.refreshIntervalMs",
+    section: "usage",
+    key: "refreshIntervalMs",
+    label: "Usage refresh interval",
+    description: "How often to poll Grok billing (milliseconds).",
+    values: ["30000", "60000", "120000", "300000"],
+    parse: (rawValue) =>
+      asNumberInRange(Number(rawValue), DEFAULT_USAGE_CONFIG.refreshIntervalMs, 5_000, 3_600_000),
+    current: (config) => String(config.usage.refreshIntervalMs),
+  },
+  {
+    id: "usage.showOnlyOnSubscriptionModels",
+    section: "usage",
+    key: "showOnlyOnSubscriptionModels",
+    label: "Only on subscription models",
+    description: "Hide usage unless the current model uses xAI OAuth.",
+    values: ["true", "false"],
+    parse: (rawValue) => rawValue === "true",
+    current: (config) => String(config.usage.showOnlyOnSubscriptionModels),
+  },
+  {
+    id: "usage.showResetTimes",
+    section: "usage",
+    key: "showResetTimes",
+    label: "Show reset times",
+    description: "Append the billing period reset countdown to the usage line.",
+    values: ["true", "false"],
+    parse: (rawValue) => rawValue === "true",
+    current: (config) => String(config.usage.showResetTimes),
+  },
+];
+
+export const FAST_SETTING_DESCRIPTORS: SettingsOptionDescriptor[] = [
+  {
+    id: "fast.effort",
+    section: "fast",
+    key: "effort",
+    label: "Fast effort",
+    description: "reasoning_effort injected while fast mode is enabled.",
+    values: FAST_EFFORTS,
+    parse: (rawValue) => asEnum(rawValue, FAST_EFFORTS, DEFAULT_FAST_CONFIG.effort),
+    current: (config) => config.fast.effort,
+  },
+];
+
+export const SETTINGS_OPTION_DESCRIPTORS: SettingsOptionDescriptor[] = [
+  ...FOOTER_SETTING_DESCRIPTORS,
+  ...USAGE_SETTING_DESCRIPTORS,
+  ...FAST_SETTING_DESCRIPTORS,
+];
+
+export const SETTINGS_OPTION_BY_ID = new Map(
+  SETTINGS_OPTION_DESCRIPTORS.map((descriptor) => [descriptor.id, descriptor]),
+);
+
+export type SettingPatchContext = {
+  persistState?: boolean;
+  active?: boolean;
+  desiredActive?: boolean;
+};
+
+export function applySettingToRawConfig(
+  current: Record<string, unknown>,
+  id: string,
+  rawValue: string,
+  context: SettingPatchContext = {},
+): Record<string, unknown> {
+  const next: Record<string, unknown> = { ...current };
+  if (id === "fast.enabled") {
+    const bool = rawValue === "true";
+    if (context.persistState) {
+      next.active = context.active ?? bool;
+      next.desiredActive = context.desiredActive ?? bool;
+    }
+    return next;
+  }
+  const descriptor = SETTINGS_OPTION_BY_ID.get(id);
+  if (!descriptor) return next;
+  const parsedValue = descriptor.parse(rawValue);
+  const currentSection = next[descriptor.section];
+  const section =
+    currentSection && typeof currentSection === "object" && !Array.isArray(currentSection)
+      ? { ...(currentSection as Record<string, unknown>) }
+      : {};
+  section[descriptor.key] = parsedValue;
+  next[descriptor.section] = section;
+  return next;
+}
+
+export function configPaths(cwd: string, home = homedir(), env = process.env) {
+  return {
+    project: join(cwd, ".pi", "extensions", CONFIG_BASENAME),
+    global: join(piAgentDir(env, home), "extensions", CONFIG_BASENAME),
+  };
+}
+
+export function readRawConfig(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : {};
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`${logPrefix()} Failed to read ${path}: ${message}`);
+    return {};
+  }
+}
+
+export function writeConfig(path: string, config: ConfigFile | Record<string, unknown>): void {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`${logPrefix()} Failed to write ${path}: ${message}`);
+  }
+}
+
+function firstDefined(
+  globalRaw: Record<string, unknown>,
+  projectRaw: Record<string, unknown>,
+  key: string,
+): unknown {
+  if (globalRaw[key] !== undefined) return globalRaw[key];
+  return projectRaw[key];
+}
+
+export function resolveConfig(cwd: string, home = homedir(), env = process.env): ResolvedConfig {
+  const paths = configPaths(cwd, home, env);
+  const projectRaw = readRawConfig(paths.project);
+  const globalRaw = readRawConfig(paths.global);
+  const projectHasContent = Object.keys(projectRaw).length > 0;
+  return {
+    configPath: projectHasContent ? paths.project : paths.global,
+    projectConfigPath: paths.project,
+    globalConfigPath: paths.global,
+    projectConfigExists: existsSync(paths.project),
+    globalConfigExists: existsSync(paths.global),
+    persistState: asBoolean(firstDefined(globalRaw, projectRaw, "persistState"), true),
+    active: asBoolean(firstDefined(globalRaw, projectRaw, "active"), false),
+    desiredActive: asBoolean(firstDefined(globalRaw, projectRaw, "desiredActive"), false),
+    supportedModels: parseModels(firstDefined(globalRaw, projectRaw, "supportedModels")),
+    fast: mergedSection(DEFAULT_FAST_CONFIG, globalRaw.fast, projectRaw.fast),
+    usage: mergedSection(DEFAULT_USAGE_CONFIG, globalRaw.usage, projectRaw.usage),
+    footer: mergedSection(DEFAULT_FOOTER_CONFIG, globalRaw.footer, projectRaw.footer),
+  };
+}

package/src/fast-controller.ts

@@ -0,0 +1,82 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ResolvedConfig, SupportedModel } from "./config.ts";
+
+export function currentModelKey(ctx: Pick<ExtensionContext, "model">): string | undefined {
+  const model = ctx.model;
+  if (!model?.provider || !model.id) return undefined;
+  return `${model.provider}/${model.id}`;
+}
+
+export function modelList(models: SupportedModel[]): string {
+  return models.map((model) => `${model.provider}/${model.id}`).join(", ");
+}
+
+export function supportsFast(
+  ctx: Pick<ExtensionContext, "model">,
+  supportedModels: SupportedModel[],
+): boolean {
+  const key = currentModelKey(ctx);
+  return (
+    key !== undefined && supportedModels.some((model) => `${model.provider}/${model.id}` === key)
+  );
+}
+
+export class FastController {
+  active = false;
+  desiredActive = false;
+
+  setDesired(ctx: Pick<ExtensionContext, "model">, config: ResolvedConfig, next: boolean): void {
+    this.desiredActive = next;
+    this.applyDesiredState(ctx, config);
+  }
+
+  applyDesiredState(ctx: Pick<ExtensionContext, "model">, config: ResolvedConfig): void {
+    this.active = this.desiredActive && supportsFast(ctx, config.supportedModels);
+  }
+
+  initializeForSession(
+    ctx: Pick<ExtensionContext, "model">,
+    config: ResolvedConfig,
+    flagEnabled: boolean,
+  ): void {
+    this.desiredActive = flagEnabled || (config.persistState ? config.desiredActive : false);
+    this.applyDesiredState(ctx, config);
+  }
+
+  injectProviderPayload(
+    event: { payload?: unknown },
+    ctx: Pick<ExtensionContext, "model">,
+    config: ResolvedConfig,
+  ): Record<string, unknown> | undefined {
+    if (!this.active || !supportsFast(ctx, config.supportedModels)) return undefined;
+    if (!event?.payload || typeof event.payload !== "object" || Array.isArray(event.payload)) {
+      return undefined;
+    }
+    return { ...(event.payload as Record<string, unknown>), reasoning_effort: config.fast.effort };
+  }
+
+  statusSegment(ctx: Pick<ExtensionContext, "model">, config: ResolvedConfig): string | undefined {
+    return this.active && supportsFast(ctx, config.supportedModels) ? "fast" : undefined;
+  }
+
+  stateText(config: ResolvedConfig): string {
+    return `Fast mode enabled (reasoning_effort=${config.fast.effort})`;
+  }
+
+  unsupportedRequestMessage(ctx: Pick<ExtensionContext, "model">, config: ResolvedConfig): string {
+    return `Fast mode unavailable for ${currentModelKey(ctx) ?? "current model"}. Supported: ${modelList(config.supportedModels)}`;
+  }
+
+  inactiveForModelMessage(ctx: Pick<ExtensionContext, "model">): string {
+    return `Fast mode inactive for ${currentModelKey(ctx) ?? "current model"}.`;
+  }
+
+  debugLines(ctx: Pick<ExtensionContext, "model">, config: ResolvedConfig): string[] {
+    return [
+      `Fast desired: ${this.desiredActive}`,
+      `Fast active: ${this.active}`,
+      `Fast eligible: ${supportsFast(ctx, config.supportedModels)}`,
+      `Fast effort: ${config.fast.effort}`,
+    ];
+  }
+}

package/src/format.ts

@@ -0,0 +1,66 @@
+import {
+  truncateToWidth as truncateTerminalText,
+  visibleWidth as terminalVisibleWidth,
+} from "@earendil-works/pi-tui";
+
+const ANSI_ESCAPE_PATTERN = String.raw`\u001B\[[0-?]*[ -/]*[@-~]`;
+const ANSI_ESCAPE_REGEXP = new RegExp(ANSI_ESCAPE_PATTERN, "g");
+const DIAGNOSTIC_MAX_LENGTH = 500;
+
+function replaceControlCharacters(value: string): string {
+  let result = "";
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    result += code <= 31 || (code >= 127 && code <= 159) ? " " : char;
+  }
+  return result;
+}
+
+export function stripAnsi(value: string): string {
+  return value.replace(ANSI_ESCAPE_REGEXP, "");
+}
+
+export function visibleWidth(value: string): number {
+  return terminalVisibleWidth(value);
+}
+
+export function truncateToWidth(value: string, width: number, ellipsis = "..."): string {
+  return truncateTerminalText(value, width, ellipsis);
+}
+
+export function formatTokens(count: number): string {
+  if (count < 1000) return count.toString();
+  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`;
+}
+
+export function sanitizeStatusText(text: string): string {
+  return text.replace(/[ \r\n\t]+/g, " ").trim();
+}
+
+export function maskIdentifier(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) return undefined;
+  if (trimmed.length <= 8) return "found";
+  return `${trimmed.slice(0, 4)}...${trimmed.slice(-4)}`;
+}
+
+export function sanitizeDiagnosticError(
+  message: string,
+  maxLength = DIAGNOSTIC_MAX_LENGTH,
+): string {
+  const redactedSecrets = stripAnsi(message)
+    .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED]")
+    .replace(/\bsk-[A-Za-z0-9_-]{8,}\b/g, "sk-[REDACTED]")
+    .replace(
+      /(["']?(?:access|access_token|token|api[_-]?key|authorization|accountId|account_id|userId|user_id|refresh)["']?\s*[:=]\s*["']?)([^"',\s}\]]+)/gi,
+      "$1[REDACTED]",
+    )
+    .replace(/\[REDACTED\](?:\])+/g, "[REDACTED]");
+  const redacted = replaceControlCharacters(redactedSecrets).replace(/ +/g, " ").trim();
+  const sanitized = redacted || "Unknown error.";
+  if (sanitized.length <= maxLength) return sanitized;
+  return `${sanitized.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
+}