studiograph 1.3.48-next.11 → 1.3.48-next.110

package/README.md

@@ -57,15 +57,15 @@ A Studiograph workspace is a directory containing a `.studiograph/` configuratio
 ```
 my-studio/
 ├── .studiograph/           # Config repo (workspace.json, team roster, migrations)
-├── acme-rebrand/           # Collection (client project)
-├── website-redesign/       # Collection (another project)
-├── team-knowledge/         # Collection (processes, standards)
+├── acme-rebrand/           # Folder (client project)
+├── website-redesign/       # Folder (another project)
+├── team-knowledge/         # Folder (processes, standards)
 └── private/                # Local-only, gitignored
 ```
 
-### Collections
+### Folders
 
-Each subdirectory is a **collection** — a Git repo containing related entities. Collections are lightweight and flexible: one per project, one for team knowledge, one for business operations, or however your team thinks.
+Each subdirectory is a **folder** — a Git repo containing related entities. Folders are lightweight and flexible: one per project, one for team knowledge, one for business operations, or however your team thinks.
 
 ### Entities
 
@@ -133,7 +133,7 @@ There are 17 built-in entity types (project, meeting, person, organization, deci
 
 | Command | Description |
 |---------|-------------|
-| `studiograph collection` | Manage collections (add, list, rename, remove) |
+| `studiograph folder` | Manage folders (add, list, rename, remove) |
 | `studiograph provision` | Push workspace config to GitHub as a separate repo |
 | `studiograph members` | Manage team members and roles |
 | `studiograph index` | Rebuild search index |
@@ -190,7 +190,7 @@ Studiograph exposes a [Model Context Protocol](https://modelcontextprotocol.io/)
 
 If you're running from the workspace directory, you can omit the path: `studiograph mcp`.
 
-MCP tools available: `list_repos`, `list_entities`, `get_entity`, `search_entities`, `create_entity`, `update_entity`, `delete_entity`.
+MCP tools available: `list_repos`, `create_repo`, `list_entities`, `get_entity`, `search_entities`, `create_entity`, `update_entity`, `delete_entity`.
 
 ### Third-Party Connectors
 

package/dist/agent/agent-pool.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Agent Pool — manages per-session Agent instances for concurrent access.
+ *
+ * Each session (folder chat, private chat, capture) gets its own Agent
+ * with independent conversation history. Shared resources (tools, system
+ * prompt, model) are created once and passed to each new agent.
+ *
+ * Per-session locking ensures only one call runs per session at a time,
+ * while different sessions can run in parallel.
+ */
+import { Agent } from '@mariozechner/pi-agent-core';
+import type { AuthUser } from '../services/auth-service.js';
+import type { MutationEvent } from './tools/graph-tools.js';
+export interface AgentContext {
+    user: AuthUser | null;
+    onHighlight?: ((ids: string[]) => void) | null;
+    onMutation?: ((m: MutationEvent) => void) | null;
+    /**
+     * Called by tool wrappers at the start (`enter`) and end (`leave`) of any
+     * mutation that targets a folder. Powers the "X's agent is acting" sidebar
+     * chip via wsHub.handleAgentActivity. Optional — no-op if unset.
+     */
+    onAgentActivity?: ((action: 'enter' | 'leave' | 'heartbeat', repo: string) => void) | null;
+    /**
+     * Wired only by the quick-capture flow. When the agent calls the
+     * `nothing_to_capture` tool, this receives the structured reason so the
+     * UI can render a toast without going through freeform assistant prose
+     * (which is variable-quality and leaks the followups marker).
+     */
+    onNothingToCapture?: ((reason: string) => void) | null;
+}
+export interface SharedAgentConfig {
+    /** Factory to create a fresh Agent instance with tools, prompt, and model. */
+    createAgent: (userId?: number) => Agent;
+    /** Callback to load custom tools async (called once per new agent). */
+    loadCustomTools?: (agent: Agent) => void;
+    /** Base sessions directory. */
+    sessionsDir: string;
+}
+export declare class AgentPool {
+    private pool;
+    private reapTimer;
+    private config;
+    /** Per-session context — set before each call, read by tool closures. */
+    private contextMap;
+    constructor(config: SharedAgentConfig);
+    /**
+     * Get the current context for a session (used by tool closures).
+     * Returns null user if no context is set.
+     */
+    getContext(sessionId: string): AgentContext;
+    /**
+     * Acquire an agent for a session, run a callback, then release.
+     * Per-session locking ensures serialized access within the same session.
+     * Different sessions run in parallel.
+     */
+    withAgent<T>(sessionId: string, ctx: AgentContext, fn: (agent: Agent) => Promise<T>, opts?: {
+        userId?: number;
+        fallbackHistory?: Array<{
+            role: string;
+            content: string;
+        }>;
+    }): Promise<T>;
+    /** Get the raw Agent for a session (for subscribe/streaming). Must be used with withAgent. */
+    getAgent(sessionId: string): Agent | null;
+    /** Abort the agent for a session. */
+    abort(sessionId: string): void;
+    /** Save all sessions and stop the reaper. */
+    shutdown(): Promise<void>;
+    /** Clear all saved session files for a user. */
+    clearSessions(userId?: number): number;
+    get size(): number;
+    /** Find the session ID for a given agent instance. */
+    findSessionForAgent(agent: Agent): string | null;
+    private getOrCreate;
+    private loadSession;
+    private saveSession;
+    private getUserDir;
+    private pruneSessions;
+    private reap;
+}

package/dist/agent/agent-pool.js

@@ -0,0 +1,231 @@
+/**
+ * Agent Pool — manages per-session Agent instances for concurrent access.
+ *
+ * Each session (folder chat, private chat, capture) gets its own Agent
+ * with independent conversation history. Shared resources (tools, system
+ * prompt, model) are created once and passed to each new agent.
+ *
+ * Per-session locking ensures only one call runs per session at a time,
+ * while different sessions can run in parallel.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, unlinkSync, statSync } from 'fs';
+import { join, resolve } from 'path';
+const IDLE_TIMEOUT_MS = 10 * 60_000; // 10 minutes
+const REAP_INTERVAL_MS = 60_000; // check every 60s
+const MAX_SESSIONS_PER_USER = 20;
+export class AgentPool {
+    pool = new Map();
+    reapTimer = null;
+    config;
+    /** Per-session context — set before each call, read by tool closures. */
+    contextMap = new Map();
+    constructor(config) {
+        this.config = config;
+        this.reapTimer = setInterval(() => this.reap(), REAP_INTERVAL_MS);
+    }
+    /**
+     * Get the current context for a session (used by tool closures).
+     * Returns null user if no context is set.
+     */
+    getContext(sessionId) {
+        return this.contextMap.get(sessionId) ?? { user: null };
+    }
+    /**
+     * Acquire an agent for a session, run a callback, then release.
+     * Per-session locking ensures serialized access within the same session.
+     * Different sessions run in parallel.
+     */
+    async withAgent(sessionId, ctx, fn, opts) {
+        const entry = this.getOrCreate(sessionId, opts?.userId, opts?.fallbackHistory);
+        // Chain on the session's lock to serialize calls
+        const result = entry.lock.then(async () => {
+            entry.lastUsedAt = Date.now();
+            this.contextMap.set(sessionId, ctx);
+            try {
+                return await fn(entry.agent);
+            }
+            finally {
+                this.contextMap.delete(sessionId);
+                // Save session after each call
+                this.saveSession(entry);
+            }
+        });
+        // Update the lock — next caller for this session waits for this one
+        entry.lock = result.then(() => { }, () => { });
+        return result;
+    }
+    /** Get the raw Agent for a session (for subscribe/streaming). Must be used with withAgent. */
+    getAgent(sessionId) {
+        return this.pool.get(sessionId)?.agent ?? null;
+    }
+    /** Abort the agent for a session. */
+    abort(sessionId) {
+        this.pool.get(sessionId)?.agent.abort();
+    }
+    /** Save all sessions and stop the reaper. */
+    async shutdown() {
+        if (this.reapTimer) {
+            clearInterval(this.reapTimer);
+            this.reapTimer = null;
+        }
+        for (const entry of this.pool.values()) {
+            this.saveSession(entry);
+        }
+        this.pool.clear();
+    }
+    /** Clear all saved session files for a user. */
+    clearSessions(userId) {
+        const dir = this.getUserDir(userId);
+        if (!existsSync(dir))
+            return 0;
+        const files = readdirSync(dir).filter(f => f.endsWith('.json'));
+        for (const f of files) {
+            try {
+                unlinkSync(join(dir, f));
+            }
+            catch { /* ignore */ }
+        }
+        return files.length;
+    }
+    get size() {
+        return this.pool.size;
+    }
+    /** Find the session ID for a given agent instance. */
+    findSessionForAgent(agent) {
+        for (const [sid, entry] of this.pool) {
+            if (entry.agent === agent)
+                return sid;
+        }
+        return null;
+    }
+    // ── Private ──
+    getOrCreate(sessionId, userId, fallbackHistory) {
+        const existing = this.pool.get(sessionId);
+        if (existing)
+            return existing;
+        // Create a fresh agent instance (pass userId for per-user context like briefing)
+        const agent = this.config.createAgent(userId);
+        this.config.loadCustomTools?.(agent);
+        // Try loading session from disk
+        const loaded = this.loadSession(agent, sessionId, userId);
+        // Fallback: rebuild the transcript as proper role-tagged messages when
+        // the saved session file is missing (cleared, corrupted, or first turn
+        // on a fresh container). The previous implementation flattened the
+        // entire history into a single role: 'user' message with "Assistant:" /
+        // "User:" prefixes embedded as plain text — the model then had to parse
+        // those textual prefixes to know what was its own output, and would
+        // sometimes mis-attribute its prior turns to the user (e.g. "you
+        // mentioned that Watowa consults" when the user had just said "we
+        // consult on..."). Mapping each turn to its actual role tag lets the
+        // model distinguish reliably without parsing-by-prefix.
+        if (!loaded && fallbackHistory && fallbackHistory.length > 0) {
+            const model = agent.state.model;
+            const baseTime = Date.now() - fallbackHistory.length * 1000;
+            agent.state.messages = fallbackHistory.map((m, i) => {
+                const timestamp = baseTime + i * 1000;
+                if (m.role === 'assistant') {
+                    return {
+                        role: 'assistant',
+                        content: [{ type: 'text', text: m.content }],
+                        api: model.api,
+                        provider: model.provider,
+                        model: model.id,
+                        usage: {
+                            input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0,
+                            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+                        },
+                        stopReason: 'stop',
+                        timestamp,
+                    };
+                }
+                return {
+                    role: 'user',
+                    content: [{ type: 'text', text: m.content }],
+                    timestamp,
+                };
+            });
+        }
+        const entry = {
+            agent,
+            sessionId,
+            userId,
+            lastUsedAt: Date.now(),
+            lock: Promise.resolve(),
+        };
+        this.pool.set(sessionId, entry);
+        return entry;
+    }
+    loadSession(agent, sessionId, userId) {
+        const userDir = this.getUserDir(userId);
+        const sessionPath = join(userDir, `${sessionId}.json`);
+        // Path traversal guard
+        if (!resolve(sessionPath).startsWith(resolve(userDir)))
+            return false;
+        if (existsSync(sessionPath)) {
+            try {
+                const data = JSON.parse(readFileSync(sessionPath, 'utf-8'));
+                if (Array.isArray(data.messages) && data.messages.length > 0) {
+                    agent.state.messages = data.messages;
+                    return true;
+                }
+            }
+            catch { /* corrupted — fall through */ }
+        }
+        return false;
+    }
+    saveSession(entry) {
+        const messages = entry.agent.state.messages;
+        if (messages.length === 0)
+            return;
+        const userDir = this.getUserDir(entry.userId);
+        if (!existsSync(userDir)) {
+            mkdirSync(userDir, { recursive: true });
+        }
+        const sessionPath = join(userDir, `${entry.sessionId}.json`);
+        writeFileSync(sessionPath, JSON.stringify({
+            sessionId: entry.sessionId,
+            updatedAt: new Date().toISOString(),
+            messages,
+        }), 'utf-8');
+        this.pruneSessions(userDir, MAX_SESSIONS_PER_USER);
+    }
+    getUserDir(userId) {
+        if (userId)
+            return join(this.config.sessionsDir, String(userId));
+        return this.config.sessionsDir;
+    }
+    pruneSessions(dir, keep) {
+        if (!existsSync(dir))
+            return;
+        const files = readdirSync(dir)
+            .filter(f => f.endsWith('.json'))
+            .map(f => {
+            try {
+                return { name: f, mtime: statSync(join(dir, f)).mtimeMs };
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter(Boolean);
+        if (files.length <= keep)
+            return;
+        files.sort((a, b) => b.mtime - a.mtime);
+        for (const f of files.slice(keep)) {
+            try {
+                unlinkSync(join(dir, f.name));
+            }
+            catch { /* ignore */ }
+        }
+    }
+    reap() {
+        const now = Date.now();
+        for (const [key, entry] of this.pool) {
+            if (now - entry.lastUsedAt > IDLE_TIMEOUT_MS) {
+                this.saveSession(entry);
+                this.pool.delete(key);
+            }
+        }
+    }
+}
+//# sourceMappingURL=agent-pool.js.map

package/dist/agent/agent-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-pool.js","sourceRoot":"","sources":["../../src/agent/agent-pool.ts"],"names":[],"mappings":"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"}

package/dist/agent/followups.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Follow-up suggestion marker parsing.
+ *
+ * The system prompt instructs the agent to end every response with an HTML
+ * comment of the form:
+ *
+ *   <!-- followups: ["prompt 1", "prompt 2", "prompt 3"] -->
+ *
+ * Each transport (web, CLI, MCP) must strip this marker from the content it
+ * displays and surface the suggestions in whatever form fits its UI — chips
+ * in the web client, a dim numbered list in the CLI, a `suggestions` field
+ * in MCP, etc.
+ *
+ * Keep the parser in one place so a new transport can't silently leak the
+ * raw marker.
+ */
+export interface ParsedFollowups {
+    /** Response content with the marker removed and trailing whitespace trimmed. */
+    content: string;
+    /** Parsed suggestions, if the marker was present and valid JSON. */
+    suggestions?: string[];
+}
+/**
+ * Parse a raw agent response and split it into clean content plus optional
+ * follow-up suggestions. Malformed markers are left in place (the caller can
+ * choose to strip or render as-is), matching the existing web behaviour.
+ */
+export declare function parseFollowups(raw: string): ParsedFollowups;
+/**
+ * Return true if `text` contains an *unclosed* followups marker — used by
+ * streaming consumers to know whether to defer rendering the tail of a
+ * delta until the closing `-->` arrives.
+ */
+export declare function hasOpenFollowupsMarker(text: string): boolean;

package/dist/agent/followups.js

@@ -0,0 +1,52 @@
+/**
+ * Follow-up suggestion marker parsing.
+ *
+ * The system prompt instructs the agent to end every response with an HTML
+ * comment of the form:
+ *
+ *   <!-- followups: ["prompt 1", "prompt 2", "prompt 3"] -->
+ *
+ * Each transport (web, CLI, MCP) must strip this marker from the content it
+ * displays and surface the suggestions in whatever form fits its UI — chips
+ * in the web client, a dim numbered list in the CLI, a `suggestions` field
+ * in MCP, etc.
+ *
+ * Keep the parser in one place so a new transport can't silently leak the
+ * raw marker.
+ */
+/** Matches the trailing followups HTML comment at end of text (with optional trailing whitespace). */
+const FOLLOWUPS_RE = /<!--\s*followups:\s*(\[[\s\S]*?\])\s*-->\s*$/;
+/**
+ * Parse a raw agent response and split it into clean content plus optional
+ * follow-up suggestions. Malformed markers are left in place (the caller can
+ * choose to strip or render as-is), matching the existing web behaviour.
+ */
+export function parseFollowups(raw) {
+    const match = raw.match(FOLLOWUPS_RE);
+    if (!match)
+        return { content: raw };
+    try {
+        const parsed = JSON.parse(match[1]);
+        if (!Array.isArray(parsed) || !parsed.every((s) => typeof s === 'string')) {
+            return { content: raw };
+        }
+        const content = raw.slice(0, match.index).trimEnd();
+        return { content, suggestions: parsed };
+    }
+    catch {
+        return { content: raw };
+    }
+}
+/**
+ * Return true if `text` contains an *unclosed* followups marker — used by
+ * streaming consumers to know whether to defer rendering the tail of a
+ * delta until the closing `-->` arrives.
+ */
+export function hasOpenFollowupsMarker(text) {
+    const lastOpen = text.lastIndexOf('<!--');
+    if (lastOpen < 0)
+        return false;
+    const lastClose = text.lastIndexOf('-->');
+    return lastClose < lastOpen;
+}
+//# sourceMappingURL=followups.js.map

package/dist/agent/followups.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"followups.js","sourceRoot":"","sources":["../../src/agent/followups.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,sGAAsG;AACtG,MAAM,YAAY,GAAG,8CAA8C,CAAC;AASpE;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;IAEpC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,EAAE,CAAC;YAC1E,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;QAC1B,CAAC;QACD,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;QACpD,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;IAC1B,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,QAAQ,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/B,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IAC1C,OAAO,SAAS,GAAG,QAAQ,CAAC;AAC9B,CAAC"}

package/dist/agent/orchestrator.d.ts

@@ -10,6 +10,7 @@ import { WorkspaceConfig } from '../core/types.js';
 import { GitUser } from '../services/git.js';
 import { type MutationEvent } from './tools/graph-tools.js';
 import type { AuthUser } from '../services/auth-service.js';
+import { AgentPool } from './agent-pool.js';
 export interface AgentConfig {
     workspacePath: string;
     workspaceConfig: WorkspaceConfig;
@@ -22,6 +23,15 @@ export interface AgentConfig {
     recentMemory?: string;
     /** Shared WorkspaceManager instance (used by server to share state with agent). */
     workspaceManager?: WorkspaceManager;
+    /** Shared MessageService instance (for searching folder messages). */
+    messageService?: import('../services/message-service.js').MessageService;
+    /**
+     * Called after the agent mutates an entity on disk, so the server can
+     * push the new content into any active Y.Doc and keep live editors in
+     * sync. Without this, agent edits bypass the Y.Doc and cause content
+     * duplication on the next resync.
+     */
+    onEntityContentMutation?: (repo: string, entityType: string, entityId: string) => void;
 }
 export interface AgentResponse {
     content: string;
@@ -34,25 +44,28 @@ export interface AgentResponse {
 export declare class AgentOrchestrator {
     private workspacePath;
     private workspaceManager;
-    private agent;
+    private pool;
     private config;
     private gitUser;
     private skillsDirs;
     private toolsDirs;
     private registryRef;
-    private _highlightCallback;
-    private _mutationCallback;
-    private _currentUser;
     private authService;
+    private messageService;
     private recentMemory?;
-    private currentSessionId;
     private sessionsDir;
+    private onEntityContentMutation?;
+    private _currentUser;
+    private _highlightCallback;
+    private _mutationCallback;
+    private currentSessionId;
+    private _sessionUserId;
     constructor(config: AgentConfig);
     /**
      * Create Pi-Mono agent with tools and system prompt.
      * Custom tools and skills are loaded asynchronously via initAsync().
      */
-    private createAgent;
+    private createAgentInstance;
     /**
      * Load custom JS tools from app/workspace tool dirs and append to the agent.
      * Runs async after construction — custom tools may not be available for the
@@ -64,6 +77,32 @@ export declare class AgentOrchestrator {
      * Build the full system prompt: base prompt + eager skill content + skill index.
      */
     private buildSystemPrompt;
+    /**
+     * Enumerate skill entities across all folders the user can access. Each
+     * skill becomes a SkillMeta with a `graph://<repo>/<id>` sentinel
+     * entrypoint. Priority order: user's private folder first, then shared
+     * folders alphabetically. First occurrence of a given name wins.
+     */
+    private getPromptRepoScope;
+    private enumerateGraphSkills;
+    /**
+     * Load the markdown body of a skill entity by (repo, id).
+     */
+    private readGraphSkillBody;
+    /**
+     * Build a workspace identity section from graph entities.
+     * Reads organization, person, practice-area, and guideline entries
+     * to compose a concise identity summary for the system prompt.
+     * Returns null if no organization entries exist.
+     */
+    private buildWorkspaceIdentity;
+    /**
+     * Per-repo subfolder summary for the system prompt. Lists each accessible
+     * repo with up to MAX_PER_REPO subfolder paths so the agent can route new
+     * entries into existing folders without calling list_folders for every
+     * decision. Refresh cadence is per-session (system prompt is built once).
+     */
+    private buildFolderInventory;
     /**
      * Fallback system prompt when prompts/system.md is not found.
      */
@@ -71,7 +110,23 @@ export declare class AgentOrchestrator {
     /**
      * Send a message to the agent
      */
+    /**
+     * Send a message and await the full agent response.
+     * Uses the current session (set via switchSession) or a default session.
+     */
     chat(userMessage: string): Promise<AgentResponse>;
+    /**
+     * Send a message with an explicit session ID and context.
+     * Preferred over the legacy setCurrentUser + switchSession + chat pattern.
+     */
+    chatInSession(sessionId: string, userMessage: string, opts?: {
+        user?: AuthUser | null;
+        userId?: number;
+        fallbackHistory?: Array<{
+            role: string;
+            content: string;
+        }>;
+    }): Promise<AgentResponse>;
     /**
      * Get workspace manager (for tools)
      */
@@ -90,7 +145,7 @@ export declare class AgentOrchestrator {
      */
     getRepoNames(): string[];
     /**
-     * Set the current authenticated user for per-collection access filtering.
+     * Set the current authenticated user for per-folder access filtering.
      * Called per-request by the chat endpoint. Null = full access (API key / open mode).
      */
     setCurrentUser(user: AuthUser | null): void;
@@ -111,36 +166,34 @@ export declare class AgentOrchestrator {
      */
     emitMutation(m: MutationEvent): void;
     /**
-     * Expose the raw pi-agent-core Agent instance.
+     * Expose the raw pi-agent-core Agent instance for a session (for SSE streaming).
+     * Returns the default session agent if no sessionId specified.
      */
-    getAgent(): Agent;
-    /** Abort the current agent run (if any). */
-    abort(): void;
+    getAgent(sessionId?: string): Agent | null;
+    /** Get the agent pool (for advanced callers that need direct pool access). */
+    getPool(): AgentPool;
+    /** Abort the agent for a session. */
+    abort(sessionId?: string): void;
     /**
      * Get the current session ID (null if none active).
      */
     getCurrentSessionId(): string | null;
     /**
-     * Switch the agent to a different session.
-     * - Same session → no-op
-     * - Existing session file → restore messages from disk
-     * - No file but fallback history → inject as context message
-     * - Nothing → clear messages for a fresh start
+     * Switch session (backward compat — sets state for next chat() call).
+     * With the pool, actual session loading happens lazily in withAgent().
      */
     switchSession(sessionId: string, fallbackHistory?: Array<{
         role: string;
         content: string;
-    }>): Promise<void>;
+    }>, userId?: number): Promise<void>;
     /**
-     * Save the current session's messages to disk.
+     * Save session (backward compat — pool auto-saves after each withAgent call).
      */
     saveSession(): void;
     /**
      * Clear all saved sessions from disk.
      */
     clearSessions(): number;
-    /**
-     * Keep only the N most recent session files by mtime.
-     */
-    private pruneSessions;
+    /** Shut down the agent pool (save all sessions, stop idle reaper). */
+    shutdown(): Promise<void>;
 }