@by-lua/lspec-subagents 1.0.1

package/dist/invocation-config.d.ts

@@ -0,0 +1,22 @@
+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 declare function resolveAgentInvocationConfig(agentConfig: AgentConfig | undefined, params: AgentInvocationParams): {
+    modelInput?: string;
+    modelFromParams: boolean;
+    thinking?: ThinkingLevel;
+    maxTurns?: number;
+    inheritContext: boolean;
+    runInBackground: boolean;
+    isolated: boolean;
+    isolation?: IsolationMode;
+};
+export declare function resolveJoinMode(defaultJoinMode: JoinMode, runInBackground: boolean): JoinMode | undefined;
+export {};

package/dist/invocation-config.js

@@ -0,0 +1,15 @@
+export function resolveAgentInvocationConfig(agentConfig, params) {
+    return {
+        modelInput: agentConfig?.model ?? params.model,
+        modelFromParams: agentConfig?.model == null && params.model != null,
+        thinking: (agentConfig?.thinking ?? params.thinking),
+        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, runInBackground) {
+    return runInBackground ? defaultJoinMode : undefined;
+}

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/model-config-loader.d.ts

@@ -0,0 +1,58 @@
+/**
+ * model-config-loader.ts — Load centralized model configuration for L-Spec subagents.
+ *
+ * Inspired by oh-my-opencode-slim's model config approach.
+ *
+ * Resolution order (highest priority wins):
+ *   1. Project:  <cwd>/.pi/lspec-model-config.json
+ *   2. Global:   ~/.pi/agent/lspec-model-config.json
+ *   3. Embedded: hardcoded defaults in this file
+ */
+export interface ModelConfig {
+    /** Map of agent name → model string (e.g. "claude-sonnet-4" or "provider/modelId") */
+    agents: Record<string, string>;
+}
+/** The placeholder marker prefix/suffix used in default-agents.ts */
+export declare const MODEL_PLACEHOLDER_PREFIX = "{{model:";
+export declare const MODEL_PLACEHOLDER_SUFFIX = "}}";
+/**
+ * Check if a model string is a placeholder like "{{model:explorer}}"
+ */
+export declare function isModelPlaceholder(model: string): boolean;
+/**
+ * Extract agent name from a placeholder like "{{model:explorer}}" → "explorer"
+ */
+export declare function parseModelPlaceholder(model: string): string | null;
+/**
+ * Resolve a model placeholder to the actual model string from config.
+ * Returns the resolved model, or undefined if the placeholder can't be resolved.
+ */
+export declare function resolveModelPlaceholder(model: string | undefined, config: ModelConfig): string | undefined;
+/**
+ * Resolve all model placeholders in a map of agent configs.
+ * Modifies the map in place.
+ */
+export declare function resolveAllPlaceholders(agents: Map<string, {
+    model?: string;
+}>, config: ModelConfig): void;
+/**
+ * Load model config from disk, merging global + project overrides.
+ * Returns the merged config.
+ */
+export declare function loadModelConfig(cwd: string): ModelConfig;
+/** Re-export for convenience — returns a fully resolved model for an agent. */
+export declare function getModelForAgent(agentName: string, cwd: string): string | undefined;
+/**
+ * Get the global model config file path.
+ */
+export declare function getGlobalModelConfigPath(): string;
+/**
+ * Get the project model config file path.
+ */
+export declare function getProjectModelConfigPath(cwd: string): string;
+/**
+ * Save a model assignment for an agent to the config file.
+ * Updates global config by default, or project config if specified.
+ * Preserves existing entries and metadata keys (_note, _docs, etc).
+ */
+export declare function saveModelForAgent(agentName: string, model: string, target?: "global" | "project", cwd?: string): void;

package/dist/model-config-loader.js

@@ -0,0 +1,157 @@
+/**
+ * model-config-loader.ts — Load centralized model configuration for L-Spec subagents.
+ *
+ * Inspired by oh-my-opencode-slim's model config approach.
+ *
+ * Resolution order (highest priority wins):
+ *   1. Project:  <cwd>/.pi/lspec-model-config.json
+ *   2. Global:   ~/.pi/agent/lspec-model-config.json
+ *   3. Embedded: hardcoded defaults in this file
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+/** Embedded defaults — used when no config file exists. Using generic models as reference. */
+const EMBEDDED_DEFAULTS = {
+    agents: {
+        orchestrator: "claude-sonnet-4",
+        explorer: "gpt-4o-mini",
+        librarian: "claude-sonnet-4",
+        oracle: "claude-opus-4",
+        designer: "claude-sonnet-4",
+        fixer: "claude-sonnet-4",
+        observer: "gpt-4o-mini",
+        council: "claude-opus-4",
+        councillor: "gpt-4o-mini",
+    },
+};
+/** The placeholder marker prefix/suffix used in default-agents.ts */
+export const MODEL_PLACEHOLDER_PREFIX = "{{model:";
+export const MODEL_PLACEHOLDER_SUFFIX = "}}";
+/**
+ * Check if a model string is a placeholder like "{{model:explorer}}"
+ */
+export function isModelPlaceholder(model) {
+    return model.startsWith(MODEL_PLACEHOLDER_PREFIX) && model.endsWith(MODEL_PLACEHOLDER_SUFFIX);
+}
+/**
+ * Extract agent name from a placeholder like "{{model:explorer}}" → "explorer"
+ */
+export function parseModelPlaceholder(model) {
+    if (!isModelPlaceholder(model))
+        return null;
+    return model.slice(MODEL_PLACEHOLDER_PREFIX.length, -MODEL_PLACEHOLDER_SUFFIX.length);
+}
+/**
+ * Resolve a model placeholder to the actual model string from config.
+ * Returns the resolved model, or undefined if the placeholder can't be resolved.
+ */
+export function resolveModelPlaceholder(model, config) {
+    if (!model)
+        return undefined;
+    if (!isModelPlaceholder(model))
+        return model;
+    const agentName = parseModelPlaceholder(model);
+    if (!agentName)
+        return undefined;
+    return config.agents[agentName];
+}
+/**
+ * Resolve all model placeholders in a map of agent configs.
+ * Modifies the map in place.
+ */
+export function resolveAllPlaceholders(agents, config) {
+    for (const [, agent] of agents) {
+        if (agent.model && isModelPlaceholder(agent.model)) {
+            const resolved = resolveModelPlaceholder(agent.model, config);
+            if (resolved) {
+                agent.model = resolved;
+            }
+        }
+    }
+}
+/**
+ * Load model config from disk, merging global + project overrides.
+ * Returns the merged config.
+ */
+export function loadModelConfig(cwd) {
+    const config = structuredClone(EMBEDDED_DEFAULTS);
+    const globalDir = join(getAgentDir());
+    const projectDir = join(cwd, ".pi");
+    // Load global config (lower priority)
+    const globalPath = join(globalDir, "lspec-model-config.json");
+    loadAndMerge(globalPath, config);
+    // Load project config (higher priority — overwrites)
+    const projectPath = join(projectDir, "lspec-model-config.json");
+    loadAndMerge(projectPath, config);
+    return config;
+}
+/**
+ * Load a JSON config file and merge its agents into the config object.
+ */
+function loadAndMerge(path, config) {
+    if (!existsSync(path))
+        return;
+    try {
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        // Skip _note, _docs keys — they're metadata
+        if (parsed.agents && typeof parsed.agents === "object") {
+            for (const [key, value] of Object.entries(parsed.agents)) {
+                if (typeof value === "string") {
+                    config.agents[key] = value;
+                }
+            }
+        }
+    }
+    catch {
+        // Silently ignore malformed config files
+    }
+}
+/** Re-export for convenience — returns a fully resolved model for an agent. */
+export function getModelForAgent(agentName, cwd) {
+    const config = loadModelConfig(cwd);
+    return config.agents[agentName];
+}
+/**
+ * Get the global model config file path.
+ */
+export function getGlobalModelConfigPath() {
+    return join(getAgentDir(), "lspec-model-config.json");
+}
+/**
+ * Get the project model config file path.
+ */
+export function getProjectModelConfigPath(cwd) {
+    return join(cwd, ".pi", "lspec-model-config.json");
+}
+/**
+ * Save a model assignment for an agent to the config file.
+ * Updates global config by default, or project config if specified.
+ * Preserves existing entries and metadata keys (_note, _docs, etc).
+ */
+export function saveModelForAgent(agentName, model, target = "global", cwd) {
+    const configPath = target === "project"
+        ? getProjectModelConfigPath(cwd ?? process.cwd())
+        : getGlobalModelConfigPath();
+    // Read existing config or create new
+    let existing = {};
+    if (existsSync(configPath)) {
+        try {
+            const raw = readFileSync(configPath, "utf-8");
+            existing = JSON.parse(raw);
+        }
+        catch {
+            existing = {};
+        }
+    }
+    // Update the agents section
+    if (!existing.agents || typeof existing.agents !== "object") {
+        existing.agents = {};
+    }
+    existing.agents[agentName] = model;
+    // Ensure directory exists
+    mkdirSync(join(configPath, ".."), { recursive: true });
+    // Write back
+    writeFileSync(configPath, JSON.stringify(existing, null, 2) + "\n", "utf-8");
+}

package/dist/model-resolver.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 declare function resolveModel(input: string, registry: ModelRegistry): any | string;

package/dist/model-resolver.js

@@ -0,0 +1,62 @@
+/**
+ * Model resolution: exact match ("provider/modelId") with fuzzy fallback.
+ */
+/**
+ * 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, registry) {
+    // Available models (those with auth configured)
+    const all = (registry.getAvailable?.() ?? registry.getAll());
+    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;
+    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/dist/output-file.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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";
+/**
+ * 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 declare function encodeCwd(cwd: string): string;
+/** 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,86 @@
+/**
+ * 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";
+/**
+ * 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) {
+    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, agentId, sessionId) {
+    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, 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

@@ -0,0 +1,29 @@
+/**
+ * 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. permission/policy systems) 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 declare function buildAgentPrompt(config: AgentConfig, cwd: string, env: EnvInfo, parentSystemPrompt?: string, extras?: PromptExtras): string;