@esso0428/pi-subagents 0.15.0

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,53 @@
+/**
+ * memory.ts — Persistent agent memory: per-agent memory directories that persist across sessions.
+ *
+ * Memory scopes:
+ *   - "user"    → getAgentDir()/agent-memory/{agent-name}/ (default ~/.pi/agent/agent-memory/, honors $PI_CODING_AGENT_DIR)
+ *   - "project" → .pi/agent-memory/{agent-name}/
+ *   - "local"   → .pi/agent-memory-local/{agent-name}/
+ *
+ * The user scope previously hardcoded ~/.pi/agent-memory/. That legacy location
+ * is still honored (read + write) when it exists and the new location doesn't,
+ * so existing memories aren't orphaned.
+ */
+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,165 @@
+/**
+ * memory.ts — Persistent agent memory: per-agent memory directories that persist across sessions.
+ *
+ * Memory scopes:
+ *   - "user"    → getAgentDir()/agent-memory/{agent-name}/ (default ~/.pi/agent/agent-memory/, honors $PI_CODING_AGENT_DIR)
+ *   - "project" → .pi/agent-memory/{agent-name}/
+ *   - "local"   → .pi/agent-memory-local/{agent-name}/
+ *
+ * The user scope previously hardcoded ~/.pi/agent-memory/. That legacy location
+ * is still honored (read + write) when it exists and the new location doesn't,
+ * so existing memories aren't orphaned.
+ */
+import { existsSync, lstatSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+/** 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": {
+            const current = join(getAgentDir(), "agent-memory", agentName);
+            // Legacy location from when this path was hardcoded. Keep using it if it
+            // already holds this agent's memory and the new location hasn't been
+            // created yet — otherwise existing memories would be silently orphaned.
+            const legacy = join(homedir(), ".pi", "agent-memory", agentName);
+            if (!existsSync(current) && existsSync(legacy) && !isSymlink(legacy)) {
+                return legacy;
+            }
+            return current;
+        }
+        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-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,80 @@
+/**
+ * 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. Normalize separators so cosmetic
+    // punctuation differences still match — e.g. "claude-haiku-4.5" and
+    // "claude-haiku-4-5" (dot vs dash in the version) resolve to the same model.
+    const normalize = (s) => s.toLowerCase().replace(/\./g, "-");
+    const query = normalize(input);
+    // 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 = normalize(m.id);
+        const name = normalize(m.name);
+        const full = normalize(`${m.provider}/${m.id}`);
+        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 (
+        // A trailing date-stamp token (e.g. "20251001") is optional, so a
+        // date-pinned config like "claude-haiku-4-5-20251001" still matches an
+        // undated registry id like "claude-haiku-4-5".
+        query
+            .split(/[\s\-/]+/)
+            .every(part => /^\d{8}$/.test(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. Provider fallback: a "provider/modelId" query that didn't match under the
+    // named provider (exact or fuzzy above) retries against all providers. The
+    // named provider is preferred when present; this only kicks in when it isn't,
+    // so the same model from another provider beats falling back to "inherit".
+    if (slashIdx !== -1) {
+        const bare = resolveModel(input.slice(slashIdx + 1), registry);
+        if (typeof bare !== "string")
+            return bare;
+    }
+    // 4. 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/nico-overrides.d.ts

@@ -0,0 +1,53 @@
+/**
+ * nico-overrides.ts — Read and apply agent overrides from `npm:pi-subagents`-style
+ * `settings.json` (`subagents.agentOverrides`).
+ *
+ * Priority (after `@tintinweb/pi-subagents` has resolved its own .md chain):
+ *   1. Local  JSON  (.pi/settings.json)  ← highest
+ *   2. Global JSON  (~/.pi/agent/settings.json)
+ *
+ * Overrides are applied to matching agents in the registry. If an agent name
+ * from the overrides does not exist in the registry, it is auto-registered
+ * using the override fields as the full definition (no .md file needed).
+ *
+ * Skill mapping (Nico string[] → tintinweb true | string[] | false):
+ *   ["*"]     → true   (all skills)
+ *   ["foo"]   → ["foo"] (only listed)
+ *   [] | false → false  (none)
+ *   omitted   → true   (all, fallback)
+ */
+import type { AgentConfig } from "./types.js";
+export interface NicoAgentOverride {
+    model?: string | false;
+    thinking?: string | false;
+    fallbackModels?: string[];
+    systemPrompt?: string;
+    systemPromptMode?: "append" | "replace";
+    inheritProjectContext?: boolean;
+    inheritSkills?: boolean;
+    defaultContext?: "fresh" | "fork" | false;
+    disabled?: boolean;
+    skills?: string[] | false;
+    tools?: string[] | false;
+    completionGuard?: boolean;
+    toolBudget?: Record<string, unknown>;
+}
+/**
+ * Read subagents.agentOverrides and subagents.defaultModel from both local
+ * and global Nico-style settings.json. Local overrides global on key collision.
+ */
+export declare function readNicoAgentOverrides(cwd: string): {
+    overrides: Record<string, NicoAgentOverride>;
+    defaultModel: string | undefined;
+};
+export declare function resolveNicoSkills(skills: string[] | false | undefined): true | string[] | false;
+/**
+ * Apply a Nico-style override to an existing tintinweb AgentConfig.
+ * JSON values directly overwrite the config (highest priority).
+ */
+export declare function applyNicoOverride(agent: AgentConfig, override: NicoAgentOverride, nicoDefaultModel?: string): AgentConfig;
+/**
+ * Apply all Nico overrides to a map of agents (mutating in-place).
+ * Agents that don't exist yet are auto-registered from the override.
+ */
+export declare function applyNicoOverridesToMap(agents: Map<string, AgentConfig>, overrides: Record<string, NicoAgentOverride>, defaultModel?: string): void;

package/dist/nico-overrides.js

@@ -0,0 +1,169 @@
+/**
+ * nico-overrides.ts — Read and apply agent overrides from `npm:pi-subagents`-style
+ * `settings.json` (`subagents.agentOverrides`).
+ *
+ * Priority (after `@tintinweb/pi-subagents` has resolved its own .md chain):
+ *   1. Local  JSON  (.pi/settings.json)  ← highest
+ *   2. Global JSON  (~/.pi/agent/settings.json)
+ *
+ * Overrides are applied to matching agents in the registry. If an agent name
+ * from the overrides does not exist in the registry, it is auto-registered
+ * using the override fields as the full definition (no .md file needed).
+ *
+ * Skill mapping (Nico string[] → tintinweb true | string[] | false):
+ *   ["*"]     → true   (all skills)
+ *   ["foo"]   → ["foo"] (only listed)
+ *   [] | false → false  (none)
+ *   omitted   → true   (all, fallback)
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
+// ============================================================================
+// Reader
+// ============================================================================
+/**
+ * Read subagents.agentOverrides and subagents.defaultModel from both local
+ * and global Nico-style settings.json. Local overrides global on key collision.
+ */
+export function readNicoAgentOverrides(cwd) {
+    const merged = {};
+    let defaultModel;
+    // Global: ~/.pi/agent/settings.json
+    const globalPath = join(getAgentDir(), "settings.json");
+    const globalSettings = readNicoSettingsFile(globalPath);
+    if (globalSettings) {
+        mergeOverrides(merged, globalSettings.agentOverrides);
+        if (defaultModel === undefined)
+            defaultModel = globalSettings.defaultModel;
+    }
+    // Local: .pi/settings.json
+    const localPath = join(cwd, ".pi", "settings.json");
+    if (existsSync(localPath)) {
+        const localSettings = readNicoSettingsFile(localPath);
+        if (localSettings) {
+            mergeOverrides(merged, localSettings.agentOverrides);
+            if (localSettings.defaultModel !== undefined)
+                defaultModel = localSettings.defaultModel;
+        }
+    }
+    return { overrides: merged, defaultModel };
+}
+function readNicoSettingsFile(filePath) {
+    if (!existsSync(filePath))
+        return undefined;
+    try {
+        const raw = JSON.parse(readFileSync(filePath, "utf-8"));
+        const sub = raw?.subagents;
+        if (!sub || typeof sub !== "object")
+            return undefined;
+        return sub;
+    }
+    catch {
+        // Silently skip — bad Nico config must not break tintinweb
+        return undefined;
+    }
+}
+function mergeOverrides(target, source) {
+    if (!source)
+        return;
+    for (const [name, override] of Object.entries(source)) {
+        target[name] = { ...target[name], ...override };
+    }
+}
+// ============================================================================
+// Skill converter: Nico string[] → tintinweb true | string[] | false
+// ============================================================================
+export function resolveNicoSkills(skills) {
+    // Not set → inherit all (tintinweb default)
+    if (skills === undefined)
+        return true;
+    // Explicit false / empty array → none
+    if (skills === false || skills.length === 0)
+        return false;
+    // ["*"] → all skills
+    if (skills.length === 1 && skills[0] === "*")
+        return true;
+    // Specific list
+    return [...skills];
+}
+// ============================================================================
+// Applier — override existing agent
+// ============================================================================
+/**
+ * Apply a Nico-style override to an existing tintinweb AgentConfig.
+ * JSON values directly overwrite the config (highest priority).
+ */
+export function applyNicoOverride(agent, override, nicoDefaultModel) {
+    let modified = false;
+    let next = agent;
+    // model: explicit override wins; else use defaultModel when agent has none
+    if (override.model !== undefined) {
+        next = { ...next, model: override.model === false ? undefined : override.model };
+        modified = true;
+    }
+    else if (nicoDefaultModel !== undefined && next.model === undefined) {
+        next = { ...next, model: nicoDefaultModel };
+        modified = true;
+    }
+    if (override.thinking !== undefined) {
+        next = { ...next, thinking: override.thinking === false ? undefined : override.thinking };
+        modified = true;
+    }
+    if (override.systemPrompt !== undefined) {
+        next = { ...next, systemPrompt: override.systemPrompt };
+        modified = true;
+    }
+    if (override.disabled !== undefined) {
+        next = { ...next, enabled: !override.disabled };
+        modified = true;
+    }
+    if (override.tools !== undefined) {
+        next = { ...next, builtinToolNames: override.tools === false ? [] : [...override.tools] };
+        modified = true;
+    }
+    return modified ? next : agent;
+}
+// ============================================================================
+// Auto-register — create AgentConfig from override when agent doesn't exist
+// ============================================================================
+function createAgentFromOverride(name, override, defaultModel) {
+    return {
+        name,
+        displayName: name,
+        description: `Auto-registered from npm:pi-subagents JSON settings`,
+        builtinToolNames: override.tools !== undefined
+            ? (override.tools === false ? [] : [...override.tools])
+            : [...BUILTIN_TOOL_NAMES],
+        extensions: true,
+        skills: resolveNicoSkills(override.skills),
+        model: override.model !== undefined ? (override.model === false ? undefined : override.model) : defaultModel,
+        thinking: override.thinking !== undefined
+            ? (override.thinking === false ? undefined : override.thinking)
+            : undefined,
+        systemPrompt: override.systemPrompt ?? "",
+        promptMode: override.systemPromptMode === "append" ? "append" : "replace",
+        enabled: !(override.disabled ?? false),
+        source: "global",
+        isDefault: false,
+    };
+}
+// ============================================================================
+// Bulk apply
+// ============================================================================
+/**
+ * Apply all Nico overrides to a map of agents (mutating in-place).
+ * Agents that don't exist yet are auto-registered from the override.
+ */
+export function applyNicoOverridesToMap(agents, overrides, defaultModel) {
+    for (const [name, override] of Object.entries(overrides)) {
+        const existing = agents.get(name);
+        if (existing) {
+            agents.set(name, applyNicoOverride(existing, override, defaultModel));
+        }
+        else {
+            agents.set(name, createAgentFromOverride(name, override, defaultModel));
+        }
+    }
+}

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 "@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 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;