shariq-pi-extensions 0.1.0

package/extensions/subagents/src/catalog.ts

@@ -0,0 +1,85 @@
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { CapabilityMode, IsolationMode } from "./config.ts";
+import type { SubagentStatus } from "./domain.ts";
+import type { WorktreeInfo } from "./worktree.ts";
+
+export interface ArchivedSubagent {
+  id: string;
+  title: string;
+  cwd: string;
+  status: SubagentStatus;
+  sessionFile: string;
+  model?: string;
+  agentType?: string;
+  persona?: string;
+  capability?: CapabilityMode;
+  isolation?: IsolationMode;
+  worktree?: WorktreeInfo;
+  updatedAt: number;
+}
+
+interface CatalogFile {
+  version: 1;
+  agents: ArchivedSubagent[];
+}
+
+const MAX_CATALOG_AGENTS = 512;
+
+export function allocateSubagentId() {
+  // Preserve the legacy sa-N shape while remaining collision-resistant across
+  // independent and ephemeral Pi processes.
+  const random = BigInt(`0x${randomBytes(8).toString("hex")}`).toString(10).padStart(20, "0");
+  return `sa-${Date.now()}${random}`;
+}
+
+export function subagentCatalogPath() {
+  return path.join(getAgentDir(), "subagents", "catalog.json");
+}
+
+function validRecord(value: unknown): value is ArchivedSubagent {
+  if (!value || typeof value !== "object") return false;
+  const record = value as Partial<ArchivedSubagent>;
+  return (
+    typeof record.id === "string" &&
+    typeof record.title === "string" &&
+    typeof record.cwd === "string" &&
+    typeof record.sessionFile === "string" &&
+    typeof record.updatedAt === "number" &&
+    (record.status === "running" || record.status === "done" || record.status === "error")
+  );
+}
+
+export function loadSubagentCatalog(): Map<string, ArchivedSubagent> {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(subagentCatalogPath(), "utf8")) as Partial<CatalogFile>;
+    const agents = Array.isArray(parsed.agents) ? parsed.agents.filter(validRecord) : [];
+    return new Map(agents.map((record) => [record.id, record]));
+  } catch {
+    return new Map();
+  }
+}
+
+export function saveSubagentCatalog(records: Iterable<ArchivedSubagent>) {
+  const file = subagentCatalogPath();
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const agents = [...records]
+    .filter(validRecord)
+    .sort((a, b) => b.updatedAt - a.updatedAt)
+    .slice(0, MAX_CATALOG_AGENTS);
+  const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify({ version: 1, agents }, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  fs.renameSync(temp, file);
+  fs.chmodSync(file, 0o600);
+}
+
+export function upsertSubagentCatalog(record: ArchivedSubagent) {
+  const catalog = loadSubagentCatalog();
+  const existing = catalog.get(record.id);
+  if (!existing || existing.updatedAt <= record.updatedAt) catalog.set(record.id, record);
+  saveSubagentCatalog(catalog.values());
+}

package/extensions/subagents/src/config.ts

@@ -0,0 +1,241 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ReasoningEffort } from "./domain.ts";
+
+export const AGENT_TYPES = ["general-purpose", "explore", "plan"] as const;
+export const CAPABILITY_MODES = ["read-only", "read-write", "execute", "all"] as const;
+export const ISOLATION_MODES = ["none", "worktree"] as const;
+
+export type CapabilityMode = (typeof CAPABILITY_MODES)[number];
+export type IsolationMode = (typeof ISOLATION_MODES)[number];
+
+export interface AgentProfile {
+  description?: string;
+  instructions?: string;
+  capability?: CapabilityMode;
+  model?: string;
+  thinking?: ReasoningEffort;
+  isolation?: IsolationMode;
+}
+
+export interface PersonaProfile {
+  description?: string;
+  instructions: string;
+  model?: string;
+  thinking?: ReasoningEffort;
+  isolation?: IsolationMode;
+}
+
+export interface SubagentConfig {
+  maxConcurrent: number;
+  profiles: Record<string, AgentProfile>;
+  personas: Record<string, PersonaProfile>;
+}
+
+const BUILTIN_PROFILES: Record<string, AgentProfile> = {
+  "general-purpose": {
+    description: "Full-capability implementation and investigation agent",
+    capability: "all",
+  },
+  explore: {
+    description: "Read, search, and execute diagnostics without editing files",
+    capability: "execute",
+    instructions: "Investigate only as far as needed to answer the task. Do not modify files. Report concrete evidence and paths, and distinguish verified facts from inference.",
+  },
+  plan: {
+    description: "Read-only planning agent that produces an implementation plan",
+    capability: "execute",
+    instructions: "Inspect the relevant code without modifying files. Return an ordered implementation plan tied to current paths, dependencies, material risks, and validation steps."
+  },
+};
+
+const DEFAULT_CONFIG: SubagentConfig = {
+  maxConcurrent: 50,
+  profiles: BUILTIN_PROFILES,
+  personas: {},
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function readJson(file: string): Record<string, unknown> | undefined {
+  try {
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    return isRecord(value) ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function boundedInt(value: unknown, fallback: number, min: number, max: number) {
+  return typeof value === "number" && Number.isInteger(value)
+    ? Math.max(min, Math.min(max, value))
+    : fallback;
+}
+
+function enumValue<T extends readonly string[]>(value: unknown, values: T): T[number] | undefined {
+  return typeof value === "string" && values.includes(value) ? (value as T[number]) : undefined;
+}
+
+function parseProfile(value: unknown): AgentProfile | undefined {
+  if (!isRecord(value)) return undefined;
+  return {
+    description: typeof value.description === "string" ? value.description : undefined,
+    instructions: typeof value.instructions === "string" ? value.instructions : undefined,
+    capability: enumValue(value.capability, CAPABILITY_MODES),
+    model: typeof value.model === "string" ? value.model : undefined,
+    thinking: enumValue(value.thinking, ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const),
+    isolation: enumValue(value.isolation, ISOLATION_MODES),
+  };
+}
+
+function parsePersona(value: unknown): PersonaProfile | undefined {
+  const profile = parseProfile(value);
+  if (!profile?.instructions) return undefined;
+  return { ...profile, instructions: profile.instructions };
+}
+
+function mergeConfig(base: SubagentConfig, raw: Record<string, unknown> | undefined): SubagentConfig {
+  if (!raw) return base;
+  const profiles = { ...base.profiles };
+  if (isRecord(raw.profiles)) {
+    for (const [name, value] of Object.entries(raw.profiles)) {
+      const parsed = parseProfile(value);
+      if (parsed) profiles[name] = { ...profiles[name], ...parsed };
+    }
+  }
+  const personas = { ...base.personas };
+  if (isRecord(raw.personas)) {
+    for (const [name, value] of Object.entries(raw.personas)) {
+      const parsed = parsePersona(value);
+      if (parsed) personas[name] = parsed;
+    }
+  }
+  return {
+    maxConcurrent: boundedInt(raw.maxConcurrent, base.maxConcurrent, 1, 50),
+    profiles,
+    personas,
+  };
+}
+
+export type ConfigScope = "global" | "project";
+
+export function subagentConfigPath(scope: ConfigScope, cwd: string) {
+  return scope === "global"
+    ? path.join(getAgentDir(), "subagents.json")
+    : path.join(cwd, CONFIG_DIR_NAME, "subagents.json");
+}
+
+export function loadConfigDocument(scope: ConfigScope, cwd: string) {
+  const file = subagentConfigPath(scope, cwd);
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return `${JSON.stringify({ maxConcurrent: 50, profiles: {}, personas: {} }, null, 2)}\n`;
+  }
+}
+
+function validateProfileDocument(name: string, value: unknown, persona: boolean) {
+  if (!isRecord(value)) throw new Error(`Invalid ${persona ? "persona" : "profile"} "${name}".`);
+  if (value.description !== undefined && typeof value.description !== "string") {
+    throw new Error(`${name}.description must be a string.`);
+  }
+  if (value.instructions !== undefined && typeof value.instructions !== "string") {
+    throw new Error(`${name}.instructions must be a string.`);
+  }
+  if (persona && typeof value.instructions !== "string") {
+    throw new Error(`Invalid persona "${name}"; personas require instructions.`);
+  }
+  if (value.capability !== undefined && !enumValue(value.capability, CAPABILITY_MODES)) {
+    throw new Error(`${name}.capability must be one of ${CAPABILITY_MODES.join(", ")}.`);
+  }
+  if (value.isolation !== undefined && !enumValue(value.isolation, ISOLATION_MODES)) {
+    throw new Error(`${name}.isolation must be one of ${ISOLATION_MODES.join(", ")}.`);
+  }
+  if (value.model !== undefined && typeof value.model !== "string") {
+    throw new Error(`${name}.model must be a string.`);
+  }
+  if (
+    value.thinking !== undefined &&
+    !enumValue(value.thinking, ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const)
+  ) {
+    throw new Error(`${name}.thinking is invalid.`);
+  }
+}
+
+export function saveConfigDocument(scope: ConfigScope, cwd: string, text: string) {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`Invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!isRecord(raw)) throw new Error("Subagent configuration must be a JSON object.");
+  if (
+    raw.maxConcurrent !== undefined &&
+    (!Number.isInteger(raw.maxConcurrent) || (raw.maxConcurrent as number) < 1 || (raw.maxConcurrent as number) > 50)
+  ) {
+    throw new Error("maxConcurrent must be an integer from 1 to 50.");
+  }
+  if (raw.profiles !== undefined && !isRecord(raw.profiles)) {
+    throw new Error("profiles must be an object keyed by profile name.");
+  }
+  for (const [name, value] of Object.entries(isRecord(raw.profiles) ? raw.profiles : {})) {
+    if (!name.trim()) throw new Error("Profile names cannot be empty.");
+    validateProfileDocument(name, value, false);
+  }
+  if (raw.personas !== undefined && !isRecord(raw.personas)) {
+    throw new Error("personas must be an object keyed by persona name.");
+  }
+  for (const [name, value] of Object.entries(isRecord(raw.personas) ? raw.personas : {})) {
+    if (!name.trim()) throw new Error("Persona names cannot be empty.");
+    validateProfileDocument(name, value, true);
+  }
+  const file = subagentConfigPath(scope, cwd);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(raw, null, 2)}\n`, { mode: 0o600 });
+  fs.chmodSync(file, 0o600);
+}
+
+export function loadSubagentConfig(cwd: string, projectTrusted: boolean): SubagentConfig {
+  let config = mergeConfig(DEFAULT_CONFIG, readJson(subagentConfigPath("global", cwd)));
+  if (projectTrusted) {
+    config = mergeConfig(config, readJson(subagentConfigPath("project", cwd)));
+  }
+  return config;
+}
+
+export function resolveProfile(
+  config: SubagentConfig,
+  options: {
+    agentType?: string;
+    persona?: string;
+    capability?: CapabilityMode;
+    model?: string;
+    thinking?: ReasoningEffort;
+    isolation?: IsolationMode;
+  },
+) {
+  const agentType = options.agentType?.trim() || "general-purpose";
+  const profile = config.profiles[agentType];
+  if (!profile) {
+    throw new Error(`Unknown agent_type "${agentType}". Available: ${Object.keys(config.profiles).join(", ")}.`);
+  }
+  const personaName = options.persona?.trim();
+  const persona = personaName ? config.personas[personaName] : undefined;
+  if (personaName && !persona) {
+    throw new Error(`Unknown persona "${personaName}". Available: ${Object.keys(config.personas).join(", ") || "none"}.`);
+  }
+  const instructions = [profile.instructions, persona?.instructions].filter(Boolean).join("\n\n");
+  return {
+    agentType,
+    persona: personaName,
+    instructions,
+    capability: options.capability ?? profile.capability ?? "all",
+    model: options.model ?? profile.model ?? persona?.model,
+    thinking: options.thinking ?? profile.thinking ?? persona?.thinking,
+    isolation: options.isolation ?? profile.isolation ?? persona?.isolation ?? "none",
+  } as const;
+}

package/extensions/subagents/src/context.ts

@@ -0,0 +1,57 @@
+import type { AssistantMessage, Message, UserMessage } from "@earendil-works/pi-ai";
+
+export type ForkTurns = "none" | "all" | number;
+
+export function parseForkTurns(value: string | undefined): ForkTurns {
+  const normalized = value?.trim().toLowerCase() || "none";
+  if (normalized === "none") return "none";
+  if (normalized === "all") return "all";
+  const count = Number(normalized);
+  if (!Number.isInteger(count) || count <= 0) {
+    throw new Error('fork_turns must be "none", "all", or a positive integer string.');
+  }
+  return count;
+}
+
+function sanitizeMessage(message: unknown): Message | undefined {
+  if (!message || typeof message !== "object") return undefined;
+  const role = (message as { role?: unknown }).role;
+  if (role === "user") {
+    const user = message as UserMessage;
+    return { ...user, content: Array.isArray(user.content) ? user.content.filter((part) => part.type === "text" || part.type === "image") : user.content };
+  }
+  if (role === "assistant") {
+    const assistant = message as AssistantMessage;
+    const content = assistant.content.filter((part) => part.type === "text");
+    if (content.length === 0) return undefined;
+    return { ...assistant, content, stopReason: "stop", errorMessage: undefined };
+  }
+  return undefined;
+}
+
+/**
+ * Fork only conversational user/final-text history. Tool calls, tool results,
+ * and thinking are deliberately excluded so the child never inherits an
+ * unresolved protocol exchange or private reasoning.
+ */
+export function forkConversation(messages: readonly unknown[], mode: ForkTurns): Message[] {
+  if (mode === "none") return [];
+  const sanitized = messages.map(sanitizeMessage).filter((message): message is Message => !!message);
+  if (mode === "all") return sanitized;
+
+  let usersSeen = 0;
+  let start = sanitized.length;
+  for (let index = sanitized.length - 1; index >= 0; index--) {
+    if (sanitized[index]?.role !== "user") continue;
+    usersSeen++;
+    start = index;
+    if (usersSeen >= mode) break;
+  }
+  return sanitized.slice(start);
+}
+
+export function buildTaskPrompt(message: string, instructions: string, persona?: string) {
+  if (!instructions.trim()) return message;
+  const label = persona ? `Profile instructions with persona "${persona}"` : "Profile instructions";
+  return `<subagent_instructions>\n${label}:\n${instructions.trim()}\n</subagent_instructions>\n\nTask:\n${message}`;
+}

package/extensions/subagents/src/coordinator.ts

@@ -0,0 +1,64 @@
+import type { EventBus, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { CapabilityMode, IsolationMode } from "./config.ts";
+import type {
+  ReasoningEffort,
+  SubagentSnapshot,
+} from "./domain.ts";
+
+export const SUBAGENT_COORDINATOR_REQUEST =
+  "shariq-pi-extensions:subagents:coordinator-request";
+
+export interface CoordinatorSpawnOptions {
+  message: string;
+  taskName: string;
+  cwd?: string;
+  model?: string;
+  thinking?: ReasoningEffort;
+  capability: CapabilityMode;
+  isolation: IsolationMode;
+  agentType?: string;
+  resumeFrom?: string;
+  concurrencyGroup?: string;
+  maxConcurrent?: number;
+}
+
+export interface SubagentCoordinator {
+  spawn(
+    ctx: ExtensionContext,
+    options: CoordinatorSpawnOptions,
+  ): Promise<SubagentSnapshot>;
+  send(id: string, message: string): Promise<SubagentSnapshot>;
+  cancel(ids: ReadonlyArray<string>): Promise<void>;
+  get(id: string): Promise<SubagentSnapshot | undefined>;
+  list(): Promise<ReadonlyArray<SubagentSnapshot>>;
+  subscribe(listener: () => void): Promise<() => void>;
+  apply(id: string, targetCwd?: string): Promise<{ changed: boolean; files: string[] }>;
+  discard(id: string): Promise<void>;
+  release(id: string): Promise<void>;
+}
+
+interface CoordinatorRequest {
+  accept(coordinator: SubagentCoordinator): void;
+}
+
+export function requestSubagentCoordinator(
+  events: EventBus,
+): SubagentCoordinator | undefined {
+  let coordinator: SubagentCoordinator | undefined;
+  events.emit(SUBAGENT_COORDINATOR_REQUEST, {
+    accept(value) {
+      coordinator = value;
+    },
+  } satisfies CoordinatorRequest);
+  return coordinator;
+}
+
+export function isCoordinatorRequest(
+  value: unknown,
+): value is CoordinatorRequest {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    typeof (value as CoordinatorRequest).accept === "function"
+  );
+}