shariq-pi-extensions 0.1.0

package/extensions/pi-memory/src/session.ts

@@ -0,0 +1,146 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { CapturedSession, ProjectIdentity } from "./types.ts";
+import { hasSensitiveToolArguments, redactSecrets, sanitizeToolArguments } from "./redaction.ts";
+
+type EntryLike = {
+  id?: unknown;
+  type?: unknown;
+  summary?: unknown;
+  message?: {
+    role?: unknown;
+    content?: unknown;
+    toolName?: unknown;
+    toolCallId?: unknown;
+    isError?: unknown;
+  };
+};
+
+type ContentBlock = {
+  type?: unknown;
+  id?: unknown;
+  text?: unknown;
+  name?: unknown;
+  arguments?: unknown;
+};
+
+const MEMORY_ELIGIBLE_TOOLS = new Set([
+  "read", "write", "edit", "bash", "grep", "find", "ls",
+  "start_terminal", "read_terminal", "write_terminal", "stop_terminal",
+  "spawn_agent", "task", "wait_agent", "check_agent", "send_message", "reply_question",
+]);
+
+export function isMemoryEligibleTool(toolName: string): boolean {
+  return MEMORY_ELIGIBLE_TOOLS.has(toolName);
+}
+
+function textContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((block): block is ContentBlock => typeof block === "object" && block !== null)
+    .filter((block) => block.type === "text" && typeof block.text === "string")
+    .map((block) => String(block.text))
+    .join("\n");
+}
+
+function serializeEntry(entry: EntryLike, sensitiveToolCallIds: ReadonlySet<string>): string | undefined {
+  const id = typeof entry.id === "string" ? entry.id : "unknown";
+  if (entry.type === "compaction" && typeof entry.summary === "string") {
+    return `[${id}] Compaction summary:\n${redactSecrets(entry.summary).slice(0, 8_000)}`;
+  }
+  if (entry.type === "branch_summary" && typeof entry.summary === "string") {
+    return `[${id}] Branch summary:\n${redactSecrets(entry.summary).slice(0, 8_000)}`;
+  }
+  if (entry.type !== "message" || !entry.message) return undefined;
+
+  const role = entry.message.role;
+  if (role === "user") {
+    const text = redactSecrets(textContent(entry.message.content)).trim();
+    return text ? `[${id}] User:\n${text}` : undefined;
+  }
+  if (role === "assistant") {
+    const blocks = Array.isArray(entry.message.content) ? entry.message.content : [];
+    const parts: string[] = [];
+    const text = redactSecrets(textContent(blocks)).trim();
+    if (text) parts.push(text);
+    for (const rawBlock of blocks) {
+      if (typeof rawBlock !== "object" || rawBlock === null) continue;
+      const block = rawBlock as ContentBlock;
+      if (block.type === "toolCall" && typeof block.name === "string" && isMemoryEligibleTool(block.name)) {
+        parts.push(`Tool call ${block.name}: ${sanitizeToolArguments(block.name, block.arguments)}`);
+      }
+    }
+    return parts.length > 0 ? `[${id}] Assistant:\n${parts.join("\n")}` : undefined;
+  }
+  if (role === "toolResult") {
+    const toolCallId = typeof entry.message.toolCallId === "string" ? entry.message.toolCallId : undefined;
+    if (toolCallId && sensitiveToolCallIds.has(toolCallId)) return undefined;
+    const toolName = typeof entry.message.toolName === "string" ? entry.message.toolName : "unknown";
+    if (!isMemoryEligibleTool(toolName)) return undefined;
+    const text = redactSecrets(textContent(entry.message.content)).trim().slice(0, 3_000);
+    if (!text) return undefined;
+    return `[${id}] Tool result ${toolName}${entry.message.isError ? " (error)" : ""}:\n${text}`;
+  }
+  return undefined;
+}
+
+export function captureSession(
+  ctx: Pick<ExtensionContext, "sessionManager">,
+  project: ProjectIdentity,
+  checkpointLeafId: string | undefined,
+  maxCharacters: number,
+): CapturedSession | undefined {
+  const branch = ctx.sessionManager.getBranch() as EntryLike[];
+  const leaf = branch.at(-1);
+  const leafId = typeof leaf?.id === "string" ? leaf.id : undefined;
+  if (!leafId || leafId === checkpointLeafId) return undefined;
+
+  const sensitiveToolCallIds = new Set<string>();
+  for (const entry of branch) {
+    if (entry.type !== "message" || entry.message?.role !== "assistant" || !Array.isArray(entry.message.content)) continue;
+    for (const rawBlock of entry.message.content) {
+      if (!rawBlock || typeof rawBlock !== "object") continue;
+      const block = rawBlock as ContentBlock;
+      if (
+        block.type === "toolCall"
+        && typeof block.id === "string"
+        && typeof block.name === "string"
+        && hasSensitiveToolArguments(block.name, block.arguments)
+      ) {
+        sensitiveToolCallIds.add(block.id);
+      }
+    }
+  }
+
+  const checkpointIndex = checkpointLeafId ? branch.findIndex((entry) => entry.id === checkpointLeafId) : -1;
+  const firstNewIndex = checkpointIndex >= 0 ? checkpointIndex + 1 : 0;
+  const contextStart = Math.max(0, firstNewIndex - 4);
+  const selected = branch.slice(contextStart);
+  const newSerialized = branch.slice(firstNewIndex)
+    .map((entry) => ({ entry, text: serializeEntry(entry, sensitiveToolCallIds) }))
+    .filter((item): item is { entry: EntryLike & { id: string }; text: string } => typeof item.entry.id === "string" && Boolean(item.text));
+  if (newSerialized.length === 0) return undefined;
+  const entryIds = newSerialized.map((item) => item.entry.id);
+
+  const serialized = selected.map((entry) => serializeEntry(entry, sensitiveToolCallIds)).filter((value): value is string => Boolean(value));
+  if (serialized.length === 0) return undefined;
+  let transcript = serialized.join("\n\n");
+  if (transcript.length > maxCharacters) transcript = `[older content omitted]\n\n${transcript.slice(-maxCharacters)}`;
+
+  const queryText = redactSecrets(branch.slice(firstNewIndex)
+    .filter((entry) => entry.type === "message" && entry.message?.role === "user")
+    .map((entry) => textContent(entry.message?.content))
+    .join("\n"))
+    .slice(0, 8_000);
+
+  return {
+    sessionId: ctx.sessionManager.getSessionId(),
+    sessionFile: ctx.sessionManager.getSessionFile() ?? "ephemeral",
+    project,
+    leafId,
+    entryIds,
+    transcript,
+    queryText,
+    capturedAt: Date.now(),
+  };
+}

package/extensions/pi-memory/src/types.ts

@@ -0,0 +1,82 @@
+export const MEMORY_KINDS = [
+  "preference",
+  "decision",
+  "convention",
+  "fact",
+  "solution",
+  "warning",
+  "reference",
+] as const;
+
+export type MemoryKind = (typeof MEMORY_KINDS)[number];
+export type MemoryScope = "global" | "project";
+export type MemoryStatus = "active" | "superseded" | "deleted";
+export type MemorySourceKind = "pi-session" | "manual" | "bootstrap-import";
+
+export interface ProjectIdentity {
+  id: string;
+  identity: string;
+  rootPath: string;
+  displayName: string;
+  directoryName: string;
+}
+
+export interface MemoryRecord {
+  id: number;
+  memoryId: string;
+  scope: MemoryScope;
+  projectId: string | null;
+  kind: MemoryKind;
+  title: string;
+  content: string;
+  tags: string[];
+  importance: number;
+  confidence: number;
+  status: MemoryStatus;
+  sourceKind: MemorySourceKind;
+  sourceRef: string;
+  sourceEntryIds: string[];
+  fingerprint: string;
+  createdAt: number;
+  updatedAt: number;
+  lastAccessedAt: number | null;
+  accessCount: number;
+}
+
+export interface MemoryCandidate {
+  operation: "add" | "update" | "supersede" | "ignore";
+  targetId?: string;
+  scope: MemoryScope;
+  kind: MemoryKind;
+  title: string;
+  content: string;
+  tags: string[];
+  importance: number;
+  confidence: number;
+  evidenceEntryIds: string[];
+}
+
+export interface SearchResult extends MemoryRecord {
+  score: number;
+}
+
+export interface CapturedSession {
+  sessionId: string;
+  sessionFile: string;
+  project: ProjectIdentity;
+  leafId: string;
+  entryIds: string[];
+  transcript: string;
+  queryText: string;
+  capturedAt: number;
+}
+
+export interface CaptureJob {
+  id: number;
+  jobKey: string;
+  sessionId: string;
+  projectId: string;
+  status: "pending" | "running" | "complete" | "failed";
+  attempts: number;
+  payload: CapturedSession;
+}

package/extensions/shared/README.md

@@ -0,0 +1,18 @@
+# Shared Extension Helpers
+
+Internal runtime utilities used by more than one extension. This directory is not a Pi extension and has no `index.ts` entrypoint in the package manifest.
+
+## Modules
+
+- `activity-status.ts` formats compact running/completed/failed status counts.
+- `child-session.ts` owns trust-aware child resources and bounded session shutdown.
+- `context-utilization.ts` formats model-context usage and capacity.
+- `dashboard-state.ts` keeps list selection stable as live rows change.
+- `tool-call-timeout.ts` applies cancellation-aware execution limits to registered tools.
+- `tui-dashboard.ts` provides bounded, sanitized terminal-dashboard rendering helpers.
+
+Keep extension-specific behavior in its owning `extensions/<name>` directory. Move code here only when multiple extensions genuinely share the same runtime contract.
+
+## Validation
+
+From the repository root, run `npm run validate`.

package/extensions/shared/activity-status.ts

@@ -0,0 +1,31 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+type Theme = ExtensionContext["ui"]["theme"];
+
+interface ActivityCounts {
+  running: number;
+  done: number;
+  failed: number;
+}
+
+const SQUARE = "■";
+
+export function formatActivityStatus(
+  theme: Theme,
+  label: "subagents" | "workflows",
+  counts: ActivityCounts,
+) {
+  const parts: string[] = [];
+  if (counts.running > 0) {
+    parts.push(theme.fg("warning", `${SQUARE} ${counts.running} running`));
+  }
+  if (counts.done > 0) {
+    parts.push(theme.fg("success", `${SQUARE} ${counts.done} done`));
+  }
+  if (counts.failed > 0) {
+    parts.push(theme.fg("error", `${SQUARE} ${counts.failed} failed`));
+  }
+  parts.push(theme.fg("accent", `/${label}`) + theme.fg("dim", " to view"));
+
+  return `${theme.fg("muted", `${label}:`)} ${parts.join(theme.fg("dim", " · "))}`;
+}

package/extensions/shared/child-session.ts

@@ -0,0 +1,150 @@
+import * as path from "node:path";
+import {
+  DefaultResourceLoader,
+  getAgentDir,
+  ProjectTrustStore,
+  SettingsManager,
+  type AgentSession,
+  type SessionShutdownEvent,
+} from "@earendil-works/pi-coding-agent";
+
+const CHILD_SHUTDOWN_TIMEOUT_MS = 5_000;
+
+/** Tools that headless children must not receive. Everything else stays enabled. */
+export const CHILD_EXCLUDED_TOOL_NAMES = [
+  "subagent_spawn",
+  "subagent_wait",
+  "subagent_cancel",
+  "subagent_check",
+  "subagent_list",
+  "workflow",
+  "create_orchestration",
+  "get_orchestration",
+  "ask_user",
+] as const;
+
+/** Fresh SDK options avoid turning the denylist into an accidental allowlist. */
+export function childToolPolicy() {
+  return { excludeTools: [...CHILD_EXCLUDED_TOOL_NAMES] };
+}
+
+export interface ChildResourceOptions {
+  cwd: string;
+  projectTrusted: boolean;
+  appendSystemPrompt?: string[];
+  agentDir?: string;
+}
+
+/** Load normal global/package resources and trust-gated project resources. */
+export async function createChildResources(options: ChildResourceOptions) {
+  const agentDir = options.agentDir ?? getAgentDir();
+  const settingsManager = SettingsManager.create(options.cwd, agentDir, {
+    projectTrusted: options.projectTrusted,
+  });
+  const loader = new DefaultResourceLoader({
+    cwd: options.cwd,
+    agentDir,
+    settingsManager,
+    ...(options.appendSystemPrompt
+      ? { appendSystemPrompt: options.appendSystemPrompt }
+      : {}),
+  });
+  await loader.reload();
+  return { loader, settingsManager };
+}
+
+/**
+ * Same-directory children inherit the live parent decision. An alternate cwd
+ * is trusted only when Pi's persisted trust store explicitly trusts it (or a
+ * containing directory); unreadable/invalid trust data fails closed.
+ */
+export function resolveStandaloneChildProjectTrust(options: {
+  parentCwd: string;
+  childCwd: string;
+  parentTrusted: boolean;
+  agentDir?: string;
+}) {
+  if (path.resolve(options.childCwd) === path.resolve(options.parentCwd)) {
+    return options.parentTrusted;
+  }
+  try {
+    const trustStore = new ProjectTrustStore(options.agentDir ?? getAgentDir());
+    return trustStore.get(options.childCwd) === true;
+  } catch {
+    return false;
+  }
+}
+
+/** Start child extension session hooks/resources in headless print mode. */
+export async function bindChildSessionExtensions(
+  session: Pick<AgentSession, "bindExtensions">,
+) {
+  await session.bindExtensions({ mode: "print" });
+}
+
+interface ChildExtensionRunner {
+  hasHandlers(eventType: string): boolean;
+  emit(event: SessionShutdownEvent): Promise<unknown>;
+}
+
+export interface DisposableChildSession {
+  readonly extensionRunner: ChildExtensionRunner;
+  dispose(): void;
+}
+
+const childShutdowns = new WeakMap<object, Promise<void>>();
+
+function waitBounded(operation: Promise<unknown>, timeoutMs: number) {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<void>((resolve) => {
+    timer = setTimeout(resolve, timeoutMs);
+  });
+  return Promise.race([
+    operation.then(
+      () => undefined,
+      () => undefined,
+    ),
+    timeout,
+  ])
+    .catch(() => {})
+    .finally(() => {
+      if (timer) clearTimeout(timer);
+    });
+}
+
+/**
+ * Emit child session_shutdown once, then dispose once. Hook failures and a
+ * bounded hook deadline never prevent disposal.
+ */
+export function shutdownAndDisposeChildSession(
+  session: DisposableChildSession,
+  options: { timeoutMs?: number } = {},
+) {
+  const existing = childShutdowns.get(session);
+  if (existing) return existing;
+
+  const shutdown = (async () => {
+    try {
+      if (session.extensionRunner.hasHandlers("session_shutdown")) {
+        await waitBounded(
+          session.extensionRunner.emit({
+            type: "session_shutdown",
+            reason: "quit",
+          }),
+          options.timeoutMs ?? CHILD_SHUTDOWN_TIMEOUT_MS,
+        );
+      }
+    } catch {
+      // Extension runner inspection/emission is best-effort during teardown.
+    } finally {
+      try {
+        session.dispose();
+      } catch {
+        // Disposal is terminal and must remain idempotent for callers.
+      }
+    }
+  })();
+
+  childShutdowns.set(session, shutdown);
+  return shutdown;
+}

package/extensions/shared/context-utilization.ts

@@ -0,0 +1,47 @@
+/** Compact, defensive context-window utilization formatting for child agents. */
+
+export interface ContextUtilization {
+  /** Current conversation context occupancy; null while it is unknown after compaction. */
+  tokens?: number | null;
+  /** Capacity of the model currently serving the conversation. */
+  contextWindow?: number | null;
+}
+
+function usableTokens(value: number | null | undefined) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0
+    ? value
+    : undefined;
+}
+
+function usableCapacity(value: number | null | undefined) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0
+    ? value
+    : undefined;
+}
+
+export function contextPercent(usage: ContextUtilization) {
+  const tokens = usableTokens(usage.tokens);
+  const capacity = usableCapacity(usage.contextWindow);
+  if (tokens === undefined || capacity === undefined) return undefined;
+  return Math.round(Math.min(100, Math.max(0, (tokens / capacity) * 100)));
+}
+
+export function formatCompactTokens(count: number) {
+  if (count < 1000) return Math.round(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`;
+}
+
+/**
+ * Render `%/capacity`. If occupancy is temporarily unknown (notably directly
+ * after compaction), retain the useful model capacity as `?%/capacity`. If no
+ * valid capacity is available, omit the statistic because no percentage can
+ * be computed.
+ */
+export function formatContextUtilization(usage: ContextUtilization) {
+  const capacity = usableCapacity(usage.contextWindow);
+  if (capacity === undefined) return "";
+  const percent = contextPercent(usage);
+  return `${percent === undefined ? "?" : percent}%/${formatCompactTokens(capacity)}`;
+}

package/extensions/shared/dashboard-state.ts

@@ -0,0 +1,99 @@
+export const MODEL_INFO_CHANNEL = "dashboard:model-info";
+export const GIT_INFO_CHANNEL = "dashboard:git-info";
+export const REFRESH_CHANNEL = "dashboard:refresh";
+
+export interface ModelInfoState {
+  provider: string;
+  modelId: string;
+  modelName: string;
+  thinking: string;
+  contextTokens: number | null;
+  contextWindow: number;
+  contextPercent: number | null;
+  cost: number;
+  tokensPerSecond: number | null;
+  generating: boolean;
+}
+
+export interface PullRequestInfo {
+  number: number;
+  url: string;
+  isDraft: boolean;
+}
+
+export interface GitInfoState {
+  isRepository: boolean;
+  branch: string | null;
+  changedFiles: number;
+  pullRequest: PullRequestInfo | null;
+}
+
+export function emptyModelInfoState(): ModelInfoState {
+  return {
+    provider: "",
+    modelId: "no-model",
+    modelName: "No model",
+    thinking: "off",
+    contextTokens: null,
+    contextWindow: 0,
+    contextPercent: null,
+    cost: 0,
+    tokensPerSecond: null,
+    generating: false,
+  };
+}
+
+export function emptyGitInfoState(): GitInfoState {
+  return {
+    isRepository: false,
+    branch: null,
+    changedFiles: 0,
+    pullRequest: null,
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isNullableNumber(value: unknown) {
+  return value === null || typeof value === "number";
+}
+
+export function isModelInfoState(value: unknown): value is ModelInfoState {
+  if (!isRecord(value)) return false;
+
+  return (
+    typeof value.provider === "string" &&
+    typeof value.modelId === "string" &&
+    typeof value.modelName === "string" &&
+    typeof value.thinking === "string" &&
+    isNullableNumber(value.contextTokens) &&
+    typeof value.contextWindow === "number" &&
+    isNullableNumber(value.contextPercent) &&
+    typeof value.cost === "number" &&
+    isNullableNumber(value.tokensPerSecond) &&
+    typeof value.generating === "boolean"
+  );
+}
+
+function isPullRequestInfo(value: unknown): value is PullRequestInfo {
+  if (!isRecord(value)) return false;
+
+  return (
+    typeof value.number === "number" &&
+    typeof value.url === "string" &&
+    typeof value.isDraft === "boolean"
+  );
+}
+
+export function isGitInfoState(value: unknown): value is GitInfoState {
+  if (!isRecord(value)) return false;
+
+  return (
+    typeof value.isRepository === "boolean" &&
+    (value.branch === null || typeof value.branch === "string") &&
+    typeof value.changedFiles === "number" &&
+    (value.pullRequest === null || isPullRequestInfo(value.pullRequest))
+  );
+}

package/extensions/shared/tool-call-timeout.ts

@@ -0,0 +1,104 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+
+export const CHILD_TOOL_CALL_TIMEOUT_MS = 3 * 60 * 1_000;
+
+interface ToolRegistry {
+  getAllTools(): Array<{ name: string }>;
+  getToolDefinition(name: string): ToolDefinition | undefined;
+}
+
+function formatTimeout(timeoutMs: number) {
+  if (timeoutMs % 60_000 === 0) {
+    const minutes = timeoutMs / 60_000;
+    return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+  }
+  if (timeoutMs % 1_000 === 0) {
+    const seconds = timeoutMs / 1_000;
+    return `${seconds} second${seconds === 1 ? "" : "s"}`;
+  }
+  return `${timeoutMs} ms`;
+}
+
+export class ToolCallTimeoutError extends Error {
+  constructor(toolName: string, timeoutMs: number) {
+    super(
+      `Tool call "${toolName}" timed out after ${formatTimeout(timeoutMs)}.`,
+    );
+    this.name = "ToolCallTimeoutError";
+  }
+}
+
+export async function runWithToolCallTimeout<T>(
+  toolName: string,
+  timeoutMs: number,
+  signal: AbortSignal | undefined,
+  execute: (signal: AbortSignal) => Promise<T>,
+) {
+  const timeoutController = new AbortController();
+  const executionSignal = signal
+    ? AbortSignal.any([signal, timeoutController.signal])
+    : timeoutController.signal;
+  const timeoutError = new ToolCallTimeoutError(toolName, timeoutMs);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(timeoutError);
+      timeoutController.abort(timeoutError);
+    }, timeoutMs);
+  });
+
+  let removeAbortListener: (() => void) | undefined;
+  const aborted = new Promise<never>((_resolve, reject) => {
+    if (!signal) return;
+    const onAbort = () => {
+      reject(
+        signal.reason instanceof Error
+          ? signal.reason
+          : new Error(`Tool call "${toolName}" was aborted.`),
+      );
+    };
+    if (signal.aborted) {
+      onAbort();
+      return;
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+    removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+  });
+
+  try {
+    return await Promise.race([execute(executionSignal), timeout, aborted]);
+  } finally {
+    if (timer) clearTimeout(timer);
+    removeAbortListener?.();
+  }
+}
+
+/**
+ * Wrap every currently registered child tool with an independent execution
+ * timeout. Calling apply() again is safe and picks up tools registered later.
+ */
+export function createToolCallTimeoutGuard(
+  timeoutMs = CHILD_TOOL_CALL_TIMEOUT_MS,
+) {
+  const wrapped = new WeakSet<ToolDefinition>();
+
+  const wrap = (definition: ToolDefinition) => {
+    if (wrapped.has(definition)) return;
+    wrapped.add(definition);
+
+    const execute = definition.execute;
+    definition.execute = async (toolCallId, params, signal, onUpdate, ctx) =>
+      runWithToolCallTimeout(definition.name, timeoutMs, signal, (signal) =>
+        execute.call(definition, toolCallId, params, signal, onUpdate, ctx),
+      );
+  };
+
+  return {
+    apply(session: ToolRegistry) {
+      for (const { name } of session.getAllTools()) {
+        const definition = session.getToolDefinition(name);
+        if (definition) wrap(definition);
+      }
+    },
+  };
+}