@tintinweb/pi-subagents 0.4.10 → 0.5.0

package/dist/memory.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 type { MemoryScope } from "./types.js";
+/**
+ * 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 declare function isUnsafeName(name: string): boolean;
+/**
+ * Returns true if the given path is a symlink (defense against symlink attacks).
+ */
+export declare function isSymlink(filePath: string): boolean;
+/**
+ * Safely read a file, rejecting symlinks.
+ * Returns undefined if the file doesn't exist, is a symlink, or can't be read.
+ */
+export declare function safeReadFile(filePath: string): string | undefined;
+/**
+ * Resolve the memory directory path for a given agent + scope + cwd.
+ * Throws if agentName contains path traversal characters.
+ */
+export declare function resolveMemoryDir(agentName: string, scope: MemoryScope, cwd: string): string;
+/**
+ * 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 declare function ensureMemoryDir(memoryDir: string): void;
+/**
+ * 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 declare function readMemoryIndex(memoryDir: string): string | undefined;
+/**
+ * Build the memory block to inject into the agent's system prompt.
+ * Also ensures the memory directory exists (creates it if needed).
+ */
+export declare function buildMemoryBlock(agentName: string, scope: MemoryScope, cwd: string): string;
+/**
+ * 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 declare function buildReadOnlyMemoryBlock(agentName: string, scope: MemoryScope, cwd: string): string;

package/dist/memory.js

@@ -0,0 +1,151 @@
+/**
+ * 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";
+/** 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) {
+    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) {
+    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) {
+    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, scope, cwd) {
+    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) {
+    // 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) {
+    // 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, scope, cwd) {
+    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, scope, cwd) {
+    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/dist/output-file.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 type { AgentSession } from "@mariozechner/pi-coding-agent";
+/** Create the output file path, ensuring the directory exists.
+ *  Mirrors Claude Code's layout: /tmp/{prefix}-{uid}/{encoded-cwd}/{sessionId}/tasks/{agentId}.output */
+export declare function createOutputFilePath(cwd: string, agentId: string, sessionId: string): string;
+/** Write the initial user prompt entry. */
+export declare function writeInitialEntry(path: string, agentId: string, prompt: string, cwd: string): void;
+/**
+ * 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 declare function streamToOutputFile(session: AgentSession, path: string, agentId: string, cwd: string): () => void;

package/dist/output-file.js

@@ -0,0 +1,66 @@
+/**
+ * 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";
+/** 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, agentId, sessionId) {
+    const encoded = cwd.replace(/\//g, "-").replace(/^-/, "");
+    const root = join(tmpdir(), `pi-subagents-${process.getuid?.() ?? 0}`);
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    chmodSync(root, 0o700);
+    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, agentId, prompt, cwd) {
+    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, path, agentId, cwd) {
+    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) => {
+        if (event.type === "turn_end")
+            flush();
+    });
+    return () => {
+        flush();
+        unsubscribe();
+    };
+}

package/dist/prompts.d.ts

@@ -2,6 +2,16 @@
  * 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.
  *
@@ -10,5 +20,6 @@ import type { AgentConfig, EnvInfo } from "./types.js";
  * - "append" with empty systemPrompt: pure parent clone
  *
  * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
+ * @param extras  Optional extra sections to inject (memory, preloaded skills).
  */
-export declare function buildAgentPrompt(config: AgentConfig, cwd: string, env: EnvInfo, parentSystemPrompt?: string): string;
+export declare function buildAgentPrompt(config: AgentConfig, cwd: string, env: EnvInfo, parentSystemPrompt?: string, extras?: PromptExtras): string;

package/dist/prompts.js

@@ -9,12 +9,24 @@
  * - "append" with empty systemPrompt: pure parent clone
  *
  * @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, cwd, env, parentSystemPrompt) {
+export function buildAgentPrompt(config, cwd, env, parentSystemPrompt, extras) {
     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 = [];
+    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>
@@ -32,14 +44,14 @@ You are operating as a sub-agent invoked to handle a specific task.
         const customSection = config.systemPrompt?.trim()
             ? `\n\n<agent_instructions>\n${config.systemPrompt}\n</agent_instructions>`
             : "";
-        return envBlock + "\n\n<inherited_system_prompt>\n" + identity + "\n</inherited_system_prompt>\n\n" + bridge + customSection;
+        return 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 replaceHeader + "\n\n" + config.systemPrompt;
+    return replaceHeader + "\n\n" + config.systemPrompt + extrasSuffix;
 }
 /** Fallback base prompt when parent system prompt is unavailable in append mode. */
 const genericBase = `# Role

package/dist/skill-loader.d.ts

@@ -0,0 +1,19 @@
+/**
+ * skill-loader.ts — Preload specific skill files and inject their content into the system prompt.
+ *
+ * When skills is a string[], reads each named skill from .pi/skills/ or ~/.pi/skills/
+ * and returns their content for injection into the agent's system prompt.
+ */
+export interface PreloadedSkill {
+    name: string;
+    content: string;
+}
+/**
+ * Attempt to load named skills from project and global skill directories.
+ * Looks for: <dir>/<name>.md, <dir>/<name>.txt, <dir>/<name>
+ *
+ * @param skillNames  List of skill names to preload.
+ * @param cwd         Working directory for project-level skills.
+ * @returns Array of loaded skills (missing skills are skipped with a warning comment).
+ */
+export declare function preloadSkills(skillNames: string[], cwd: string): PreloadedSkill[];

package/dist/skill-loader.js

@@ -0,0 +1,67 @@
+/**
+ * skill-loader.ts — Preload specific skill files and inject their content into the system prompt.
+ *
+ * When skills is a string[], reads each named skill from .pi/skills/ or ~/.pi/skills/
+ * and returns their content for injection into the agent's system prompt.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { isUnsafeName, safeReadFile } from "./memory.js";
+/**
+ * Attempt to load named skills from project and global skill directories.
+ * Looks for: <dir>/<name>.md, <dir>/<name>.txt, <dir>/<name>
+ *
+ * @param skillNames  List of skill names to preload.
+ * @param cwd         Working directory for project-level skills.
+ * @returns Array of loaded skills (missing skills are skipped with a warning comment).
+ */
+export function preloadSkills(skillNames, cwd) {
+    const results = [];
+    for (const name of skillNames) {
+        // Unlike memory (which throws on unsafe names because it's part of agent setup),
+        // skills are optional — skip gracefully to avoid blocking agent startup.
+        if (isUnsafeName(name)) {
+            results.push({ name, content: `(Skill "${name}" skipped: name contains path traversal characters)` });
+            continue;
+        }
+        const content = findAndReadSkill(name, cwd);
+        if (content !== undefined) {
+            results.push({ name, content });
+        }
+        else {
+            // Include a note about missing skills so the agent knows it was requested but not found
+            results.push({ name, content: `(Skill "${name}" not found in .pi/skills/ or ~/.pi/skills/)` });
+        }
+    }
+    return results;
+}
+/**
+ * Search for a skill file in project and global directories.
+ * Project-level takes priority over global.
+ */
+function findAndReadSkill(name, cwd) {
+    const projectDir = join(cwd, ".pi", "skills");
+    const globalDir = join(homedir(), ".pi", "skills");
+    // Try project first, then global
+    for (const dir of [projectDir, globalDir]) {
+        const content = tryReadSkillFile(dir, name);
+        if (content !== undefined)
+            return content;
+    }
+    return undefined;
+}
+/**
+ * Try to read a skill file from a directory.
+ * Tries extensions in order: .md, .txt, (no extension)
+ */
+function tryReadSkillFile(dir, name) {
+    const extensions = [".md", ".txt", ""];
+    for (const ext of extensions) {
+        const path = join(dir, name + ext);
+        // safeReadFile rejects symlinks to prevent reading arbitrary files
+        const content = safeReadFile(path);
+        if (content !== undefined)
+            return content.trim();
+    }
+    return undefined;
+}

package/dist/types.d.ts

@@ -1,19 +1,25 @@
 /**
  * types.ts — Type definitions for the subagent system.
  */
-import type { AgentSession } from "@mariozechner/pi-coding-agent";
 import type { ThinkingLevel } from "@mariozechner/pi-agent-core";
+import type { AgentSession } from "@mariozechner/pi-coding-agent";
 export type { ThinkingLevel };
 /** Agent type: any string name (built-in defaults or user-defined). */
 export type SubagentType = string;
 /** Names of the three embedded default agents. */
 export declare const DEFAULT_AGENT_NAMES: readonly ["general-purpose", "Explore", "Plan"];
+/** Memory scope for persistent agent memory. */
+export type MemoryScope = "user" | "project" | "local";
+/** Isolation mode for agent execution. */
+export type IsolationMode = "worktree";
 /** Unified agent configuration — used for both default and user-defined agents. */
 export interface AgentConfig {
     name: string;
     displayName?: string;
     description: string;
     builtinToolNames?: string[];
+    /** Tool denylist — these tools are removed even if `builtinToolNames` or extensions include them. */
+    disallowedTools?: string[];
     /** true = inherit all, string[] = only listed, false = none */
     extensions: true | string[] | false;
     /** true = inherit all, string[] = only listed, false = none */
@@ -29,6 +35,10 @@ export interface AgentConfig {
     runInBackground: boolean;
     /** Default for spawn: no extension tools */
     isolated: boolean;
+    /** Persistent memory scope — agents with memory get a persistent directory and MEMORY.md */
+    memory?: MemoryScope;
+    /** Isolation mode — "worktree" runs the agent in a temporary git worktree */
+    isolation?: IsolationMode;
     /** true = this is an embedded default agent (informational) */
     isDefault?: boolean;
     /** false = agent is hidden from the registry */
@@ -54,6 +64,40 @@ export interface AgentRecord {
     joinMode?: JoinMode;
     /** Set when result was already consumed via get_subagent_result — suppresses completion notification. */
     resultConsumed?: boolean;
+    /** Steering messages queued before the session was ready. */
+    pendingSteers?: string[];
+    /** Worktree info if the agent is running in an isolated worktree. */
+    worktree?: {
+        path: string;
+        branch: string;
+    };
+    /** Worktree cleanup result after agent completion. */
+    worktreeResult?: {
+        hasChanges: boolean;
+        branch?: string;
+    };
+    /** The tool_use_id from the original Agent tool call. */
+    toolCallId?: string;
+    /** Path to the streaming output transcript file. */
+    outputFile?: string;
+    /** Cleanup function for the output file stream subscription. */
+    outputCleanup?: () => void;
+}
+/** Details attached to custom notification messages for visual rendering. */
+export interface NotificationDetails {
+    id: string;
+    description: string;
+    status: string;
+    toolUses: number;
+    turnCount: number;
+    maxTurns?: number;
+    totalTokens: number;
+    durationMs: number;
+    outputFile?: string;
+    error?: string;
+    resultPreview: string;
+    /** Additional agents in a group notification. */
+    others?: NotificationDetails[];
 }
 export interface EnvInfo {
     isGitRepo: boolean;

package/dist/ui/agent-widget.d.ts

@@ -36,6 +36,10 @@ export interface AgentActivity {
             };
         };
     };
+    /** Current turn count. */
+    turnCount: number;
+    /** Effective max turns for this agent (undefined = unlimited). */
+    maxTurns?: number;
 }
 /** Metadata attached to Agent tool results for custom rendering. */
 export interface AgentDetails {
@@ -54,11 +58,17 @@ export interface AgentDetails {
     modelName?: string;
     /** Notable config tags (e.g. ["thinking: high", "isolated"]). */
     tags?: string[];
+    /** Current turn count. */
+    turnCount?: number;
+    /** Effective max turns (undefined = unlimited). */
+    maxTurns?: number;
     agentId?: string;
     error?: string;
 }
 /** Format a token count compactly: "33.8k token", "1.2M token". */
 export declare function formatTokens(count: number): string;
+/** Format turn count with optional max limit: "⟳5≤30" or "⟳5". */
+export declare function formatTurns(turnCount: number, maxTurns?: number | null): string;
 /** Format milliseconds as human-readable duration. */
 export declare function formatMs(ms: number): string;
 /** Format duration from start/completed timestamps. */
@@ -79,6 +89,12 @@ export declare class AgentWidget {
     private finishedTurnAge;
     /** How many extra turns errors/aborted agents linger (completed agents clear after 1 turn). */
     private static readonly ERROR_LINGER_TURNS;
+    /** Whether the widget callback is currently registered with the TUI. */
+    private widgetRegistered;
+    /** Cached TUI reference from widget factory callback, used for requestRender(). */
+    private tui;
+    /** Last status bar text, used to avoid redundant setStatus calls. */
+    private lastStatusText;
     constructor(manager: AgentManager, agentActivity: Map<string, AgentActivity>);
     /** Set the UI context (grabbed from first tool execution). */
     setUICtx(ctx: UICtx): void;
@@ -95,6 +111,11 @@ export declare class AgentWidget {
     markFinished(agentId: string): void;
     /** Render a finished agent line. */
     private renderFinishedLine;
+    /**
+     * Render the widget content. Called from the registered widget's render() callback,
+     * reading live state each time instead of capturing it in a closure.
+     */
+    private renderWidget;
     /** Force an immediate widget update. */
     update(): void;
     dispose(): void;