pi-spark 0.1.0

package/extensions/shared/components/split-line.ts

@@ -0,0 +1,76 @@
+import { visibleWidth } from "@earendil-works/pi-tui";
+
+import { InlineText } from "./inline-text";
+
+import type { Component } from "@earendil-works/pi-tui";
+
+type Side = "left" | "right";
+
+interface SplitLineOptions {
+  padding?: number;
+  gap?: number;
+  innerPadding?: number;
+  primarySide?: Side;
+  spacingChar?: string;
+  ellipsis?: string;
+}
+
+const DEFAULT_SPLIT_LINE_OPTIONS: Required<SplitLineOptions> = {
+  padding: 0,
+  gap: 2,
+  innerPadding: 0,
+  primarySide: "left",
+  spacingChar: " ",
+  ellipsis: "…",
+};
+
+/** Single-line component that places left and right text at opposite sides. */
+export class SplitLine implements Component {
+  private left: InlineText;
+  private right: InlineText;
+
+  private padding: number;
+  private gap: number;
+  private primarySide: Side;
+  private spacingChar: string;
+
+  constructor(left: InlineText | string, right: InlineText | string, options: SplitLineOptions = {}) {
+    const spacingChar = options.spacingChar ?? DEFAULT_SPLIT_LINE_OPTIONS.spacingChar;
+    if (visibleWidth(spacingChar) !== 1) throw new Error("spacingChar must have a visible width of 1");
+
+    const inlineTextOptions = { padding: options.innerPadding ?? DEFAULT_SPLIT_LINE_OPTIONS.innerPadding, ellipsis: options.ellipsis ?? DEFAULT_SPLIT_LINE_OPTIONS.ellipsis };
+    this.left = typeof left === "string" ? new InlineText(left, inlineTextOptions) : left;
+    this.right = typeof right === "string" ? new InlineText(right, inlineTextOptions) : right;
+
+    this.padding = options.padding ?? DEFAULT_SPLIT_LINE_OPTIONS.padding;
+    this.gap = options.gap ?? DEFAULT_SPLIT_LINE_OPTIONS.gap;
+    this.primarySide = options.primarySide ?? DEFAULT_SPLIT_LINE_OPTIONS.primarySide;
+    this.spacingChar = spacingChar;
+  }
+
+  invalidate(): void {
+    // No-op
+  }
+
+  render(width: number): [string] {
+    const contentWidth = width - this.padding * 2;
+    const content = this.renderContent(contentWidth);
+    const paddingText = this.spacingChar.repeat(this.padding);
+
+    return [`${paddingText}${content}${paddingText}`];
+  }
+
+  private renderContent(width: number): string {
+    const [primary, secondary] = this.primarySide === "left" ? [this.left, this.right] : [this.right, this.left];
+
+    const renderedPrimary = primary.render(width)[0];
+    const renderedPrimaryWidth = visibleWidth(renderedPrimary);
+    const secondaryWidth = renderedPrimaryWidth > 0 ? width - renderedPrimaryWidth - this.gap : width;
+    const renderedSecondary = secondary.render(secondaryWidth)[0];
+
+    const [renderedLeft, renderedRight] = this.primarySide === "left" ? [renderedPrimary, renderedSecondary] : [renderedSecondary, renderedPrimary];
+    const spacingWidth = width - visibleWidth(renderedLeft) - visibleWidth(renderedRight);
+
+    return `${renderedLeft}${this.spacingChar.repeat(spacingWidth)}${renderedRight}`;
+  }
+}

package/extensions/shared/config/index.ts

@@ -0,0 +1,70 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+import { configSchemas } from "./schema";
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ConfigField, ConfigValue } from "./schema";
+
+type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
+type JsonObject = { [key: string]: JsonValue };
+
+export function loadConfig<Field extends ConfigField>(ctx: ExtensionContext, field: Field, fileName: string = "spark.json"): ConfigValue<Field> | undefined {
+  const rawConfig = loadMergedJson(getConfigPaths(ctx.cwd, fileName));
+  const rawValue = rawConfig?.[field];
+  if (rawValue === false) return undefined;
+
+  const result = configSchemas[field].safeParse(rawValue === true || rawValue === undefined ? {} : rawValue);
+  if (result.success) return result.data as ConfigValue<Field>;
+
+  const message = result.error.issues.map((issue) => `${[field, ...issue.path].join(".")}: ${issue.message}`).join("; ");
+  ctx.ui.notify(`Invalid spark config: ${message}`, "error");
+
+  return undefined;
+}
+
+function getConfigPaths(cwd: string, fileName: string): [globalPath: string, projectPath: string] {
+  return [join(getAgentDir(), fileName), join(cwd, ".pi", fileName)];
+}
+
+function loadMergedJson(paths: string[]): JsonObject | undefined {
+  let merged: JsonObject | undefined;
+  paths.forEach((path) => {
+    const value = readJsonFile(path);
+    if (value === undefined) return;
+
+    merged = mergeConfig(merged, value);
+  });
+
+  return merged;
+}
+
+function readJsonFile(path: string): JsonObject | undefined {
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as JsonObject;
+  } catch {
+    return undefined;
+  }
+}
+
+function mergeConfig(base: JsonObject | undefined, override: JsonObject): JsonObject {
+  if (base === undefined) return override;
+  if (!isPlainObject(base) || !isPlainObject(override)) return override;
+
+  const result: Record<string, JsonValue> = { ...base };
+  Object.entries(override).forEach(([key, overrideValue]) => {
+    const baseValue = base[key];
+    if (isPlainObject(baseValue) && isPlainObject(overrideValue)) {
+      result[key] = { ...baseValue, ...overrideValue };
+    } else {
+      result[key] = overrideValue;
+    }
+  });
+
+  return result;
+}
+
+function isPlainObject(value: unknown): value is Record<string, JsonValue> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}

package/extensions/shared/config/model.ts

@@ -0,0 +1,15 @@
+import * as z from "zod";
+
+import type { ModelThinkingLevel } from "@earendil-works/pi-ai";
+
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const satisfies readonly ModelThinkingLevel[];
+
+export const modelSchema = z.object({
+  provider: z.string().min(1),
+  model: z.string().min(1),
+  thinkingLevel: z.enum(THINKING_LEVELS),
+});
+
+export const optionalModelSchema = modelSchema.partial();
+
+export type OptionalModelConfig = z.infer<typeof optionalModelSchema>;

package/extensions/shared/config/schema.ts

@@ -0,0 +1,18 @@
+import * as z from "zod";
+
+import { editorConfigSchema } from "../../editor/config";
+import { footerConfigSchema } from "../../footer/config";
+import { fullscreenConfigSchema } from "../../fullscreen/config";
+import { recapConfigSchema } from "../../recap/config";
+import { presetsConfigSchema } from "../../presets/config";
+
+export const configSchemas = {
+  editor: editorConfigSchema,
+  footer: footerConfigSchema,
+  fullscreen: fullscreenConfigSchema,
+  recap: recapConfigSchema,
+  presets: presetsConfigSchema,
+};
+
+export type ConfigField = keyof typeof configSchemas;
+export type ConfigValue<Field extends ConfigField> = z.infer<(typeof configSchemas)[Field]>;

package/extensions/shared/events/auto-collect-events.ts

@@ -0,0 +1,40 @@
+import type { ExtensionAPI, EventBus } from "@earendil-works/pi-coding-agent";
+
+class EventCollector {
+  private pi: ExtensionAPI;
+  private collected: Set<() => void> = new Set();
+
+  constructor(pi: ExtensionAPI) {
+    this.pi = pi;
+  }
+
+  on(...args: Parameters<EventBus["on"]>): ReturnType<EventBus["on"]> {
+    const unsubscribe = this.pi.events.on(...args);
+    this.collected.add(unsubscribe);
+
+    return this.wrap(unsubscribe);
+  }
+
+  dispose(): void {
+    this.collected.forEach((unsubscribe) => unsubscribe());
+    this.collected.clear();
+  }
+
+  private wrap(unsubscribe: () => void): () => void {
+    return () => {
+      if (this.collected.delete(unsubscribe)) {
+        unsubscribe();
+      }
+    };
+  }
+}
+
+export function autoCollectEvents(pi: ExtensionAPI): EventCollector {
+  const collector = new EventCollector(pi);
+
+  pi.on("session_shutdown", () => {
+    collector.dispose();
+  });
+
+  return collector;
+}

package/extensions/shared/events/index.ts

@@ -0,0 +1,3 @@
+export { autoCollectEvents } from "./auto-collect-events";
+
+export * from "./preset";

package/extensions/shared/events/preset.ts

@@ -0,0 +1,9 @@
+import * as z from "zod";
+
+const presetChangePayloadSchema = z.string().min(1).optional();
+
+export const PRESET_CHANGE = "preset:change" as const;
+
+export function parsePresetChange(data: unknown): z.infer<typeof presetChangePayloadSchema> {
+  return presetChangePayloadSchema.parse(data);
+}

package/extensions/shared/format/index.ts

@@ -0,0 +1,35 @@
+import type { Provider } from "@earendil-works/pi-ai";
+import type { ContextUsage } from "@earendil-works/pi-coding-agent";
+
+export function formatModel(provider?: Provider, model?: string, thinkingLevel?: string): string {
+  return provider && model ? `${provider}/${model}${thinkingLevel ? `:${thinkingLevel}` : ""}` : "no-model";
+}
+
+export function formatTokens(count: number): string {
+  if (count < 1_000) return count.toString();
+  if (count < 10_000) return `${(count / 1_000).toFixed(1)}K`;
+  if (count < 1_000_000) return `${Math.round(count / 1_000)}K`;
+  if (count < 10_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+  return `${Math.round(count / 1_000_000)}M`;
+}
+
+export function formatContextUsage(contextUsage: ContextUsage | undefined): string {
+  const tokens = contextUsage?.tokens ?? null;
+  const contextWindow = contextUsage?.contextWindow ?? null;
+  const percent = contextUsage?.percent ?? null;
+  const percentText = percent === null ? "?" : `${percent.toFixed(1)}%`;
+
+  return `${tokens === null ? "?" : formatTokens(tokens)}/${contextWindow === null ? "?" : formatTokens(contextWindow)} (${percentText})`;
+}
+
+export function formatCost(cost: number, isSubscription: boolean): string {
+  return `$${cost.toFixed(2)}${isSubscription ? " (sub)" : ""}`;
+}
+
+/** Replace newlines, tabs, carriage returns with space, then collapse multiple spaces */
+export function sanitizeText(text: string): string {
+  return text
+    .replace(/[\r\n\t]/g, " ")
+    .replace(/ +/g, " ")
+    .trim();
+}

package/extensions/shared/usage/index.ts

@@ -0,0 +1,79 @@
+import type { Usage } from "@earendil-works/pi-ai";
+import type { ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+
+/** Structural type guard for the pi `Usage` shape. */
+export function isUsage(value: unknown): value is Usage {
+  if (typeof value !== "object" || value === null) return false;
+
+  const usage = value as Record<string, unknown>;
+  const hasTokenFields =
+    typeof usage.input === "number" &&
+    typeof usage.output === "number" &&
+    typeof usage.cacheRead === "number" &&
+    typeof usage.cacheWrite === "number" &&
+    typeof usage.totalTokens === "number";
+  if (!hasTokenFields) return false;
+
+  if (typeof usage.cost !== "object" || usage.cost === null) return false;
+  const cost = usage.cost as Record<string, unknown>;
+  return (
+    typeof cost.input === "number" &&
+    typeof cost.output === "number" &&
+    typeof cost.cacheRead === "number" &&
+    typeof cost.cacheWrite === "number" &&
+    typeof cost.total === "number"
+  );
+}
+
+/** Sum two `Usage` values into a new one. */
+export function addUsage(a: Usage, b: Usage): Usage {
+  return {
+    input: a.input + b.input,
+    output: a.output + b.output,
+    cacheRead: a.cacheRead + b.cacheRead,
+    cacheWrite: a.cacheWrite + b.cacheWrite,
+    totalTokens: a.totalTokens + b.totalTokens,
+    cost: {
+      input: a.cost.input + b.cost.input,
+      output: a.cost.output + b.cost.output,
+      cacheRead: a.cost.cacheRead + b.cost.cacheRead,
+      cacheWrite: a.cost.cacheWrite + b.cost.cacheWrite,
+      total: a.cost.total + b.cost.total,
+    },
+  };
+}
+
+/**
+ * Extract usage from a session entry, classifying it as subscription or paid.
+ *
+ * `usage`/`provider`/`model` live in different fields depending on the entry type:
+ *
+ * - `message` carries them on `.message`
+ * - `custom` on `.data`
+ * - `custom_message` on `.details`.
+ *
+ * Other entry types carry no usage. Returns `undefined` when the resolved field has no `usage`.
+ *
+ * An entry counts as subscription only when its `provider`/`model` resolve to an OAuth model in the
+ * registry; everything else (including entries without `provider`/`model`) is treated as paid.
+ */
+export function getEntryUsage(ctx: ExtensionContext, entry: SessionEntry): { type: "subscription" | "paid"; usage: Usage } | undefined {
+  let source: unknown;
+  if (entry.type === "message") source = entry.message;
+  else if (entry.type === "custom") source = entry.data;
+  else if (entry.type === "custom_message") source = entry.details;
+  else return;
+
+  if (typeof source !== "object" || source === null) return;
+  const data = source as { usage?: unknown; provider?: unknown; model?: unknown };
+  if (!isUsage(data.usage)) return;
+
+  const type = isSubscription(ctx, data.provider, data.model) ? "subscription" : "paid";
+  return { type, usage: data.usage };
+}
+
+function isSubscription(ctx: ExtensionContext, provider: unknown, model: unknown): boolean {
+  if (typeof provider !== "string" || typeof model !== "string") return false;
+  const resolved = ctx.modelRegistry.find(provider, model);
+  return resolved ? ctx.modelRegistry.isUsingOAuth(resolved) : false;
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "pi-spark",
+  "version": "0.1.0",
+  "description": "A small, opinionated collection of pi extensions",
+  "keywords": [
+    "pi-coding-agent",
+    "pi-package"
+  ],
+  "homepage": "https://github.com/zlliang/pi-spark#readme",
+  "bugs": {
+    "url": "https://github.com/zlliang/pi-spark/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zlliang/pi-spark.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "extensions",
+    "assets",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": ["./extensions"],
+    "image": "https://raw.githubusercontent.com/zlliang/pi-spark/main/assets/cover.png"
+  },
+  "scripts": {
+    "start": "pi --no-extensions --extension ~/.pi/agent --extension $PWD",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@types/node": "*",
+    "typebox": "*",
+    "typescript": "^6.0.3"
+  }
+}