@ryan_nookpi/pi-extension-subagent 0.1.0

package/utils/format-utils.ts

@@ -0,0 +1,255 @@
+// Vendored from shared personal-extension utilities as a self-contained copy.
+// Maintained independently within this package.
+/**
+ * Pure formatting utility functions extracted from various extensions.
+ *
+ * These functions convert data into display-ready strings. They have no
+ * side effects and depend only on their arguments and Node built-ins.
+ */
+
+import { visibleWidth } from "@earendil-works/pi-tui";
+import type { AgentConfigLike } from "./agent-utils.ts";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export type { AgentConfigLike };
+
+export interface UsageStats {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	contextTokens?: number;
+	turns?: number;
+}
+
+export interface CommandRunSummaryInput {
+	id: number;
+	status: string;
+	agent: string;
+	contextMode?: string;
+	turnCount?: number;
+	elapsedMs: number;
+	toolCalls: number;
+}
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+/** Vibrant ANSI-256 foreground colors for per-agent name coloring. */
+export const AGENT_NAME_PALETTE = [39, 208, 114, 204, 220, 141, 81, 209, 156, 177];
+
+// ─── USD / Token Formatting ──────────────────────────────────────────────────
+
+/** Format a cost value as a USD string with adaptive precision. */
+export function formatUsd(cost: number): string {
+	if (!Number.isFinite(cost) || cost <= 0) return "$0.00";
+	if (cost >= 1) return `$${cost.toFixed(2)}`;
+	if (cost >= 0.1) return `$${cost.toFixed(3)}`;
+	return `$${cost.toFixed(4)}`;
+}
+
+/** Rough token estimate from text length (~4 chars/token). */
+export function estimateTokens(text: string): number {
+	return Math.max(0, Math.ceil(text.length / 4));
+}
+
+/**
+ * Safely extract a total cost number from a usage object.
+ * Handles `{ cost: number }`, `{ cost: string }`, `{ cost: { total: number } }`.
+ */
+export function extractCostTotal(usage: unknown): number {
+	if (!usage || typeof usage !== "object") return 0;
+	const rec = usage as Record<string, unknown>;
+	const c = rec.cost;
+	if (typeof c === "number") return Number.isFinite(c) ? c : 0;
+	if (typeof c === "string") {
+		const n = Number(c);
+		return Number.isFinite(n) ? n : 0;
+	}
+	if (c && typeof c === "object") {
+		const t = (c as Record<string, unknown>).total;
+		if (typeof t === "number") return Number.isFinite(t) ? t : 0;
+		if (typeof t === "string") {
+			const n = Number(t);
+			return Number.isFinite(n) ? n : 0;
+		}
+	}
+	return 0;
+}
+
+/** Format a token count to a compact string (e.g. "1.2k", "300k", "1.5M"). */
+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`;
+	return `${(count / 1000000).toFixed(1)}M`;
+}
+
+/**
+ * Build a compact usage stats summary string.
+ *
+ * Format example: `3 turns ↑12k ↓4.2k R8k W1k $0.0521 ctx:32k sonnet`
+ */
+export function formatUsageStats(usage: UsageStats, model?: string): string {
+	const parts: string[] = [];
+	if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
+	if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
+	if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
+	if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
+	if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
+	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
+	if (usage.contextTokens && usage.contextTokens > 0) {
+		parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
+	}
+	if (model) parts.push(model);
+	return parts.join(" ");
+}
+
+// ─── Model / Context ─────────────────────────────────────────────────────────
+
+/** Split a model reference into optional provider and id. */
+export function normalizeModelRef(modelRef: string): { provider?: string; id: string } {
+	const cleaned = modelRef.trim().split(":")[0] ?? modelRef.trim();
+	if (cleaned.includes("/")) {
+		const [provider, ...idParts] = cleaned.split("/");
+		return { provider, id: idParts.join("/") };
+	}
+	return { id: cleaned };
+}
+
+/** Compute percentage of context window used (0–100), or undefined if unavailable. */
+export function getUsedContextPercent(contextTokens?: number, contextWindow?: number): number | undefined {
+	if (!contextWindow || contextWindow <= 0) return undefined;
+	if (contextTokens === undefined || contextTokens === null || contextTokens < 0) return undefined;
+	return Math.max(0, Math.min(100, Math.round((contextTokens / contextWindow) * 100)));
+}
+
+/** Compute percentage of context window remaining (0–100). */
+export function getRemainingContextPercent(usedPercent?: number): number | undefined {
+	if (usedPercent === undefined || usedPercent === null) return undefined;
+	return Math.max(0, Math.min(100, 100 - usedPercent));
+}
+
+/**
+ * Render a text-based context usage bar.
+ * Example: `[■■■■■□□□□□] 50%`
+ */
+export function formatContextUsageBar(percent: number, width = 10): string {
+	const clamped = Math.max(0, Math.min(100, Math.round(percent)));
+	const barWidth = Math.max(4, width);
+	const filled = Math.round((clamped / 100) * barWidth);
+	return `[${"■".repeat(filled)}${"□".repeat(barWidth - filled)}] ${clamped}%`;
+}
+
+/** Map remaining context percentage to a color severity. */
+export function getContextBarColorByRemaining(remainingPercent: number): "warning" | "error" | undefined {
+	if (remainingPercent <= 15) return "error";
+	if (remainingPercent <= 40) return "warning";
+	return undefined;
+}
+
+// ─── Agent Formatting ────────────────────────────────────────────────────────
+
+/** Deterministic index into AGENT_NAME_PALETTE based on agent name hash. */
+export function agentBgIndex(name: string): number {
+	let h = 0;
+	for (let i = 0; i < name.length; i++) {
+		h = ((h << 5) - h + name.charCodeAt(i)) | 0;
+	}
+	return Math.abs(h) % AGENT_NAME_PALETTE.length;
+}
+
+/** Truncate text to at most `maxLines` lines, appending "..." if truncated. */
+export function truncateLines(text: string, maxLines = 2): string {
+	const lines = text.split("\n");
+	if (lines.length <= maxLines) return text;
+	return `${lines.slice(0, maxLines).join("\n")}\n...`;
+}
+
+function sliceToDisplayWidth(value: string, maxWidth: number): string {
+	if (maxWidth <= 0 || value.length === 0) return "";
+
+	let result = "";
+	let width = 0;
+
+	for (const { segment } of graphemeSegmenter.segment(value)) {
+		const segmentWidth = visibleWidth(segment);
+		if (segmentWidth <= 0) {
+			result += segment;
+			continue;
+		}
+		if (width + segmentWidth > maxWidth) break;
+		result += segment;
+		width += segmentWidth;
+	}
+
+	return result;
+}
+
+/**
+ * Truncate plain text to display width and append an ellipsis when truncation occurs.
+ * Apply terminal styles after calling this helper so the ellipsis inherits the intended style.
+ */
+export function truncatePlainToWidth(value: string, maxWidth: number, ellipsis = "..."): string {
+	if (maxWidth <= 0) return "";
+	if (visibleWidth(value) <= maxWidth) return value;
+	if (!ellipsis) return sliceToDisplayWidth(value, maxWidth);
+
+	const ellipsisWidth = visibleWidth(ellipsis);
+	if (ellipsisWidth >= maxWidth) return sliceToDisplayWidth(ellipsis, maxWidth);
+	return `${sliceToDisplayWidth(value, maxWidth - ellipsisWidth)}${ellipsis}`;
+}
+
+/**
+ * Truncate a single line to display width and append "..." when truncation occurs.
+ * Uses terminal display width (CJK-aware) rather than string length.
+ */
+export function truncateToWidthWithEllipsis(value: string, maxWidth: number): string {
+	if (maxWidth <= 0) return "";
+	if (visibleWidth(value) <= maxWidth) return value;
+	if (maxWidth <= 3) return sliceToDisplayWidth(value, maxWidth);
+	return truncatePlainToWidth(value, maxWidth, "...");
+}
+
+/**
+ * One-line summary of a command run.
+ *
+ * Format: `#<id> [<status>] <agent> ctx:<contextMode> turn:<turnCount> <elapsed>s tools:<toolCalls>`
+ */
+export function formatCommandRunSummary(run: CommandRunSummaryInput): string {
+	const elapsedSec = Math.max(0, Math.round(run.elapsedMs / 1000));
+	const contextLabel = run.contextMode === "main" ? "main" : "isolated";
+	return `#${run.id} [${run.status}] ${run.agent} ctx:${contextLabel} turn:${run.turnCount ?? 1} ${elapsedSec}s tools:${run.toolCalls}`;
+}
+
+/** Format a list of agents for display. */
+export function formatAgentList(agents: AgentConfigLike[], maxItems: number): { text: string; remaining: number } {
+	if (agents.length === 0) return { text: "none", remaining: 0 };
+	const listed = agents.slice(0, maxItems);
+	const remaining = agents.length - listed.length;
+	return {
+		text: listed.map((a) => `${a.name} (${a.source}): ${a.description}`).join("; "),
+		remaining,
+	};
+}
+
+// ─── GitHub Formatting ───────────────────────────────────────────────────────
+
+/** Format a state string for display (replace underscores, uppercase). */
+export function formatStateLabel(value: string | null): string {
+	if (!value) return "UNKNOWN";
+	return value.replace(/_/g, " ").toUpperCase();
+}
+
+// ─── Purpose Formatting ──────────────────────────────────────────────────────
+
+/** Format a purpose string for status bar display (normalizes whitespace, clips). */
+export function formatPurposeStatus(purpose: string): string {
+	const singleLine = typeof purpose !== "string" ? "" : purpose.replace(/\s+/g, " ").trim();
+	const maxChars = 90;
+	const clipped = singleLine.length > maxChars ? `${singleLine.slice(0, maxChars - 1)}…` : singleLine;
+	return `🎯 ${clipped}`;
+}

package/utils/short-label.ts

@@ -0,0 +1,78 @@
+// Vendored from shared personal-extension utilities as a self-contained copy.
+// Maintained independently within this package.
+import { completeSimple } from "@earendil-works/pi-ai/compat";
+
+type SummaryModel = Parameters<typeof completeSimple>[0];
+type SummaryResult = Awaited<ReturnType<typeof completeSimple>>;
+
+type AuthResult = {
+	ok: boolean;
+	apiKey?: string;
+	headers?: Record<string, string>;
+};
+
+export type ShortLabelContext = {
+	model?: SummaryModel;
+	modelRegistry?: {
+		getApiKeyAndHeaders: (model: SummaryModel) => Promise<AuthResult>;
+	};
+};
+
+export type GenerateShortLabelOptions = {
+	systemPrompt: string;
+	prompt: string;
+	maxTokens?: number;
+	timeoutMs?: number;
+	extractText?: (content: SummaryResult["content"]) => string;
+};
+
+function defaultExtractText(content: SummaryResult["content"]): string {
+	return content
+		.filter((part): part is { type: "text"; text: string } => part.type === "text" && typeof part.text === "string")
+		.map((part) => part.text)
+		.join("")
+		.trim();
+}
+
+export async function generateShortLabel(ctx: ShortLabelContext, options: GenerateShortLabelOptions): Promise<string> {
+	const model = ctx.model;
+	if (!model || !ctx.modelRegistry) return "";
+
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	if (!auth.ok) return "";
+
+	const controller = new AbortController();
+	const timeoutMs = options.timeoutMs ?? 10000;
+	const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+	try {
+		const result = await completeSimple(
+			model,
+			{
+				systemPrompt: options.systemPrompt,
+				messages: [
+					{
+						role: "user",
+						content: [{ type: "text", text: options.prompt }],
+						timestamp: Date.now(),
+					},
+				],
+			},
+			{
+				apiKey: auth.apiKey,
+				headers: auth.headers,
+				signal: controller.signal,
+				reasoning: "minimal",
+				maxTokens: options.maxTokens ?? 60,
+			},
+		);
+
+		if (result.stopReason !== "stop") return "";
+		const extractText = options.extractText ?? defaultExtractText;
+		return extractText(result.content);
+	} catch {
+		return "";
+	} finally {
+		clearTimeout(timer);
+	}
+}

package/utils/string-utils.ts

@@ -0,0 +1,229 @@
+// Vendored from shared personal-extension utilities as a self-contained copy.
+// Maintained independently within this package.
+/**
+ * Pure string utility functions extracted from various extension modules.
+ * No side effects, no pi SDK dependencies.
+ */
+
+import crypto from "node:crypto";
+import { basename } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ── Topic / Text Sanitization ────────────────────────────────────────────────
+
+/**
+ * Sanitize a topic name into a safe filesystem slug.
+ * Strips path traversal sequences, path separators, and non-slug characters.
+ * Throws on empty result.
+ *
+ * Source: memory-layer/storage.ts
+ */
+export function sanitizeTopic(topic: string): string {
+	const slug = topic
+		.replace(/\.\./g, "") // strip traversal
+		.replace(/[/\\]/g, "") // strip path separators
+		.toLowerCase()
+		.replace(/[^a-z0-9\uAC00-\uD7AF\u3131-\u3163-]/g, "-")
+		.replace(/-+/g, "-")
+		.replace(/^-|-$/g, "")
+		.slice(0, 50);
+
+	if (!slug) {
+		throw new Error(`Invalid topic name: "${topic}"`);
+	}
+	return slug;
+}
+
+/**
+ * Normalize text for consistent key generation.
+ * Trims whitespace and canonicalizes line endings (\r\n → \n).
+ *
+ * Source: memory-layer/storage.ts
+ */
+export function normalizeText(s: string): string {
+	return s.replace(/\r\n/g, "\n").trim();
+}
+
+/**
+ * Normalize a git remote URL to a slug.
+ *   https://github.com/example/product.git → github-example-product
+ *   git@github.com:example/product.git     → github-example-product
+ *
+ * Source: memory-layer/project-id.ts
+ */
+export function normalizeRemoteUrl(url: string): string {
+	let normalized = url.trim();
+
+	// SSH: git@github.com:org/repo.git → github.com/org/repo.git
+	const sshMatch = normalized.match(/^[\w-]+@([\w.-]+):(.*)/);
+	if (sshMatch) {
+		normalized = `${sshMatch[1]}/${sshMatch[2]}`;
+	}
+
+	// Strip protocol
+	normalized = normalized.replace(/^https?:\/\//, "");
+	normalized = normalized.replace(/^ssh:\/\//, "");
+
+	// Strip trailing .git
+	normalized = normalized.replace(/\.git$/, "");
+
+	// Strip trailing slashes
+	normalized = normalized.replace(/\/+$/, "");
+
+	// Strip user@ prefix (e.g. git@)
+	normalized = normalized.replace(/^[\w-]+@/, "");
+
+	// Replace non-alphanumeric with hyphens, collapse, trim
+	return normalized
+		.replace(/[^a-zA-Z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.toLowerCase();
+}
+
+/**
+ * Generate a short SHA-256 hash (first 8 hex chars).
+ *
+ * Source: memory-layer/project-id.ts
+ */
+export function shortHash(input: string): string {
+	return crypto.createHash("sha256").update(input).digest("hex").slice(0, 8);
+}
+
+/**
+ * Truncate content to its first line, clipped to maxLen characters.
+ *
+ * Source: memory-layer/index.ts
+ */
+export function truncateTitle(content: string, maxLen = 60): string {
+	const firstLine = content.split("\n")[0]?.trim() ?? content.trim();
+	if (firstLine.length <= maxLen) return firstLine;
+	return `${firstLine.slice(0, maxLen - 1)}…`;
+}
+
+/**
+ * Convert a slug to a human-readable heading (Title Case).
+ *
+ * Source: memory-layer/index.ts
+ */
+export function slugToHeading(slug: string): string {
+	return slug
+		.split("-")
+		.map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+		.join(" ");
+}
+
+// ── String Splitting / Encoding ──────────────────────────────────────────────
+
+/**
+ * Split a null-separated string into an array, filtering empty entries.
+ *
+ * Source: files.ts
+ */
+export function splitNullSeparated(value: string): string[] {
+	return value.split("\0").filter(Boolean);
+}
+
+/**
+ * Encode text to base64 (UTF-8).
+ *
+ * Source: former clipboard extension
+ */
+export function toBase64(text: string): string {
+	return Buffer.from(text, "utf-8").toString("base64");
+}
+
+// ── Name / Label Normalization ───────────────────────────────────────────────
+
+/**
+ * Normalize a skill name by stripping the "skill:" prefix if present.
+ *
+ * Source: context.ts
+ */
+export function normalizeSkillName(name: string): string {
+	return name.startsWith("skill:") ? name.slice("skill:".length) : name;
+}
+
+/**
+ * Join an array of strings with ", ".
+ *
+ * Source: context.ts
+ */
+export function joinComma(items: string[]): string {
+	return items.join(", ");
+}
+
+/**
+ * Join items with a custom render function and separator.
+ *
+ * Source: context.ts
+ */
+export function joinCommaStyled(items: string[], renderItem: (item: string) => string, sep: string): string {
+	return items.map(renderItem).join(sep);
+}
+
+// ── Whitespace / Tab ─────────────────────────────────────────────────────────
+
+/**
+ * Expand tabs to spaces.
+ *
+ * Source: diff-overlay.ts
+ */
+export function expandTabs(s: string, tabSize = 4): string {
+	return s.replace(/\t/g, " ".repeat(tabSize));
+}
+
+/**
+ * Derive the extension name (e.g. "minimal") from its import.meta.url or file path.
+ *
+ * Source: shared extension-name parsing helper
+ */
+export function extensionName(fileUrl: string): string {
+	const filePath = fileUrl.startsWith("file://") ? fileURLToPath(fileUrl) : fileUrl;
+	return basename(filePath).replace(/\.[^.]+$/, "");
+}
+
+/**
+ * Normalize whitespace in a string: collapse consecutive spaces/tabs/newlines
+ * into a single space and trim.
+ *
+ * Unifies normalizeLine (former idle-screensaver extension) and
+ * normalizePurpose (former auto-name extension) under the same
+ * whitespace-normalization logic.
+ *
+ * Source: former idle-screensaver / auto-name extensions
+ */
+export function normalizeWhitespace(raw: unknown): string {
+	if (typeof raw !== "string") return "";
+	return raw.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Sanitize status text: replace newlines/tabs with spaces, collapse, trim.
+ *
+ * Source: footer.ts
+ */
+export function sanitizeStatusText(text: string): string {
+	return text
+		.replace(/[\r\n\t]/g, " ")
+		.replace(/ +/g, " ")
+		.trim();
+}
+
+// ── Session ID Detection ─────────────────────────────────────────────────────
+
+/**
+ * Check if a string looks like an auto-generated session ID
+ * (hex-based or "session-NNN" pattern).
+ *
+ * Source: former idle-screensaver extension
+ */
+export function isLikelySessionId(text: string): boolean {
+	const s = normalizeWhitespace(text);
+	if (!s) return true;
+
+	const compact = s.replace(/[-_]/g, "");
+	if (/^[0-9a-f]{16,}$/i.test(compact)) return true;
+	if (/^session[-_]?\d+$/i.test(s)) return true;
+	if (/^session[-_]?[0-9a-f-]{8,}$/i.test(s)) return true;
+	return false;
+}

package/utils/time-utils.ts

@@ -0,0 +1,105 @@
+// Vendored from shared personal-extension utilities as a self-contained copy.
+// Maintained independently within this package.
+/**
+ * Shared time formatting helpers.
+ *
+ * Standard duration format: h/m/s (e.g. "1h 2m 3s", "4m 5s", "12s").
+ */
+
+// ─── Internal Helpers ────────────────────────────────────────────────────────
+
+function toSafeMs(value: number): number {
+	if (!Number.isFinite(value)) return 0;
+	return Math.max(0, Math.floor(value));
+}
+
+// ─── Existing Functions ──────────────────────────────────────────────────────
+
+export function formatDuration(ms: number): string {
+	const totalSeconds = Math.floor(toSafeMs(ms) / 1000);
+	const hours = Math.floor(totalSeconds / 3600);
+	const minutes = Math.floor((totalSeconds % 3600) / 60);
+	const seconds = totalSeconds % 60;
+
+	if (hours > 0) return `${hours}h ${minutes}m ${seconds}s`;
+	if (minutes > 0) return `${minutes}m ${seconds}s`;
+	return `${seconds}s`;
+}
+
+export function formatDurationBetween(start: Date | number, end: Date | number): string {
+	const startMs = start instanceof Date ? start.getTime() : start;
+	const endMs = end instanceof Date ? end.getTime() : end;
+	return formatDuration(toSafeMs(endMs - startMs));
+}
+
+export function formatElapsedSince(startedAt: number, now = Date.now()): string {
+	return formatDuration(toSafeMs(now - startedAt));
+}
+
+// ─── Delay / Duration Conversion ─────────────────────────────────────────────
+
+/** Convert a numeric amount + Korean unit to milliseconds. */
+export function toDelayMs(amount: number, unit: "초" | "분" | "시간"): number {
+	if (unit === "초") return amount * 1000;
+	if (unit === "시간") return amount * 60 * 60 * 1000;
+	return amount * 60 * 1000; // 분
+}
+
+/**
+ * Format milliseconds as a Korean duration string (shorter style).
+ *
+ * Unlike `formatDuration` which always shows 시간/분/초,
+ * this picks the most natural unit: "5초", "3분", "2시간 10분".
+ */
+export function formatKoreanDuration(ms: number): string {
+	if (ms < 60_000) return `${Math.max(1, Math.round(ms / 1000))}초`;
+	if (ms < 3_600_000) return `${Math.max(1, Math.round(ms / 60_000))}분`;
+
+	const hours = Math.floor(ms / 3_600_000);
+	const minutes = Math.floor((ms % 3_600_000) / 60_000);
+	if (minutes === 0) return `${hours}시간`;
+	return `${hours}시간 ${minutes}분`;
+}
+
+/** Format a timestamp as a ko-KR 24-hour clock string, e.g. "14:05:30". */
+export function formatClock(ts: number): string {
+	return new Date(ts).toLocaleTimeString("ko-KR", {
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit",
+		hour12: false,
+	});
+}
+
+// ─── Session Replay Time (from subagent/replay.ts) ───────────────────────────
+
+/** Safely parse a date value (number or string) into a Date, falling back to now. */
+export function parseDateSafely(raw: unknown): Date {
+	if (typeof raw === "number") {
+		const d = new Date(raw);
+		if (!Number.isNaN(d.getTime())) return d;
+	}
+	if (typeof raw === "string") {
+		const d = new Date(raw);
+		if (!Number.isNaN(d.getTime())) return d;
+	}
+	return new Date();
+}
+
+/** Format a Date as a compact time string, e.g. "14:05:30". */
+export function formatReplayTime(date: Date): string {
+	return date.toLocaleTimeString([], {
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit",
+	});
+}
+
+// ─── Epoch Conversion (from github-overlay.ts) ───────────────────────────────
+
+/** Parse an ISO date string to epoch milliseconds, returning 0 on failure. */
+export function toEpochMs(value: string | null): number {
+	if (!value) return 0;
+	const parsed = Date.parse(value);
+	return Number.isFinite(parsed) ? parsed : 0;
+}