@hadooppei/hwcode 0.1.0

package/.env.example

@@ -0,0 +1,11 @@
+# Keep real credentials outside version control.
+# Local provider credentials. Model addresses and capabilities live in
+# .pi/model-providers.json.
+PI_LOCAL_MODEL_API_KEY=local
+
+# Optional credential used as the default when logging in to the configurable
+# "hw" provider. Leave unset for a keyless local endpoint.
+# HW_API_KEY=
+
+# OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=

package/.pi/APPEND_SYSTEM.md

@@ -0,0 +1,5 @@
+# HWCode Behavior
+
+Treat this repository as the active project boundary. Follow `AGENTS.md`, keep edits scoped to the user's request, and verify material changes before reporting completion.
+
+Do not expose secrets or perform destructive, irreversible, or externally visible actions without explicit user authorization.

package/.pi/extensions/command-filter.ts

@@ -0,0 +1,46 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import {
+	DEFAULT_HIDDEN_COMMANDS,
+	filterCommandSuggestions,
+	parseHiddenCommands,
+} from "../lib/command-filter.ts";
+
+function loadHiddenCommands(cwd: string, notify: (message: string) => void): Set<string> {
+	const settingsPath = join(cwd, ".pi", "settings.json");
+	if (!existsSync(settingsPath)) return new Set(DEFAULT_HIDDEN_COMMANDS);
+	try {
+		return parseHiddenCommands(readFileSync(settingsPath, "utf8"));
+	} catch (error) {
+		notify(
+			`Invalid hwcode.hiddenCommands configuration; using defaults. ${error instanceof Error ? error.message : String(error)}`,
+		);
+		return new Set(DEFAULT_HIDDEN_COMMANDS);
+	}
+}
+
+export default function commandFilterExtension(pi: ExtensionAPI) {
+	pi.on("session_start", async (_event, ctx) => {
+		if (ctx.mode !== "tui") return;
+		const hiddenCommands = loadHiddenCommands(ctx.cwd, (message) => {
+			if (ctx.hasUI) ctx.ui.notify(message, "warning");
+		});
+
+		ctx.ui.addAutocompleteProvider((current) => ({
+			triggerCharacters: current.triggerCharacters,
+			getSuggestions: async (...args) => {
+				const suggestions = await current.getSuggestions(...args);
+				if (!suggestions) return null;
+				const items = filterCommandSuggestions(suggestions.items, suggestions.prefix, hiddenCommands);
+				return items.length > 0 ? { ...suggestions, items } : null;
+			},
+			applyCompletion: (...args) => current.applyCompletion(...args),
+			...(current.shouldTriggerFileCompletion && {
+				shouldTriggerFileCompletion: (...args) => current.shouldTriggerFileCompletion!(...args),
+			}),
+		}));
+	});
+}

package/.pi/extensions/cwd.ts

@@ -0,0 +1,188 @@
+import type {
+	BashOperations,
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { createLocalBashOperations } from "@earendil-works/pi-coding-agent";
+
+import {
+	canonicalizeDirectory,
+	findChainedDirectoryChange,
+	getActiveWorkflowRoot,
+	getWorkingDirectory,
+	getWorkingDirectoryState,
+	parseLeadingDirectoryChange,
+	resetWorkingDirectoryState,
+	resolveDirectoryArgument,
+	resolveWorkingPath,
+	setWorkingDirectoryState,
+	shellQuote,
+	type WorkingDirectoryState,
+	WORKING_DIRECTORY_STATE_TYPE,
+} from "../lib/working-directory.ts";
+
+const FILE_PATH_TOOLS = new Set(["read", "write", "edit", "grep", "find", "ls"]);
+const OPTIONAL_PATH_TOOLS = new Set(["grep", "find", "ls"]);
+
+interface ChangeResult {
+	state?: WorkingDirectoryState;
+	error?: string;
+}
+
+function notify(ctx: ExtensionContext, message: string, level: "info" | "warning" | "error" = "info"): void {
+	if (ctx.hasUI) ctx.ui.notify(message, level);
+}
+
+function commandArgument(args: string): string {
+	const trimmed = args.trim();
+	if (!trimmed) return "";
+	const parsed = parseLeadingDirectoryChange(`cd ${trimmed}`);
+	return parsed && !parsed.remainder ? parsed.argument : trimmed;
+}
+
+export default function workingDirectoryExtension(pi: ExtensionAPI) {
+	const localBash = createLocalBashOperations();
+
+	function changeDirectory(argument: string, ctx: ExtensionContext): ChangeResult {
+		const current = getWorkingDirectoryState(ctx.sessionManager);
+		let target: string;
+		try {
+			target = resolveDirectoryArgument(current.cwd, argument, current.previousCwd);
+		} catch (error) {
+			return { error: error instanceof Error ? error.message : String(error) };
+		}
+
+		const workflowRoot = getActiveWorkflowRoot(ctx.sessionManager.getEntries());
+		if (workflowRoot) {
+			let canonicalWorkflowRoot = workflowRoot;
+			try {
+				canonicalWorkflowRoot = canonicalizeDirectory(workflowRoot);
+			} catch {
+				// The workflow guard will handle a missing locked root separately.
+			}
+			if (target !== canonicalWorkflowRoot) {
+				return {
+					error: `The active HWCode workflow locks this session to ${workflowRoot}. Start a new session before switching to ${target}.`,
+				};
+			}
+		}
+
+		const state: WorkingDirectoryState = {
+			version: 1,
+			cwd: target,
+			previousCwd: target === current.cwd ? current.previousCwd : current.cwd,
+		};
+		setWorkingDirectoryState(ctx.sessionManager, state);
+		pi.appendEntry<WorkingDirectoryState>(WORKING_DIRECTORY_STATE_TYPE, state);
+		pi.events.emit("hwcode:working-directory-changed", state);
+		return { state };
+	}
+
+	pi.registerCommand("cd", {
+		description: "Change the persistent working directory for this session",
+		handler: async (args, ctx) => {
+			if (!ctx.isIdle()) {
+				notify(ctx, "Wait for the current response to finish before changing directory.", "warning");
+				return;
+			}
+			const result = changeDirectory(commandArgument(args), ctx);
+			if (result.error) {
+				notify(ctx, result.error, "error");
+				return;
+			}
+			notify(ctx, `Working directory: ${result.state!.cwd}`);
+		},
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		try {
+			resetWorkingDirectoryState(ctx.sessionManager);
+		} catch (error) {
+			const fallback: WorkingDirectoryState = {
+				version: 1,
+				cwd: canonicalizeDirectory(ctx.sessionManager.getCwd()),
+			};
+			setWorkingDirectoryState(ctx.sessionManager, fallback);
+			pi.appendEntry<WorkingDirectoryState>(WORKING_DIRECTORY_STATE_TYPE, fallback);
+			notify(
+				ctx,
+				`Stored working directory is unavailable; restored ${fallback.cwd}. ${error instanceof Error ? error.message : String(error)}`,
+				"warning",
+			);
+		}
+	});
+
+	pi.on("before_agent_start", (event, ctx) => {
+		const cwd = getWorkingDirectory(ctx.sessionManager);
+		const prompt = event.systemPrompt.replace(
+			/\nCurrent working directory: [^\n]*(?=\n|$)/gu,
+			`\nCurrent working directory: ${cwd}`,
+		);
+		return {
+			systemPrompt: `${prompt}\nA leading shell \`cd\` changes the persistent working directory for this session. All relative shell and built-in file-tool paths resolve from the current working directory.`,
+		};
+	});
+
+	pi.on("tool_call", (event, ctx) => {
+		const input = event.input as Record<string, unknown>;
+		if (event.toolName === "bash" && typeof input.command === "string") {
+			const executionCwd = getWorkingDirectory(ctx.sessionManager);
+			const change = findChainedDirectoryChange(input.command);
+			if (change) {
+				const result = changeDirectory(change.argument, ctx);
+				if (result.error) return { block: true, reason: result.error };
+			}
+
+			input.command = `cd -- ${shellQuote(executionCwd)} || exit $?\n${input.command}`;
+			return undefined;
+		}
+
+		if (!FILE_PATH_TOOLS.has(event.toolName)) return undefined;
+		const cwd = getWorkingDirectory(ctx.sessionManager);
+		if (typeof input.path === "string") {
+			input.path = resolveWorkingPath(cwd, input.path);
+		} else if (OPTIONAL_PATH_TOOLS.has(event.toolName)) {
+			input.path = cwd;
+		}
+		return undefined;
+	});
+
+	pi.on("user_bash", (event, ctx) => {
+		const executionCwd = getWorkingDirectory(ctx.sessionManager);
+		const change = findChainedDirectoryChange(event.command);
+		if (change) {
+			const result = changeDirectory(change.argument, ctx);
+			if (result.error) {
+				return {
+					result: {
+						output: `${result.error}\n`,
+						exitCode: 1,
+						cancelled: false,
+						truncated: false,
+					},
+				};
+			}
+			if (change.standalone) {
+				return {
+					result: {
+						output: `${result.state!.cwd}\n`,
+						exitCode: 0,
+						cancelled: false,
+						truncated: false,
+					},
+				};
+			}
+			const operations: BashOperations = {
+				exec: (command, _cwd, options) => localBash.exec(command, executionCwd, options),
+			};
+			return { operations };
+		}
+
+		const cwd = getWorkingDirectory(ctx.sessionManager);
+		if (cwd === event.cwd) return undefined;
+		const operations: BashOperations = {
+			exec: (command, _cwd, options) => localBash.exec(command, cwd, options),
+		};
+		return { operations };
+	});
+}

package/.pi/extensions/footer-tps.ts

@@ -0,0 +1,292 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import type { AssistantMessage, Usage } from "@earendil-works/pi-ai";
+import {
+  type ExtensionAPI,
+  type ExtensionContext,
+  type ReadonlyFooterDataProvider,
+  type Theme,
+} from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+import {
+  canonicalizeDirectory,
+  getWorkingDirectory,
+} from "../lib/working-directory.ts";
+
+interface UsageTotals {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+}
+
+interface TpsState {
+  streaming: boolean;
+  firstDeltaAt?: number;
+  streamedChunks: number;
+  reportedTokens: number;
+  value?: number;
+  approximate: boolean;
+}
+
+const tps: TpsState = {
+  streaming: false,
+  streamedChunks: 0,
+  reportedTokens: 0,
+  approximate: false,
+};
+
+let requestRender: (() => void) | undefined;
+
+function addUsage(totals: UsageTotals, usage: Usage): void {
+  totals.input += usage.input;
+  totals.output += usage.output;
+  totals.cacheRead += usage.cacheRead;
+  totals.cacheWrite += usage.cacheWrite;
+  totals.cost += usage.cost.total;
+}
+
+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`;
+}
+
+function formatCwd(cwd: string, home: string | undefined): string {
+  if (!home) return cwd;
+
+  const resolvedCwd = resolve(cwd);
+  const resolvedHome = resolve(home);
+  const relativeToHome = relative(resolvedHome, resolvedCwd);
+  const isInsideHome =
+    relativeToHome === "" ||
+    (relativeToHome !== ".." &&
+      !relativeToHome.startsWith(`..${sep}`) &&
+      !isAbsolute(relativeToHome));
+
+  if (!isInsideHome) return cwd;
+  return relativeToHome === "" ? "~" : `~${sep}${relativeToHome}`;
+}
+
+function sanitizeStatusText(text: string): string {
+  return text.replace(/[\r\n\t]/gu, " ").replace(/ +/gu, " ").trim();
+}
+
+function updateTps(now: number, exactTokens?: number): void {
+  if (tps.firstDeltaAt === undefined) return;
+
+  const elapsedSeconds = (now - tps.firstDeltaAt) / 1000;
+  if (elapsedSeconds <= 0 || (elapsedSeconds < 0.1 && exactTokens === undefined)) return;
+
+  const tokenCount = exactTokens && exactTokens > 0 ? exactTokens : tps.streamedChunks;
+  if (tokenCount <= 0) return;
+
+  tps.value = tokenCount / elapsedSeconds;
+  tps.approximate = !(exactTokens && exactTokens > 0);
+}
+
+function tpsLabel(): string {
+  if (tps.value === undefined) return tps.streaming ? "TPS …" : "TPS --";
+  return `TPS ${tps.approximate ? "~" : ""}${tps.value.toFixed(1)}`;
+}
+
+function resetTps(streaming: boolean): void {
+  tps.streaming = streaming;
+  tps.firstDeltaAt = undefined;
+  tps.streamedChunks = 0;
+  tps.reportedTokens = 0;
+  tps.value = undefined;
+  tps.approximate = false;
+}
+
+function isGeneratedDelta(type: string): boolean {
+  return type === "text_delta" || type === "thinking_delta" || type === "toolcall_delta";
+}
+
+function collectUsage(ctx: ExtensionContext): {
+  totals: UsageTotals;
+  latestCacheHitRate?: number;
+} {
+  const totals: UsageTotals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+  let latestCacheHitRate: number | undefined;
+
+  for (const entry of ctx.sessionManager.getEntries()) {
+    if (entry.type === "message" && entry.message.role === "assistant") {
+      const usage = (entry.message as AssistantMessage).usage;
+      addUsage(totals, usage);
+      const promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;
+      latestCacheHitRate = promptTokens > 0 ? (usage.cacheRead / promptTokens) * 100 : undefined;
+    } else if (entry.type === "message" && entry.message.role === "toolResult" && entry.message.usage) {
+      addUsage(totals, entry.message.usage);
+    } else if ((entry.type === "branch_summary" || entry.type === "compaction") && entry.usage) {
+      addUsage(totals, entry.usage);
+    }
+  }
+
+  return { totals, latestCacheHitRate };
+}
+
+function renderFooter(
+  ctx: ExtensionContext,
+  theme: Theme,
+  footerData: ReadonlyFooterDataProvider,
+  width: number,
+): string[] {
+  const { totals, latestCacheHitRate } = collectUsage(ctx);
+  const contextUsage = ctx.getContextUsage();
+  const contextWindow = contextUsage?.contextWindow ?? ctx.model?.contextWindow ?? 0;
+  const contextPercentValue = contextUsage?.percent ?? 0;
+  const contextPercent = contextUsage?.percent === null ? "?" : contextPercentValue.toFixed(1);
+
+  const workingDirectory = getWorkingDirectory(ctx.sessionManager);
+  let pwd = formatCwd(workingDirectory, process.env.HOME || process.env.USERPROFILE);
+  let sessionDirectory = ctx.sessionManager.getCwd();
+  try {
+    sessionDirectory = canonicalizeDirectory(sessionDirectory);
+  } catch {
+    // If the launch directory disappeared, do not show its stale Git branch.
+  }
+  const branch = workingDirectory === sessionDirectory ? footerData.getGitBranch() : undefined;
+  if (branch) pwd = `${pwd} (${branch})`;
+  const sessionName = ctx.sessionManager.getSessionName();
+  if (sessionName) pwd = `${pwd} • ${sessionName}`;
+
+  const statsParts: string[] = [];
+  if (totals.input) statsParts.push(`↑${formatTokens(totals.input)}`);
+  if (totals.output) statsParts.push(`↓${formatTokens(totals.output)}`);
+  if (totals.cacheRead) statsParts.push(`R${formatTokens(totals.cacheRead)}`);
+  if (totals.cacheWrite) statsParts.push(`W${formatTokens(totals.cacheWrite)}`);
+  if ((totals.cacheRead > 0 || totals.cacheWrite > 0) && latestCacheHitRate !== undefined) {
+    statsParts.push(`CH${latestCacheHitRate.toFixed(1)}%`);
+  }
+  if (totals.cost) statsParts.push(`$${totals.cost.toFixed(3)}`);
+
+  const contextDisplay =
+    contextPercent === "?"
+      ? `?/${formatTokens(contextWindow)} (auto)`
+      : `${contextPercent}%/${formatTokens(contextWindow)} (auto)`;
+  if (contextPercentValue > 90) {
+    statsParts.push(theme.fg("error", contextDisplay));
+  } else if (contextPercentValue > 70) {
+    statsParts.push(theme.fg("warning", contextDisplay));
+  } else {
+    statsParts.push(contextDisplay);
+  }
+  statsParts.push(tpsLabel());
+
+  let statsLeft = statsParts.join(" ");
+  let statsLeftWidth = visibleWidth(statsLeft);
+  if (statsLeftWidth > width) {
+    statsLeft = truncateToWidth(statsLeft, width, "...");
+    statsLeftWidth = visibleWidth(statsLeft);
+  }
+
+  const modelName = ctx.model?.id ?? "no-model";
+  let rightWithoutProvider = modelName;
+  if (ctx.model?.reasoning) {
+    const thinkingLevel = ctx.thinkingLevel ?? "off";
+    rightWithoutProvider =
+      thinkingLevel === "off" ? `${modelName} • thinking off` : `${modelName} • ${thinkingLevel}`;
+  }
+
+  let rightSide = rightWithoutProvider;
+  const minimumPadding = 2;
+  if (footerData.getAvailableProviderCount() > 1 && ctx.model) {
+    rightSide = `(${ctx.model.provider}) ${rightWithoutProvider}`;
+    if (statsLeftWidth + minimumPadding + visibleWidth(rightSide) > width) {
+      rightSide = rightWithoutProvider;
+    }
+  }
+
+  const rightSideWidth = visibleWidth(rightSide);
+  let statsLine: string;
+  if (statsLeftWidth + minimumPadding + rightSideWidth <= width) {
+    statsLine = statsLeft + " ".repeat(width - statsLeftWidth - rightSideWidth) + rightSide;
+  } else {
+    const availableForRight = width - statsLeftWidth - minimumPadding;
+    if (availableForRight > 0) {
+      const truncatedRight = truncateToWidth(rightSide, availableForRight, "");
+      statsLine =
+        statsLeft +
+        " ".repeat(Math.max(0, width - statsLeftWidth - visibleWidth(truncatedRight))) +
+        truncatedRight;
+    } else {
+      statsLine = statsLeft;
+    }
+  }
+
+  const remainder = statsLine.slice(statsLeft.length);
+  const lines = [
+    truncateToWidth(theme.fg("dim", pwd), width, theme.fg("dim", "...")),
+    theme.fg("dim", statsLeft) + theme.fg("dim", remainder),
+  ];
+
+  const statuses = footerData.getExtensionStatuses();
+  if (statuses.size > 0) {
+    const statusLine = Array.from(statuses.entries())
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([, text]) => sanitizeStatusText(text))
+      .join(" ");
+    lines.push(truncateToWidth(statusLine, width, theme.fg("dim", "...")));
+  }
+
+  return lines;
+}
+
+export default function footerTpsExtension(pi: ExtensionAPI) {
+  pi.on("session_start", (_event, ctx) => {
+    if (ctx.mode !== "tui") return;
+    resetTps(false);
+
+    ctx.ui.setFooter((tui, theme, footerData) => {
+      requestRender = () => tui.requestRender();
+      const unsubscribeBranch = footerData.onBranchChange(requestRender);
+      const unsubscribeCwd = pi.events.on("hwcode:working-directory-changed", requestRender);
+
+      return {
+        render: (width) => renderFooter(ctx, theme, footerData, width),
+        invalidate() {},
+        dispose() {
+          unsubscribeBranch();
+          unsubscribeCwd();
+          requestRender = undefined;
+        },
+      };
+    });
+  });
+
+  pi.on("message_start", (event) => {
+    if (event.message.role !== "assistant") return;
+    resetTps(true);
+    requestRender?.();
+  });
+
+  pi.on("message_update", (event) => {
+    if (event.message.role !== "assistant") return;
+
+    const now = performance.now();
+    if (isGeneratedDelta(event.assistantMessageEvent.type)) {
+      tps.firstDeltaAt ??= now;
+      tps.streamedChunks += 1;
+    }
+
+    const reportedTokens = event.message.usage.output;
+    if (reportedTokens > 0) tps.reportedTokens = reportedTokens;
+    updateTps(now, tps.reportedTokens || undefined);
+    requestRender?.();
+  });
+
+  pi.on("message_end", (event) => {
+    if (event.message.role !== "assistant") return;
+
+    const now = performance.now();
+    const reportedTokens = event.message.usage.output;
+    if (reportedTokens > 0) tps.reportedTokens = reportedTokens;
+    updateTps(now, tps.reportedTokens || undefined);
+    tps.streaming = false;
+    requestRender?.();
+  });
+}

package/.pi/extensions/hwcode.ts

@@ -0,0 +1,10 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function hwcodeExtension(pi: ExtensionAPI) {
+  pi.registerCommand("hwcode", {
+    description: "Show whether the HWCode project profile is active",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify("HWCode project profile is active.", "info");
+    },
+  });
+}