pi-spark 0.1.0

package/extensions/presets/manager.ts

@@ -0,0 +1,113 @@
+import { PRESET_CHANGE } from "../shared/events";
+import { formatModel } from "../shared/format";
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { PresetsConfig, PresetConfig } from "./config";
+
+export class PresetManager {
+  private pi: ExtensionAPI;
+  private presets: PresetsConfig;
+  private active: string | undefined = undefined;
+
+  constructor(pi: ExtensionAPI, presets: PresetsConfig) {
+    this.pi = pi;
+    this.presets = presets;
+  }
+
+  get keys(): string[] {
+    return Object.keys(this.presets);
+  }
+
+  isActive(ctx: ExtensionContext, key: string): boolean {
+    const current = this.getCurrentPreset(ctx);
+    return key === this.findKey(current);
+  }
+
+  sync(ctx: ExtensionContext): void {
+    const current = this.getCurrentPreset(ctx);
+    const currentKey = this.findKey(current);
+    if (currentKey === this.active) return;
+
+    this.active = currentKey;
+    this.pi.events.emit(PRESET_CHANGE, this.active);
+  }
+
+  async apply(key: string, ctx: ExtensionContext): Promise<boolean> {
+    const preset = this.presets[key];
+    if (!preset) {
+      ctx.ui.notify(`Unknown preset ${key}`, "error");
+      return false;
+    }
+
+    const model = ctx.modelRegistry.find(preset.provider, preset.model);
+    if (!model) {
+      ctx.ui.notify(`Preset ${key}: model ${preset.provider}/${preset.model} not found`, "error");
+      return false;
+    }
+
+    const success = await this.pi.setModel(model);
+    if (!success) {
+      ctx.ui.notify(`Preset ${key}: no API key for ${preset.provider}/${preset.model}`, "error");
+      return false;
+    }
+
+    this.pi.setThinkingLevel(preset.thinkingLevel);
+
+    this.active = this.findKey({
+      provider: model.provider,
+      model: model.id,
+      thinkingLevel: this.pi.getThinkingLevel(),
+    });
+    this.pi.events.emit(PRESET_CHANGE, this.active);
+
+    if (this.active === key) {
+      ctx.ui.notify(`Preset: ${key} (${this.describe(key)})`, "info");
+    } else {
+      ctx.ui.notify(`Preset ${key}: thinking level ${preset.thinkingLevel} was clamped to ${this.pi.getThinkingLevel()}`, "warning");
+    }
+
+    return true;
+  }
+
+  async cycle(ctx: ExtensionContext, direction: "forward" | "backward"): Promise<void> {
+    if (this.keys.length === 0) {
+      ctx.ui.notify("No presets defined in spark.json", "warning");
+      return;
+    }
+
+    const current = this.getCurrentPreset(ctx);
+    const currentKey = this.findKey(current);
+    const currentIndex = currentKey ? this.keys.indexOf(currentKey) : -1;
+    const step = direction === "forward" ? 1 : -1;
+    const nextIndex = currentIndex === -1 ? direction === "forward" ? 0 : this.keys.length - 1 : (currentIndex + step + this.keys.length) % this.keys.length;
+    const nextKey = this.keys[nextIndex];
+    if (!nextKey) return;
+
+    await this.apply(nextKey, ctx);
+  }
+
+  describe(key: string): string {
+    const preset = this.presets[key];
+    return preset ? formatModel(preset.provider, preset.model, preset.thinkingLevel) : "";
+  }
+
+  private findKey(preset: PresetConfig | undefined): string | undefined {
+    if (!preset) return;
+
+    return this.keys.find((key) => {
+      const p = this.presets[key]!;
+
+      return p.provider === preset.provider && p.model === preset.model && p.thinkingLevel === preset.thinkingLevel;
+    });
+  }
+
+  private getCurrentPreset(ctx: ExtensionContext): PresetConfig | undefined {
+    if (!ctx.model) return undefined;
+
+    return {
+      provider: ctx.model.provider,
+      model: ctx.model.id,
+      thinkingLevel: this.pi.getThinkingLevel(),
+    };
+  }
+}

package/extensions/presets/selector.ts

@@ -0,0 +1,55 @@
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import { Container, SelectList, Spacer, Text } from "@earendil-works/pi-tui";
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { PresetManager } from "./manager";
+
+export async function showPresetSelector(ctx: ExtensionContext, presetManager: PresetManager): Promise<string | undefined> {
+  if (presetManager.keys.length === 0) {
+    ctx.ui.notify("No presets defined in spark.json", "warning");
+    return undefined;
+  }
+
+  const selected = await ctx.ui.custom<string | null>((tui, theme, _keybindings, done) => {
+    const items = presetManager.keys
+      .toSorted((a, b) => Number(presetManager.isActive(ctx, b)) - Number(presetManager.isActive(ctx, a)))
+      .map((key) => ({
+        value: key,
+        label: presetManager.isActive(ctx, key) ? `${key} ${theme.fg("success", "✓")} ` : key,
+        description: presetManager.describe(key),
+      }));
+
+    const container = new Container();
+
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.bold("Select preset"), 0, 0));
+    container.addChild(new Text(theme.fg("dim", "↑↓ navigate · enter select · esc cancel"), 0, 0));
+    container.addChild(new Spacer(1));
+
+    const selectList = new SelectList(items, 10, {
+      selectedPrefix: (text) => theme.fg("accent", text),
+      selectedText: (text) => theme.fg("accent", text),
+      description: (text) => theme.fg("muted", text),
+      scrollInfo: (text) => theme.fg("dim", text),
+      noMatch: (text) => theme.fg("warning", text),
+    });
+    selectList.onSelect = (item) => done(item.value);
+    selectList.onCancel = () => done(null);
+    container.addChild(selectList);
+
+    container.addChild(new Spacer(1));
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+    return {
+      render: (width: number) => container.render(width),
+      invalidate: () => container.invalidate(),
+      handleInput: (data: string) => {
+        selectList.handleInput(data);
+        tui.requestRender();
+      },
+    };
+  });
+
+  return selected ?? undefined;
+}

package/extensions/recap/config.ts

@@ -0,0 +1,10 @@
+import * as z from "zod";
+
+import { idleTimeoutSchema } from "./idle";
+import { optionalModelSchema } from "../shared/config/model";
+
+export const recapConfigSchema = optionalModelSchema.extend({
+  idle: idleTimeoutSchema.optional(),
+});
+
+export type RecapConfig = z.infer<typeof recapConfigSchema>;

package/extensions/recap/idle.ts

@@ -0,0 +1,106 @@
+import * as z from "zod";
+
+export const idleTimeoutSchema = z.number().min(5000);
+
+type IdleTimeout = z.infer<typeof idleTimeoutSchema>;
+type IdleHash = string | number | boolean;
+
+const DEFAULT_IDLE_MS = 3 * 60 * 1000;
+const POLL_MS = 1_000;
+
+export class IdleListener<T> {
+  private state: "active" | "watching" | "idle" = "active";
+  private computeStateHash: (ctx: T) => IdleHash;
+  private lastStateHash: IdleHash | undefined;
+
+  private idleMs: number;
+  private pollMs: number;
+  private idleTimer: ReturnType<typeof setTimeout> | undefined;
+  private pollTimer: ReturnType<typeof setInterval> | undefined;
+
+  private enterCallbacks: Set<(ctx: T) => void> = new Set();
+  private wakeCallbacks: Set<(ctx: T) => void> = new Set();
+
+  constructor(computeStateHash: (ctx: T) => IdleHash, idleMs: IdleTimeout = DEFAULT_IDLE_MS, pollMs: number = POLL_MS) {
+    this.computeStateHash = computeStateHash;
+    this.idleMs = idleMs;
+    this.pollMs = pollMs;
+  }
+
+  on(event: "enter" | "wake", callback: (ctx: T) => void): () => void {
+    const callbackSet = event === "enter" ? this.enterCallbacks : this.wakeCallbacks;
+    callbackSet.add(callback);
+
+    return () => callbackSet.delete(callback);
+  }
+
+  watch(ctx: T): void {
+    if (this.state === "idle") return;
+
+    this.stop();
+    this.state = "watching";
+
+    this.lastStateHash = this.computeStateHash(ctx);
+    this.reset(ctx);
+
+    this.pollTimer = setInterval(() => {
+      const current = this.computeStateHash(ctx);
+      if (current === this.lastStateHash) return;
+
+      this.lastStateHash = current;
+      this.reset(ctx);
+    }, this.pollMs);
+  }
+
+  enter(ctx: T): void {
+    if (this.state === "idle") return;
+
+    this.stop();
+    this.state = "idle";
+
+    this.enterCallbacks.forEach((callback) => callback(ctx));
+  }
+
+  /** Emit on every wake signal, even when the listener is already active. */
+  wake(ctx: T): void {
+    this.stop();
+    this.state = "active";
+
+    this.wakeCallbacks.forEach((callback) => callback(ctx));
+  }
+
+  dispose(): void {
+    this.stop();
+    this.state = "active";
+
+    this.enterCallbacks.clear();
+    this.wakeCallbacks.clear();
+  }
+
+  private reset(ctx: T): void {
+    this.clearIdleTimer();
+    this.idleTimer = setTimeout(() => {
+      this.idleTimer = undefined;
+      this.enter(ctx);
+    }, this.idleMs);
+  }
+
+  private stop(): void {
+    this.clearIdleTimer();
+    this.clearPollTimer();
+  }
+
+  private clearIdleTimer(): void {
+    if (!this.idleTimer) return;
+
+    clearTimeout(this.idleTimer);
+    this.idleTimer = undefined;
+  }
+
+  private clearPollTimer(): void {
+    if (!this.pollTimer) return;
+
+    clearInterval(this.pollTimer);
+    this.pollTimer = undefined;
+  }
+}

package/extensions/recap/index.ts

@@ -0,0 +1,72 @@
+import { IdleListener } from "./idle";
+import { RecapManager } from "./manager";
+import { loadConfig } from "../shared/config";
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+  let idleListener: IdleListener<ExtensionContext> | undefined = undefined;
+  let recapManager: RecapManager | undefined = undefined;
+
+  pi.on("session_start", (event, ctx) => {
+    if (!ctx.hasUI) return;
+
+    const config = loadConfig(ctx, "recap");
+    if (!config) return;
+
+    recapManager = new RecapManager(pi, config);
+
+    pi.registerCommand("recap", {
+      description: "Generate a short recap of the current session",
+      handler: async () => await recapManager?.run(ctx, { force: true }),
+    });
+
+    idleListener = new IdleListener((c) => `idle:${c.isIdle()};editor:${c.ui.getEditorText()}`, config.idle);
+    idleListener.on("enter", (c) => recapManager?.run(c));
+    idleListener.on("wake", (c) => recapManager?.clear(c));
+
+    if (event.reason === "resume" || event.reason === "fork") {
+      idleListener.watch(ctx);
+    }
+  });
+
+  pi.on("input", (_event, ctx) => {
+    idleListener?.wake(ctx);
+  });
+
+  pi.on("user_bash", (_event, ctx) => {
+    idleListener?.wake(ctx);
+  });
+
+  pi.on("agent_start", (_event, ctx) => {
+    idleListener?.wake(ctx);
+  });
+
+  pi.on("session_before_compact", (_event, ctx) => {
+    idleListener?.wake(ctx);
+  });
+
+  pi.on("session_before_tree", (_event, ctx) => {
+    idleListener?.wake(ctx);
+  });
+
+  pi.on("agent_end", (_event, ctx) => {
+    idleListener?.watch(ctx);
+  });
+
+  pi.on("session_compact", (_event, ctx) => {
+    idleListener?.watch(ctx);
+  });
+
+  pi.on("session_tree", (_event, ctx) => {
+    idleListener?.watch(ctx);
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    recapManager?.clear(ctx);
+    recapManager = undefined;
+
+    idleListener?.dispose();
+    idleListener = undefined;
+  });
+}

package/extensions/recap/manager.ts

@@ -0,0 +1,127 @@
+import { completeSimple } from "@earendil-works/pi-ai";
+import { convertToLlm, serializeConversation } from "@earendil-works/pi-coding-agent";
+
+import { resolveRecapModel } from "./model";
+import { clearRecapWidget, setRecapLoadingWidget, setRecapTextWidget } from "./widget";
+import { sanitizeText } from "../shared/format";
+
+import type { Api, Model, ModelThinkingLevel, SimpleStreamOptions, Usage } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { RecapConfig } from "./config";
+
+const SYSTEM_PROMPT = [
+  "You write concise recaps for an idle terminal coding agent session.",
+  "Summarize only what is supported by the transcript; do not invent progress, intent, files, or next steps.",
+  "Focus on the user's goal, completed work, current state, and likely next step.",
+  "Prefer recent context when the session changed direction.",
+  "Output one short paragraph of 1-2 sentences. No heading, markdown, bullets, or quotes.",
+].join("\n");
+
+const MAX_TOKENS = 120;
+const MAX_CONVERSATION_CHARS = 8_000;
+
+export class RecapManager {
+  private pi: ExtensionAPI;
+  private config: RecapConfig;
+  private inflight: AbortController | undefined;
+  private active = false;
+
+  constructor(pi: ExtensionAPI, config: RecapConfig) {
+    this.pi = pi;
+    this.config = config;
+  }
+
+  async run(ctx: ExtensionContext, options: { force?: boolean } = {}): Promise<void> {
+    if (this.active && !options.force) return;
+
+    this.cancelInflight();
+    const controller = new AbortController();
+    this.inflight = controller;
+
+    try {
+      const recapModel = await resolveRecapModel(this.pi, ctx, this.config);
+      if (controller.signal.aborted || this.inflight !== controller || !recapModel) return;
+
+      setRecapLoadingWidget(ctx, recapModel.warning);
+      this.active = false;
+
+      const result = await this.generate(ctx, recapModel.model, recapModel.thinkingLevel, controller.signal);
+      if (controller.signal.aborted || this.inflight !== controller) return;
+      if (!result.content) {
+        clearRecapWidget(ctx);
+        return;
+      }
+
+      setRecapTextWidget(ctx, result.content, recapModel.warning);
+      this.active = true;
+
+      this.pi.appendEntry("recap", {
+        provider: recapModel.model.provider,
+        model: recapModel.model.id,
+        usage: result.usage,
+        content: result.content,
+      });
+    } catch (error) {
+      if (controller.signal.aborted || this.inflight !== controller) return;
+
+      const message = error instanceof Error ? error.message : String(error);
+      setRecapTextWidget(ctx, "Unable to generate recap.", message);
+      this.active = false;
+    } finally {
+      if (this.inflight === controller) this.inflight = undefined;
+    }
+  }
+
+  clear(ctx: ExtensionContext): void {
+    this.cancelInflight();
+    clearRecapWidget(ctx);
+    this.active = false;
+  }
+
+  private async generate(ctx: ExtensionContext, model: Model<Api>, thinkingLevel: ModelThinkingLevel, signal: AbortSignal): Promise<{ content: string; usage: Usage }> {
+    const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+    if (!auth.ok) throw new Error(auth.error);
+
+    const options: SimpleStreamOptions = { maxTokens: MAX_TOKENS, signal };
+    if (auth.apiKey) options.apiKey = auth.apiKey;
+    if (auth.headers) options.headers = auth.headers;
+    if (thinkingLevel !== "off") options.reasoning = thinkingLevel;
+
+    const response = await completeSimple(model, {
+      systemPrompt: SYSTEM_PROMPT,
+      messages: [{
+        role: "user",
+        content: [{ type: "text", text: this.buildPrompt(ctx) }],
+        timestamp: Date.now(),
+      }],
+    }, options);
+
+    const content = response.content
+      .filter((block) => block.type === "text")
+      .map((block) => block.text)
+      .join("\n")
+      .trim();
+
+    return { content: sanitizeText(content), usage: response.usage };
+  }
+
+  private buildPrompt(ctx: ExtensionContext): string {
+    const messages = ctx.sessionManager.getBranch().filter((entry) => entry.type === "message").map((entry) => entry.message);
+    const text = serializeConversation(convertToLlm(messages));
+    const conversation = text.length > MAX_CONVERSATION_CHARS ? text.slice(-MAX_CONVERSATION_CHARS) : text;
+
+    return [
+      "Create a short recap of this coding agent session for the user to see while the agent is idle.",
+      "The transcript may be truncated from the beginning and may start mid-message; account for that uncertainty.",
+      "",
+      "<conversation>",
+      conversation,
+      "</conversation>",
+    ].join("\n");
+  }
+
+  private cancelInflight(): void {
+    this.inflight?.abort();
+    this.inflight = undefined;
+  }
+}

package/extensions/recap/model.ts

@@ -0,0 +1,61 @@
+import { clampThinkingLevel } from "@earendil-works/pi-ai";
+
+import type { Api, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { OptionalModelConfig } from "../shared/config/model";
+
+const DEFAULT_THINKING_LEVEL: ModelThinkingLevel = "off";
+
+type RecapModel = {
+  model: Model<Api>;
+  thinkingLevel: ModelThinkingLevel;
+  warning: string | undefined;
+};
+
+export async function resolveRecapModel(pi: ExtensionAPI, ctx: ExtensionContext, config: OptionalModelConfig): Promise<RecapModel | undefined> {
+  const fallbackModel = ctx.model;
+  if (!fallbackModel) {
+    ctx.ui.notify("No model selected for recap", "warning");
+    return;
+  }
+
+  let model = fallbackModel;
+  let warning: string | undefined;
+
+  if (config.provider || config.model) {
+    if (!config.provider || !config.model) {
+      warning = "Both recap.provider and recap.model are required; using the current model.";
+    } else {
+      const configuredModel = ctx.modelRegistry.find(config.provider, config.model);
+      if (configuredModel) {
+        const auth = await ctx.modelRegistry.getApiKeyAndHeaders(configuredModel);
+        if (auth.ok) {
+          model = configuredModel;
+        } else {
+          warning = `Model ${config.provider}/${config.model} unavailable: ${auth.error}; using the current model.`;
+        }
+      } else {
+        warning = `Model ${config.provider}/${config.model} not found; using the current model.`;
+      }
+    }
+  }
+
+  const { thinkingLevel, warning: thinkingLevelWarning } = resolveThinkingLevel(model, config.thinkingLevel ?? pi.getThinkingLevel());
+
+  return {
+    model,
+    thinkingLevel,
+    warning: [warning, thinkingLevelWarning].filter(Boolean).join(" ") || undefined,
+  };
+}
+
+function resolveThinkingLevel(model: Model<Api>, requested: ModelThinkingLevel): { thinkingLevel: ModelThinkingLevel; warning?: string } {
+  const thinkingLevel = clampThinkingLevel(model, requested);
+  if (thinkingLevel === requested) return { thinkingLevel };
+
+  const fallback = clampThinkingLevel(model, DEFAULT_THINKING_LEVEL);
+  return {
+    thinkingLevel: fallback,
+    warning: `Thinking level ${requested} is not supported by ${model.provider}/${model.id}; using ${fallback}.`,
+  };
+}

package/extensions/recap/widget.ts

@@ -0,0 +1,42 @@
+import { Container, Loader, Spacer, Text, truncateToWidth } from "@earendil-works/pi-tui";
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const WIDGET_KEY = "recap";
+
+export function setRecapLoadingWidget(ctx: ExtensionContext, warning?: string): void {
+  ctx.ui.setWidget(WIDGET_KEY, (tui, theme) => {
+    const loader = new Loader(tui, (text) => theme.fg("accent", text), (text) => theme.fg("muted", text), "Generating recap...");
+    loader.start();
+
+    return {
+      render: (width: number) => {
+        const lines = loader.render(width);
+        if (lines[0] === "") lines.shift();
+
+        const loaderLine = (lines[0] ?? "").trimEnd();
+        const line = `${loaderLine}${warning ? ` ${theme.fg("warning", `(Warning: ${warning})`)}` : ""}`;
+
+        return [truncateToWidth(line, width), ""];
+      },
+      invalidate: () => loader.invalidate(),
+      dispose: () => loader.stop(),
+    };
+  });
+}
+
+export function setRecapTextWidget(ctx: ExtensionContext, content: string, warning?: string): void {
+  ctx.ui.setWidget(WIDGET_KEY, (_tui, theme) => {
+    const text = `${theme.bold(theme.fg("muted", "Recap:"))}${theme.fg("muted", ` ${content}`)}${warning ? ` ${theme.fg("warning", `(Warning: ${warning})`)}` : ""}`;
+
+    const container = new Container();
+    container.addChild(new Text(text, 1, 0));
+    container.addChild(new Spacer(1));
+
+    return container;
+  });
+}
+
+export function clearRecapWidget(ctx: ExtensionContext): void {
+  ctx.ui.setWidget(WIDGET_KEY, undefined);
+}

package/extensions/shared/components/inline-text.ts

@@ -0,0 +1,56 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+import { sanitizeText } from "../format";
+
+import type { Component } from "@earendil-works/pi-tui";
+
+interface InlineTextOptions {
+  padding?: number;
+  spacingChar?: string;
+  ellipsis?: string;
+}
+
+const DEFAULT_INLINE_TEXT_OPTIONS: Required<InlineTextOptions> = {
+  padding: 0,
+  spacingChar: " ",
+  ellipsis: "…",
+};
+
+/**
+ * Text component that renders inline and truncates it to fit the given width.
+ *
+ * The given width is a budget, not a guaranteed rendered width. After rendering, callers should
+ * check the result with visibleWidth(), because the rendered width may be smaller than the budget.
+ */
+export class InlineText implements Component {
+  private text: string;
+
+  private padding: number;
+  private spacingChar: string;
+  private ellipsis: string;
+
+  constructor(text: string, options: InlineTextOptions = {}) {
+    const spacingChar = options.spacingChar ?? DEFAULT_INLINE_TEXT_OPTIONS.spacingChar;
+    if (visibleWidth(spacingChar) !== 1) throw new Error("spacingChar must have a visible width of 1");
+
+    this.text = sanitizeText(text);
+
+    this.padding = options.padding ?? DEFAULT_INLINE_TEXT_OPTIONS.padding;
+    this.spacingChar = spacingChar;
+    this.ellipsis = options.ellipsis ?? DEFAULT_INLINE_TEXT_OPTIONS.ellipsis;
+  }
+
+  invalidate(): void {
+    // No-op
+  }
+
+  render(width: number): [string] {
+    if (visibleWidth(this.text) <= 0) return [""];
+    if (width < this.padding * 2 + visibleWidth(this.ellipsis)) return [""];
+
+    const displayText = truncateToWidth(this.text, width - this.padding * 2, this.ellipsis);
+    const paddingText = this.spacingChar.repeat(this.padding);
+
+    return [`${paddingText}${displayText}${paddingText}`];
+  }
+}