@gotgenes/pi-subagents 1.0.0

package/src/invocation-config.ts

@@ -0,0 +1,40 @@
+import type { AgentConfig, IsolationMode, JoinMode, ThinkingLevel } from "./types.js";
+
+interface AgentInvocationParams {
+  model?: string;
+  thinking?: string;
+  max_turns?: number;
+  run_in_background?: boolean;
+  inherit_context?: boolean;
+  isolated?: boolean;
+  isolation?: IsolationMode;
+}
+
+export function resolveAgentInvocationConfig(
+  agentConfig: AgentConfig | undefined,
+  params: AgentInvocationParams,
+): {
+  modelInput?: string;
+  modelFromParams: boolean;
+  thinking?: ThinkingLevel;
+  maxTurns?: number;
+  inheritContext: boolean;
+  runInBackground: boolean;
+  isolated: boolean;
+  isolation?: IsolationMode;
+} {
+  return {
+    modelInput: agentConfig?.model ?? params.model,
+    modelFromParams: agentConfig?.model == null && params.model != null,
+    thinking: (agentConfig?.thinking ?? params.thinking) as ThinkingLevel | undefined,
+    maxTurns: agentConfig?.maxTurns ?? params.max_turns,
+    inheritContext: agentConfig?.inheritContext ?? params.inherit_context ?? false,
+    runInBackground: agentConfig?.runInBackground ?? params.run_in_background ?? false,
+    isolated: agentConfig?.isolated ?? params.isolated ?? false,
+    isolation: agentConfig?.isolation ?? params.isolation,
+  };
+}
+
+export function resolveJoinMode(defaultJoinMode: JoinMode, runInBackground: boolean): JoinMode | undefined {
+  return runInBackground ? defaultJoinMode : undefined;
+}

package/src/memory.ts

@@ -0,0 +1,165 @@
+/**
+ * memory.ts — Persistent agent memory: per-agent memory directories that persist across sessions.
+ *
+ * Memory scopes:
+ *   - "user"    → ~/.pi/agent-memory/{agent-name}/
+ *   - "project" → .pi/agent-memory/{agent-name}/
+ *   - "local"   → .pi/agent-memory-local/{agent-name}/
+ */
+
+import { existsSync, lstatSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, } from "node:path";
+import type { MemoryScope } from "./types.js";
+
+/** Maximum lines to read from MEMORY.md */
+const MAX_MEMORY_LINES = 200;
+
+/**
+ * Returns true if a name contains characters not allowed in agent/skill names.
+ * Uses a whitelist: only alphanumeric, hyphens, underscores, and dots (no leading dot).
+ */
+export function isUnsafeName(name: string): boolean {
+  if (!name || name.length > 128) return true;
+  return !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name);
+}
+
+/**
+ * Returns true if the given path is a symlink (defense against symlink attacks).
+ */
+export function isSymlink(filePath: string): boolean {
+  try {
+    return lstatSync(filePath).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Safely read a file, rejecting symlinks.
+ * Returns undefined if the file doesn't exist, is a symlink, or can't be read.
+ */
+export function safeReadFile(filePath: string): string | undefined {
+  if (!existsSync(filePath)) return undefined;
+  if (isSymlink(filePath)) return undefined;
+  try {
+    return readFileSync(filePath, "utf-8");
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve the memory directory path for a given agent + scope + cwd.
+ * Throws if agentName contains path traversal characters.
+ */
+export function resolveMemoryDir(agentName: string, scope: MemoryScope, cwd: string): string {
+  if (isUnsafeName(agentName)) {
+    throw new Error(`Unsafe agent name for memory directory: "${agentName}"`);
+  }
+  switch (scope) {
+    case "user":
+      return join(homedir(), ".pi", "agent-memory", agentName);
+    case "project":
+      return join(cwd, ".pi", "agent-memory", agentName);
+    case "local":
+      return join(cwd, ".pi", "agent-memory-local", agentName);
+  }
+}
+
+/**
+ * Ensure the memory directory exists, creating it if needed.
+ * Refuses to create directories if any component in the path is a symlink
+ * to prevent symlink-based directory traversal attacks.
+ */
+export function ensureMemoryDir(memoryDir: string): void {
+  // If the directory already exists, verify it's not a symlink
+  if (existsSync(memoryDir)) {
+    if (isSymlink(memoryDir)) {
+      throw new Error(`Refusing to use symlinked memory directory: ${memoryDir}`);
+    }
+    return;
+  }
+  mkdirSync(memoryDir, { recursive: true });
+}
+
+/**
+ * Read the first N lines of MEMORY.md from the memory directory, if it exists.
+ * Returns undefined if no MEMORY.md exists or if the path is a symlink.
+ */
+export function readMemoryIndex(memoryDir: string): string | undefined {
+  // Reject symlinked memory directories
+  if (isSymlink(memoryDir)) return undefined;
+
+  const memoryFile = join(memoryDir, "MEMORY.md");
+  const content = safeReadFile(memoryFile);
+  if (content === undefined) return undefined;
+
+  const lines = content.split("\n");
+  if (lines.length > MAX_MEMORY_LINES) {
+    return lines.slice(0, MAX_MEMORY_LINES).join("\n") + "\n... (truncated at 200 lines)";
+  }
+  return content;
+}
+
+/**
+ * Build the memory block to inject into the agent's system prompt.
+ * Also ensures the memory directory exists (creates it if needed).
+ */
+export function buildMemoryBlock(agentName: string, scope: MemoryScope, cwd: string): string {
+  const memoryDir = resolveMemoryDir(agentName, scope, cwd);
+  // Create the memory directory so the agent can immediately write to it
+  ensureMemoryDir(memoryDir);
+
+  const existingMemory = readMemoryIndex(memoryDir);
+
+  const header = `# Agent Memory
+
+You have a persistent memory directory at: ${memoryDir}/
+Memory scope: ${scope}
+
+This memory persists across sessions. Use it to build up knowledge over time.`;
+
+  const memoryContent = existingMemory
+    ? `\n\n## Current MEMORY.md\n${existingMemory}`
+    : `\n\nNo MEMORY.md exists yet. Create one at ${join(memoryDir, "MEMORY.md")} to start building persistent memory.`;
+
+  const instructions = `
+
+## Memory Instructions
+- MEMORY.md is an index file — keep it concise (under 200 lines). Lines after 200 are truncated.
+- Store detailed memories in separate files within ${memoryDir}/ and link to them from MEMORY.md.
+- Each memory file should use this frontmatter format:
+  \`\`\`markdown
+  ---
+  name: <memory name>
+  description: <one-line description>
+  type: <user|feedback|project|reference>
+  ---
+  <memory content>
+  \`\`\`
+- Update or remove memories that become outdated. Check for existing memories before creating duplicates.
+- You have Read, Write, and Edit tools available for managing memory files.`;
+
+  return header + memoryContent + instructions;
+}
+
+/**
+ * Build a read-only memory block for agents that lack write/edit tools.
+ * Does NOT create the memory directory — agents can only consume existing memory.
+ */
+export function buildReadOnlyMemoryBlock(agentName: string, scope: MemoryScope, cwd: string): string {
+  const memoryDir = resolveMemoryDir(agentName, scope, cwd);
+  const existingMemory = readMemoryIndex(memoryDir);
+
+  const header = `# Agent Memory (read-only)
+
+Memory scope: ${scope}
+You have read-only access to memory. You can reference existing memories but cannot create or modify them.`;
+
+  const memoryContent = existingMemory
+    ? `\n\n## Current MEMORY.md\n${existingMemory}`
+    : `\n\nNo memory is available yet. Other agents or sessions with write access can create memories for you to consume.`;
+
+  return header + memoryContent;
+}

package/src/model-resolver.ts

@@ -0,0 +1,81 @@
+/**
+ * Model resolution: exact match ("provider/modelId") with fuzzy fallback.
+ */
+
+export interface ModelEntry {
+  id: string;
+  name: string;
+  provider: string;
+}
+
+export interface ModelRegistry {
+  find(provider: string, modelId: string): any;
+  getAll(): any[];
+  getAvailable?(): any[];
+}
+
+/**
+ * Resolve a model string to a Model instance.
+ * Tries exact match first ("provider/modelId"), then fuzzy match against all available models.
+ * Returns the Model on success, or an error message string on failure.
+ */
+export function resolveModel(
+  input: string,
+  registry: ModelRegistry,
+): any | string {
+  // Available models (those with auth configured)
+  const all = (registry.getAvailable?.() ?? registry.getAll()) as ModelEntry[];
+  const availableSet = new Set(all.map(m => `${m.provider}/${m.id}`.toLowerCase()));
+
+  // 1. Exact match: "provider/modelId" — only if available (has auth)
+  const slashIdx = input.indexOf("/");
+  if (slashIdx !== -1) {
+    const provider = input.slice(0, slashIdx);
+    const modelId = input.slice(slashIdx + 1);
+    if (availableSet.has(input.toLowerCase())) {
+      const found = registry.find(provider, modelId);
+      if (found) return found;
+    }
+  }
+
+  // 2. Fuzzy match against available models
+  const query = input.toLowerCase();
+
+  // Score each model: prefer exact id match > id contains > name contains > provider+id contains
+  let bestMatch: ModelEntry | undefined;
+  let bestScore = 0;
+
+  for (const m of all) {
+    const id = m.id.toLowerCase();
+    const name = m.name.toLowerCase();
+    const full = `${m.provider}/${m.id}`.toLowerCase();
+
+    let score = 0;
+    if (id === query || full === query) {
+      score = 100; // exact
+    } else if (id.includes(query) || full.includes(query)) {
+      score = 60 + (query.length / id.length) * 30; // substring, prefer tighter matches
+    } else if (name.includes(query)) {
+      score = 40 + (query.length / name.length) * 20;
+    } else if (query.split(/[\s\-/]+/).every(part => id.includes(part) || name.includes(part) || m.provider.toLowerCase().includes(part))) {
+      score = 20; // all parts present somewhere
+    }
+
+    if (score > bestScore) {
+      bestScore = score;
+      bestMatch = m;
+    }
+  }
+
+  if (bestMatch && bestScore >= 20) {
+    const found = registry.find(bestMatch.provider, bestMatch.id);
+    if (found) return found;
+  }
+
+  // 3. No match — list available models
+  const modelList = all
+    .map(m => `  ${m.provider}/${m.id}`)
+    .sort()
+    .join("\n");
+  return `Model not found: "${input}".\n\nAvailable models:\n${modelList}`;
+}

package/src/output-file.ts

@@ -0,0 +1,96 @@
+/**
+ * output-file.ts — Streaming JSONL output file for agent transcripts.
+ *
+ * Creates a per-agent output file that streams conversation turns as JSONL,
+ * matching Claude Code's task output file format.
+ */
+
+import { appendFileSync, chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Encode a cwd path as a filesystem-safe directory name. Handles:
+ *   - POSIX:   "/home/user/project"        → "home-user-project"
+ *   - Windows: "C:\Users\foo\project"      → "Users-foo-project"
+ *   - UNC:     "\\\\server\\share\\project"  → "server-share-project"
+ */
+export function encodeCwd(cwd: string): string {
+  return cwd
+    .replace(/[/\\]/g, "-")        // both separators → dash
+    .replace(/^[A-Za-z]:-/, "")    // strip Windows drive prefix ("C:-")
+    .replace(/^-+/, "");           // strip leading dashes (POSIX root, UNC)
+}
+
+/** Create the output file path, ensuring the directory exists.
+ *  Mirrors Claude Code's layout: /tmp/{prefix}-{uid}/{encoded-cwd}/{sessionId}/tasks/{agentId}.output */
+export function createOutputFilePath(cwd: string, agentId: string, sessionId: string): string {
+  const encoded = encodeCwd(cwd);
+  const root = join(tmpdir(), `pi-subagents-${process.getuid?.() ?? 0}`);
+  mkdirSync(root, { recursive: true, mode: 0o700 });
+  // chmod is a no-op on Windows and throws on some Windows filesystems.
+  // On Unix we still want to enforce 0o700 past umask, so only swallow on Windows.
+  try {
+    chmodSync(root, 0o700);
+  } catch (err) {
+    if (process.platform !== "win32") throw err;
+  }
+  const dir = join(root, encoded, sessionId, "tasks");
+  mkdirSync(dir, { recursive: true });
+  return join(dir, `${agentId}.output`);
+}
+
+/** Write the initial user prompt entry. */
+export function writeInitialEntry(path: string, agentId: string, prompt: string, cwd: string): void {
+  const entry = {
+    isSidechain: true,
+    agentId,
+    type: "user",
+    message: { role: "user", content: prompt },
+    timestamp: new Date().toISOString(),
+    cwd,
+  };
+  writeFileSync(path, JSON.stringify(entry) + "\n", "utf-8");
+}
+
+/**
+ * Subscribe to session events and flush new messages to the output file on each turn_end.
+ * Returns a cleanup function that does a final flush and unsubscribes.
+ */
+export function streamToOutputFile(
+  session: AgentSession,
+  path: string,
+  agentId: string,
+  cwd: string,
+): () => void {
+  let writtenCount = 1; // initial user prompt already written
+
+  const flush = () => {
+    const messages = session.messages;
+    while (writtenCount < messages.length) {
+      const msg = messages[writtenCount];
+      const entry = {
+        isSidechain: true,
+        agentId,
+        type: msg.role === "assistant" ? "assistant" : msg.role === "user" ? "user" : "toolResult",
+        message: msg,
+        timestamp: new Date().toISOString(),
+        cwd,
+      };
+      try {
+        appendFileSync(path, JSON.stringify(entry) + "\n", "utf-8");
+      } catch { /* ignore write errors */ }
+      writtenCount++;
+    }
+  };
+
+  const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
+    if (event.type === "turn_end") flush();
+  });
+
+  return () => {
+    flush();
+    unsubscribe();
+  };
+}

package/src/prompts.ts

@@ -0,0 +1,105 @@
+/**
+ * prompts.ts — System prompt builder for agents.
+ */
+
+import type { AgentConfig, EnvInfo } from "./types.js";
+
+/** Extra sections to inject into the system prompt (memory, skills, etc.). */
+export interface PromptExtras {
+  /** Persistent memory content to inject (first 200 lines of MEMORY.md + instructions). */
+  memoryBlock?: string;
+  /** Preloaded skill contents to inject. */
+  skillBlocks?: { name: string; content: string }[];
+}
+
+/**
+ * Build the system prompt for an agent from its config.
+ *
+ * - "replace" mode: env header + config.systemPrompt (full control, no parent identity)
+ * - "append" mode: env header + parent system prompt + sub-agent context + config.systemPrompt
+ * - "append" with empty systemPrompt: pure parent clone
+ *
+ * Both modes prepend an `<active_agent name="${config.name}"/>` tag so downstream
+ * extensions (e.g. `@gotgenes/pi-permission-system`) can resolve per-agent policy
+ * inside the child session by parsing the system prompt.
+ *
+ * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
+ * @param extras  Optional extra sections to inject (memory, preloaded skills).
+ */
+export function buildAgentPrompt(
+  config: AgentConfig,
+  cwd: string,
+  env: EnvInfo,
+  parentSystemPrompt?: string,
+  extras?: PromptExtras,
+): string {
+  const activeAgentTag = `<active_agent name="${config.name}"/>\n\n`;
+
+  const envBlock = `# Environment
+Working directory: ${cwd}
+${env.isGitRepo ? `Git repository: yes\nBranch: ${env.branch}` : "Not a git repository"}
+Platform: ${env.platform}`;
+
+  // Build optional extras suffix
+  const extraSections: string[] = [];
+  if (extras?.memoryBlock) {
+    extraSections.push(extras.memoryBlock);
+  }
+  if (extras?.skillBlocks?.length) {
+    for (const skill of extras.skillBlocks) {
+      extraSections.push(
+        `\n# Preloaded Skill: ${skill.name}\n${skill.content}`,
+      );
+    }
+  }
+  const extrasSuffix =
+    extraSections.length > 0 ? "\n\n" + extraSections.join("\n") : "";
+
+  if (config.promptMode === "append") {
+    const identity = parentSystemPrompt || genericBase;
+
+    const bridge = `<sub_agent_context>
+You are operating as a sub-agent invoked to handle a specific task.
+- Use the read tool instead of cat/head/tail
+- Use the edit tool instead of sed/awk
+- Use the write tool instead of echo/heredoc
+- Use the find tool instead of bash find/ls for file search
+- Use the grep tool instead of bash grep/rg for content search
+- Make independent tool calls in parallel
+- Use absolute file paths
+- Do not use emojis
+- Be concise but complete
+</sub_agent_context>`;
+
+    const customSection = config.systemPrompt?.trim()
+      ? `\n\n<agent_instructions>\n${config.systemPrompt}\n</agent_instructions>`
+      : "";
+
+    return (
+      activeAgentTag +
+      envBlock +
+      "\n\n<inherited_system_prompt>\n" +
+      identity +
+      "\n</inherited_system_prompt>\n\n" +
+      bridge +
+      customSection +
+      extrasSuffix
+    );
+  }
+
+  // "replace" mode — env header + the config's full system prompt
+  const replaceHeader = `You are a pi coding agent sub-agent.
+You have been invoked to handle a specific task autonomously.
+
+${envBlock}`;
+
+  return (
+    activeAgentTag + replaceHeader + "\n\n" + config.systemPrompt + extrasSuffix
+  );
+}
+
+/** Fallback base prompt when parent system prompt is unavailable in append mode. */
+const genericBase = `# Role
+You are a general-purpose coding agent for complex, multi-step tasks.
+You have full access to read, write, edit files, and execute commands.
+Do what has been asked; nothing more, nothing less.`;

package/src/schedule-store.ts

@@ -0,0 +1,143 @@
+/**
+ * schedule-store.ts — File-backed store for scheduled subagents.
+ *
+ * Session-scoped: each pi session owns its own schedules at
+ * `<cwd>/.pi/subagent-schedules/<sessionId>.json`. `/new` starts a fresh
+ * empty store; `/resume` reloads.
+ *
+ * Concurrency model lifted from pi-chonky-tasks/src/task-store.ts: every
+ * mutation acquires a PID-based exclusion lock, re-reads the latest state
+ * from disk, applies the change, atomic-writes via temp+rename, releases.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { ScheduledSubagent, ScheduleStoreData } from "./types.js";
+
+const LOCK_RETRY_MS = 50;
+const LOCK_MAX_RETRIES = 100;
+
+function isProcessRunning(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function acquireLock(lockPath: string): void {
+  for (let i = 0; i < LOCK_MAX_RETRIES; i++) {
+    try {
+      writeFileSync(lockPath, `${process.pid}`, { flag: "wx" });
+      return;
+    } catch (e: any) {
+      if (e.code === "EEXIST") {
+        try {
+          const pid = parseInt(readFileSync(lockPath, "utf-8"), 10);
+          if (pid && !isProcessRunning(pid)) {
+            unlinkSync(lockPath);
+            continue;
+          }
+        } catch { /* ignore — try again */ }
+        const start = Date.now();
+        while (Date.now() - start < LOCK_RETRY_MS) { /* busy wait */ }
+        continue;
+      }
+      throw e;
+    }
+  }
+  throw new Error(`Failed to acquire schedule lock: ${lockPath}`);
+}
+
+function releaseLock(lockPath: string): void {
+  try { unlinkSync(lockPath); } catch { /* ignore */ }
+}
+
+/** Resolve the storage path for a session-scoped store. */
+export function resolveStorePath(cwd: string, sessionId: string): string {
+  return join(cwd, ".pi", "subagent-schedules", `${sessionId}.json`);
+}
+
+export class ScheduleStore {
+  private filePath: string;
+  private lockPath: string;
+  private jobs = new Map<string, ScheduledSubagent>();
+
+  constructor(filePath: string) {
+    this.filePath = filePath;
+    this.lockPath = filePath + ".lock";
+    mkdirSync(dirname(filePath), { recursive: true });
+    this.load();
+  }
+
+  /** Load from disk into the in-memory cache. Silent on parse errors. */
+  private load(): void {
+    if (!existsSync(this.filePath)) return;
+    try {
+      const data: ScheduleStoreData = JSON.parse(readFileSync(this.filePath, "utf-8"));
+      this.jobs.clear();
+      for (const j of data.jobs ?? []) this.jobs.set(j.id, j);
+    } catch { /* corrupt — start fresh, next save rewrites */ }
+  }
+
+  /** Atomic write via temp file + rename (POSIX-atomic). */
+  private save(): void {
+    const data: ScheduleStoreData = { version: 1, jobs: [...this.jobs.values()] };
+    const tmp = this.filePath + ".tmp";
+    writeFileSync(tmp, JSON.stringify(data, null, 2));
+    renameSync(tmp, this.filePath);
+  }
+
+  /** Acquire lock → reload → mutate → save → release. */
+  private withLock<T>(fn: () => T): T {
+    acquireLock(this.lockPath);
+    try {
+      this.load();
+      const result = fn();
+      this.save();
+      return result;
+    } finally {
+      releaseLock(this.lockPath);
+    }
+  }
+
+  /** Read-only — returns a snapshot of the in-memory cache. */
+  list(): ScheduledSubagent[] {
+    return [...this.jobs.values()];
+  }
+
+  /** Read-only check — uses the cache. */
+  hasName(name: string, exceptId?: string): boolean {
+    for (const j of this.jobs.values()) {
+      if (j.id !== exceptId && j.name === name) return true;
+    }
+    return false;
+  }
+
+  get(id: string): ScheduledSubagent | undefined {
+    return this.jobs.get(id);
+  }
+
+  add(job: ScheduledSubagent): void {
+    this.withLock(() => {
+      this.jobs.set(job.id, job);
+    });
+  }
+
+  update(id: string, patch: Partial<ScheduledSubagent>): ScheduledSubagent | undefined {
+    return this.withLock(() => {
+      const existing = this.jobs.get(id);
+      if (!existing) return undefined;
+      const updated = { ...existing, ...patch };
+      this.jobs.set(id, updated);
+      return updated;
+    });
+  }
+
+  remove(id: string): boolean {
+    return this.withLock(() => this.jobs.delete(id));
+  }
+
+  /** Delete the backing file (used when no jobs remain, optional cleanup). */
+  deleteFileIfEmpty(): void {
+    if (this.jobs.size === 0 && existsSync(this.filePath)) {
+      try { unlinkSync(this.filePath); } catch { /* ignore */ }
+    }
+  }
+}