@amodalai/runtime 0.1.16 → 0.1.17

package/dist/src/session/admin-file-tools.js

@@ -0,0 +1,240 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Admin-only file tools for reading, writing, and deleting agent config files.
+ * These tools are registered on admin sessions only, and only for local repos.
+ *
+ * Ported from the old agent-runner.ts admin tool implementation.
+ */
+import { readFile, writeFile, unlink, mkdir } from 'node:fs/promises';
+import * as path from 'node:path';
+// ---------------------------------------------------------------------------
+// Path validation
+// ---------------------------------------------------------------------------
+const ALLOWED_REPO_DIRS = [
+    'skills/',
+    'knowledge/',
+    'connections/',
+    'stores/',
+    'pages/',
+    'automations/',
+    'evals/',
+    'agents/',
+    'tools/',
+    'amodal_packages/', // installed packages (read-only)
+];
+const BLOCKED_FILENAMES = [
+    '.env',
+    'amodal.json',
+    'package.json',
+    'pnpm-lock.yaml',
+    'tsconfig.json',
+];
+const READ_ONLY_DIRS = [
+    'amodal_packages/',
+];
+/** @internal Exported for testing */
+export function isAllowedRepoPath(relPath) {
+    const basename = path.basename(relPath);
+    if (BLOCKED_FILENAMES.includes(basename))
+        return false;
+    return ALLOWED_REPO_DIRS.some((dir) => relPath.startsWith(dir));
+}
+function isReadOnlyPath(relPath) {
+    return READ_ONLY_DIRS.some((dir) => relPath.startsWith(dir));
+}
+function validatePath(repoRoot, rawPath) {
+    if (!rawPath || rawPath.startsWith('/')) {
+        return { error: 'Path must be relative to the repo root (no leading /)' };
+    }
+    if (rawPath.includes('..')) {
+        return { error: 'Path traversal (..) is not allowed' };
+    }
+    const normalized = path.normalize(rawPath);
+    if (!isAllowedRepoPath(normalized)) {
+        return { error: `Path "${normalized}" is not in an allowed directory. Allowed: ${ALLOWED_REPO_DIRS.join(', ')}. Blocked files: ${BLOCKED_FILENAMES.join(', ')}` };
+    }
+    const resolved = path.resolve(repoRoot, normalized);
+    if (!resolved.startsWith(repoRoot)) {
+        return { error: 'Resolved path escapes the repo directory' };
+    }
+    return { resolved, relative: normalized };
+}
+// ---------------------------------------------------------------------------
+// Base adapter matching upstream DeclarativeTool interface
+// ---------------------------------------------------------------------------
+function createToolAdapter(opts) {
+    return {
+        name: opts.name,
+        displayName: opts.name,
+        description: opts.description,
+        kind: 'declarative',
+        parameterSchema: opts.parameters,
+        get isReadOnly() { return opts.name === 'read_repo_file'; },
+        get toolAnnotations() { return undefined; },
+        get schema() { return this.getSchema(); },
+        getSchema() {
+            return {
+                name: opts.name,
+                description: opts.description,
+                parametersJsonSchema: opts.parameters,
+            };
+        },
+        build(params) {
+            return {
+                name: opts.name,
+                params,
+                execute: async () => opts.execute(params),
+            };
+        },
+        silentBuild(params) {
+            return this.build(params);
+        },
+        async validateBuildAndExecute(params) {
+            return opts.execute(params);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Tool factories
+// ---------------------------------------------------------------------------
+export function createReadRepoFileTool(repoRoot) {
+    return createToolAdapter({
+        name: 'read_repo_file',
+        description: 'Read a file from the agent repo. Path is relative to repo root. Allowed directories: skills/, knowledge/, connections/, stores/, pages/, automations/, evals/, agents/, tools/.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path relative to repo root (e.g. "knowledge/formatting-rules.md")' },
+            },
+            required: ['path'],
+        },
+        async execute(params) {
+            const rawPath = String(params['path'] ?? '');
+            const validation = validatePath(repoRoot, rawPath);
+            if ('error' in validation) {
+                return { llmContent: `Error: ${validation.error}`, error: { message: validation.error, type: 'VALIDATION_ERROR' } };
+            }
+            try {
+                const content = await readFile(validation.resolved, 'utf-8');
+                return { llmContent: content, returnDisplay: `Read ${validation.relative}` };
+            }
+            catch (err) {
+                const isNotFound = err instanceof Error && 'code' in err && (err.code) === 'ENOENT'; // eslint-disable-line @typescript-eslint/no-unsafe-type-assertion -- checking errno;
+                const msg = isNotFound ? `File not found: ${validation.relative}` : (err instanceof Error ? err.message : String(err));
+                return { llmContent: `Error: ${msg}`, error: { message: msg, type: 'EXECUTION_FAILED' } };
+            }
+        },
+    });
+}
+export function createWriteRepoFileTool(repoRoot) {
+    return createToolAdapter({
+        name: 'write_repo_file',
+        description: 'Create or update a file in the agent repo. Use this to add skills, knowledge, pages, automations, tools, store schemas, evals, connection docs, or agent overrides. Path is relative to repo root. Allowed directories: skills/, knowledge/, connections/, stores/, pages/, automations/, evals/, agents/, tools/.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path relative to repo root (e.g. "knowledge/formatting-rules.md")' },
+                content: { type: 'string', description: 'Full file content to write' },
+            },
+            required: ['path', 'content'],
+        },
+        async execute(params) {
+            const rawPath = String(params['path'] ?? '');
+            const content = String(params['content'] ?? '');
+            const validation = validatePath(repoRoot, rawPath);
+            if ('error' in validation) {
+                return { llmContent: `Error: ${validation.error}`, error: { message: validation.error, type: 'VALIDATION_ERROR' } };
+            }
+            if (isReadOnlyPath(validation.relative)) {
+                return { llmContent: `Error: ${validation.relative} is read-only (installed package)`, error: { message: 'Cannot write to installed packages', type: 'VALIDATION_ERROR' } };
+            }
+            if (!content) {
+                return { llmContent: 'Error: Content must not be empty', error: { message: 'Content must not be empty', type: 'VALIDATION_ERROR' } };
+            }
+            try {
+                await mkdir(path.dirname(validation.resolved), { recursive: true });
+                await writeFile(validation.resolved, content, 'utf-8');
+                return { llmContent: `Wrote ${validation.relative} (${String(content.length)} bytes)`, returnDisplay: `Wrote ${validation.relative}` };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { llmContent: `Error: ${msg}`, error: { message: msg, type: 'EXECUTION_FAILED' } };
+            }
+        },
+    });
+}
+export function createDeleteRepoFileTool(repoRoot) {
+    return createToolAdapter({
+        name: 'delete_repo_file',
+        description: 'Delete a file from the agent repo. Always confirm with the user before deleting. Path is relative to repo root. Same directory restrictions as write_repo_file.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path relative to repo root (e.g. "evals/old-test.md")' },
+            },
+            required: ['path'],
+        },
+        async execute(params) {
+            const rawPath = String(params['path'] ?? '');
+            const validation = validatePath(repoRoot, rawPath);
+            if ('error' in validation) {
+                return { llmContent: `Error: ${validation.error}`, error: { message: validation.error, type: 'VALIDATION_ERROR' } };
+            }
+            if (isReadOnlyPath(validation.relative)) {
+                return { llmContent: `Error: ${validation.relative} is read-only (installed package)`, error: { message: 'Cannot delete installed packages', type: 'VALIDATION_ERROR' } };
+            }
+            try {
+                await unlink(validation.resolved);
+                return { llmContent: `Deleted ${validation.relative}`, returnDisplay: `Deleted ${validation.relative}` };
+            }
+            catch (err) {
+                const isNotFound = err instanceof Error && 'code' in err && (err.code) === 'ENOENT'; // eslint-disable-line @typescript-eslint/no-unsafe-type-assertion -- checking errno;
+                const msg = isNotFound ? `File not found: ${validation.relative}` : (err instanceof Error ? err.message : String(err));
+                return { llmContent: `Error: ${msg}`, error: { message: msg, type: 'EXECUTION_FAILED' } };
+            }
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Internal API tool — lets admin query the local runtime's own endpoints
+// ---------------------------------------------------------------------------
+export function createInternalApiTool(getPort) {
+    return createToolAdapter({
+        name: 'internal_api',
+        description: `Query the amodal runtime's internal API. Use this to check eval results, connection health, agent context, store data, and automation status. The endpoint is relative to the local server (e.g. "/api/evals/runs" or "/inspect/health"). Only GET requests are supported.`,
+        parameters: {
+            type: 'object',
+            properties: {
+                endpoint: { type: 'string', description: 'API path (e.g. "/api/evals/runs", "/inspect/health", "/api/stores")' },
+            },
+            required: ['endpoint'],
+        },
+        async execute(params) {
+            const endpoint = String(params['endpoint'] ?? '');
+            const port = getPort();
+            if (!port) {
+                return { llmContent: 'Error: Server not ready', error: { message: 'Server not ready', type: 'EXECUTION_FAILED' } };
+            }
+            try {
+                const resp = await fetch(`http://127.0.0.1:${port}${endpoint}`);
+                const text = await resp.text();
+                try {
+                    const json = JSON.parse(text);
+                    return { llmContent: JSON.stringify(json, null, 2), returnDisplay: `GET ${endpoint} → ${resp.status}` };
+                }
+                catch {
+                    return { llmContent: text, returnDisplay: `GET ${endpoint} → ${resp.status}` };
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { llmContent: `Error: ${msg}`, error: { message: msg, type: 'EXECUTION_FAILED' } };
+            }
+        },
+    });
+}
+//# sourceMappingURL=admin-file-tools.js.map

package/dist/src/session/admin-file-tools.js.map

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

package/dist/src/session/session-manager.d.ts

@@ -54,6 +54,23 @@ export interface ManagedSession {
     /** App ID for this session */
     appId?: string;
 }
+/** Shape of a stored session record (from platform API or session store). */
+export interface StoredSessionRecord {
+    id: string;
+    app_id: string;
+    messages: SessionMessage[];
+    status: string;
+    model?: string;
+    provider?: string;
+}
+/**
+ * Pluggable session store for loading stored session history.
+ * Implementations are provided by the hosting layer.
+ */
+export interface SessionStore {
+    /** Fetch a stored session record by ID. Returns null if not found. */
+    getSession(appId: string, sessionId: string, token: string): Promise<StoredSessionRecord | null>;
+}
 export interface SessionManagerOptions {
     /** Base config parameters to clone for each session */
     baseParams: AmodalConfigParameters;
@@ -71,7 +88,13 @@ export interface SessionManagerOptions {
     shellExecutor?: CustomShellExecutor;
     /** Shared store backend (local dev) */
     storeBackend?: StoreBackend;
+    /** Pluggable session store for hydration (if not provided, falls back to platform API) */
+    sessionStore?: SessionStore;
 }
+/**
+ * Manages per-request sessions: creates Config + GeminiClient + Scheduler
+ * instances, tracks them by ID, and cleans up expired sessions.
+ */
 export declare class SessionManager {
     private readonly sessions;
     private baseParams;
@@ -81,9 +104,12 @@ export declare class SessionManager {
     private readonly toolExecutor?;
     private readonly shellExecutor?;
     private readonly sharedStoreBackend?;
+    private readonly sessionStore?;
     private cleanupTimer;
     /** Deduplicates concurrent hydration requests for the same conversation */
     private readonly pendingHydrations;
+    /** Shared MCP manager for all sessions (lazy-initialized, reused) */
+    private sharedMcpManager?;
     /** Persistent MCP manager for inspect operations (lazy-initialized) */
     private inspectMcp?;
     private inspectMcpInitialized;
@@ -134,9 +160,13 @@ export declare class SessionManager {
     reregister(session: ManagedSession, newId: string): void;
     /**
      * Create an admin session for the config chat.
-     * Uses admin agent skills/knowledge but the current repo's connections.
+     * Uses admin agent skills/knowledge but the current repo's connections/stores.
+     *
+     * Temporarily swaps repo fields so create() builds the prompt with admin
+     * content, then restores the original repo. This mirrors the old approach
+     * of building an adminRepo overlay.
      */
-    createAdminSession(): Promise<ManagedSession>;
+    createAdminSession(getPort?: () => number | null): Promise<ManagedSession>;
     /**
      * Get a persistent MCP manager for inspect/health operations.
      * Lazy-initialized on first call, reused across requests.
@@ -145,7 +175,11 @@ export declare class SessionManager {
     /**
      * Initialize MCP servers for a session from repo connections.
      */
-    private initMcp;
+    /**
+     * Initialize the shared MCP manager (once, reused across sessions).
+     * Avoids reconnecting MCP servers for every eval/judge/admin session.
+     */
+    private initSharedMcp;
     /**
      * Build the list of upstream core tools to enable based on repo config.
      * Only tools relevant to the Amodal runtime are included.

package/dist/src/session/session-manager.js

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 import { randomUUID } from 'node:crypto';
-import { AmodalConfig, Scheduler, ROOT_SCHEDULER_ID, ApprovalMode, PolicyDecision, AgentSDK, buildDefaultPrompt, PlanModeManager, McpManager, ensureAdminAgent, loadAdminAgent, } from '@amodalai/core';
+import { AmodalConfig, Scheduler, ROOT_SCHEDULER_ID, ApprovalMode, PolicyDecision, AgentSDK, buildDefaultPrompt, resolveScopeLabels, generateFieldGuidance, generateAlternativeLookupGuidance, PlanModeManager, McpManager, ensureAdminAgent, loadAdminAgent, } from '@amodalai/core';
 import { convertSessionMessagesToHistory } from './history-converter.js';
 /**
  * Resolve env: references in a string record.
@@ -26,6 +26,10 @@ function resolveEnvRefs(record) {
 const DEFAULT_TTL_MS = 30 * 60 * 1000; // 30 minutes
 const DEFAULT_CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
 const ASK_USER_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+/**
+ * Manages per-request sessions: creates Config + GeminiClient + Scheduler
+ * instances, tracks them by ID, and cleans up expired sessions.
+ */
 export class SessionManager {
     sessions = new Map();
     baseParams;
@@ -35,9 +39,12 @@ export class SessionManager {
     toolExecutor;
     shellExecutor;
     sharedStoreBackend;
+    sessionStore;
     cleanupTimer = null;
     /** Deduplicates concurrent hydration requests for the same conversation */
     pendingHydrations = new Map();
+    /** Shared MCP manager for all sessions (lazy-initialized, reused) */
+    sharedMcpManager;
     /** Persistent MCP manager for inspect operations (lazy-initialized) */
     inspectMcp;
     inspectMcpInitialized = false;
@@ -49,6 +56,7 @@ export class SessionManager {
         this.toolExecutor = options.toolExecutor;
         this.shellExecutor = options.shellExecutor;
         this.sharedStoreBackend = options.storeBackend;
+        this.sessionStore = options.sessionStore;
         const cleanupIntervalMs = options.cleanupIntervalMs ?? DEFAULT_CLEANUP_INTERVAL_MS;
         this.cleanupTimer = setInterval(() => void this.cleanup(), cleanupIntervalMs);
         // Don't keep the process alive just for cleanup
@@ -107,7 +115,7 @@ export class SessionManager {
             }));
             sessionParams.basePrompt = this.repo.config.basePrompt;
             sessionParams.agentName = this.repo.config.name;
-            sessionParams.agentContext = this.repo.config.description;
+            sessionParams.agentContext = this.repo.config.userContext ?? this.repo.config.description;
             // Model config from repo
             const mainModel = this.repo.config.models?.main;
             if (mainModel) {
@@ -238,11 +246,6 @@ export class SessionManager {
         const connections = config.getConnections();
         const connKeys = Object.keys(connections).filter((k) => k !== '_secrets');
         process.stderr.write(`[SESSION] connections: ${connKeys.join(', ') || '(none)'}\n`);
-        if (sessionType === 'onboarding' && !connections['platform-api']) {
-            process.stderr.write(`[SESSION] WARNING: onboarding session has no platform-api connection — ` +
-                `the request tool cannot create resources. Check that ADMIN_APP_ID is set ` +
-                `and the seed has run.\n`);
-        }
         // App secrets are available to tools via session-scoped getSessionEnv()
         // (through ToolContext). They are NOT injected into process.env to prevent
         // cross-app secret leakage in multi-session runtimes.
@@ -308,7 +311,36 @@ export class SessionManager {
             name: config.getAgentName() ?? 'Amodal Agent',
             description: config.getAgentDescription(),
             agentContext: config.getAgentContext(),
-            connectionNames: Object.keys(config.getConnections()).filter((k) => k !== '_secrets'),
+            agentOverride: this.repo?.agents?.main,
+            connections: this.repo?.connections ? Array.from(this.repo.connections.values()).map((conn) => ({
+                name: conn.name,
+                endpoints: (conn.surface ?? [])
+                    .filter((ep) => ep.included)
+                    .map((ep) => ({ method: ep.method, path: ep.path, description: ep.description })),
+                entities: conn.entities,
+                rules: conn.rules,
+            })) : undefined,
+            skills: this.repo?.skills?.map((s) => ({
+                name: s.name,
+                description: s.description ?? '',
+                trigger: s.trigger,
+                body: s.body,
+            })),
+            knowledge: this.repo?.knowledge?.map((k) => ({
+                name: k.name,
+                title: k.title,
+                body: k.body,
+            })),
+            ...(this.repo?.connections ? (() => {
+                const { scopeLabels } = resolveScopeLabels(this.repo.connections, []);
+                const fieldGuidance = generateFieldGuidance(this.repo.connections, []);
+                const altLookup = generateAlternativeLookupGuidance(this.repo.connections);
+                return {
+                    fieldGuidance: fieldGuidance || undefined,
+                    scopeLabels: Object.keys(scopeLabels).length > 0 ? scopeLabels : undefined,
+                    alternativeLookupGuidance: altLookup || undefined,
+                };
+            })() : {}),
         });
         try {
             geminiClient.getChat().setSystemInstruction(systemPrompt);
@@ -430,9 +462,73 @@ export class SessionManager {
             shellExecutor: this.shellExecutor,
             appId: auth?.applicationId,
         };
-        // Initialize MCP servers if repo has MCP connections
-        if (this.repo) {
-            await this.initMcp(session, this.repo);
+        // Share MCP connection across sessions — connect once, reuse for all
+        if (this.repo && !this.sharedMcpManager) {
+            await this.initSharedMcp(this.repo);
+        }
+        if (this.sharedMcpManager) {
+            session.mcpManager = this.sharedMcpManager;
+            // Register MCP tools on the upstream tool registry so the Gemini client can see them
+            try {
+                const upstream = config.getUpstreamConfig();
+                const toolRegistry = upstream.getToolRegistry();
+                const mcpTools = session.mcpManager.getDiscoveredTools();
+                for (const mcpTool of mcpTools) {
+                    // Adapter matching upstream DeclarativeTool interface (build/silentBuild/schema/getSchema)
+                    const mcpSession = session;
+                    const adapter = {
+                        name: mcpTool.name,
+                        displayName: mcpTool.name,
+                        description: mcpTool.description,
+                        kind: 'declarative',
+                        parameterSchema: mcpTool.parameters,
+                        get isReadOnly() { return true; },
+                        get toolAnnotations() { return undefined; },
+                        get schema() { return this.getSchema(); },
+                        getSchema() {
+                            return {
+                                name: mcpTool.name,
+                                description: mcpTool.description,
+                                parametersJsonSchema: mcpTool.parameters,
+                            };
+                        },
+                        build(params) {
+                            return {
+                                name: mcpTool.name,
+                                params,
+                                execute: async () => adapter.validateBuildAndExecute(params),
+                            };
+                        },
+                        silentBuild(params) {
+                            return this.build(params);
+                        },
+                        async validateBuildAndExecute(params) {
+                            try {
+                                const result = await mcpSession.mcpManager.callTool(mcpTool.name, params);
+                                const output = result.content
+                                    .map((c) => c.type === 'text' && c.text ? c.text : `[${c.type}]`)
+                                    .join('\n');
+                                return {
+                                    llmContent: result.isError ? `Error: ${output}` : output,
+                                    returnDisplay: output.slice(0, 200),
+                                    ...(result.isError ? { error: { message: output, type: 'EXECUTION_FAILED' } } : {}),
+                                };
+                            }
+                            catch (err) {
+                                const msg = err instanceof Error ? err.message : String(err);
+                                return { llmContent: `Error: ${msg}`, returnDisplay: msg, error: { message: msg, type: 'EXECUTION_FAILED' } };
+                            }
+                        },
+                    };
+                    toolRegistry.registerTool(adapter); // eslint-disable-line @typescript-eslint/no-unsafe-type-assertion
+                }
+                await geminiClient.setTools();
+                process.stderr.write(`[MCP] Registered ${String(mcpTools.length)} MCP tools on tool registry\n`);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`[MCP] Failed to register MCP tools: ${msg}\n`);
+            }
         }
         this.sessions.set(sessionId, session);
         return session;
@@ -479,31 +575,20 @@ export class SessionManager {
         }
     }
     async doHydrate(conversationId, role, auth, sessionType) {
-        // Fetch stored conversation from platform-api
-        const url = `${this.platformApiUrl}/api/applications/${auth.applicationId}/sessions/${conversationId}`;
+        // Fetch stored conversation via pluggable session store
+        if (!this.sessionStore || !auth?.applicationId || !auth.token) {
+            return null;
+        }
         let record;
         try {
-            const controller = new AbortController();
-            const timer = setTimeout(() => controller.abort(), 10_000);
-            const response = await fetch(url, {
-                signal: controller.signal,
-                headers: {
-                    Authorization: `Bearer ${auth.token}`,
-                    Accept: 'application/json',
-                },
-            });
-            clearTimeout(timer);
-            if (!response.ok) {
-                process.stderr.write(`[HYDRATE] Failed to fetch conversation ${conversationId}: HTTP ${response.status}\n`);
-                return null;
-            }
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- API response shape
-            record = (await response.json());
+            record = await this.sessionStore.getSession(auth.applicationId, conversationId, auth.token);
         }
         catch (err) {
             process.stderr.write(`[HYDRATE] Error fetching conversation ${conversationId}: ${err instanceof Error ? err.message : String(err)}\n`);
             return null;
         }
+        if (!record)
+            return null;
         // No messages → nothing to hydrate
         if (!record.messages || record.messages.length === 0)
             return null;
@@ -574,27 +659,68 @@ export class SessionManager {
     }
     /**
      * Create an admin session for the config chat.
-     * Uses admin agent skills/knowledge but the current repo's connections.
+     * Uses admin agent skills/knowledge but the current repo's connections/stores.
+     *
+     * Temporarily swaps repo fields so create() builds the prompt with admin
+     * content, then restores the original repo. This mirrors the old approach
+     * of building an adminRepo overlay.
      */
-    async createAdminSession() {
+    async createAdminSession(getPort) {
         if (!this.repo) {
             throw new Error('Admin sessions require a repo');
         }
+        if (this.repo.source !== 'local') {
+            throw new Error('Admin sessions are only available for local repos');
+        }
         const agentDir = await ensureAdminAgent(this.repo.origin);
         const adminContent = await loadAdminAgent(agentDir);
-        // Create a session with admin context
-        // The admin session uses the same create() flow but with overridden prompts
-        const session = await this.create('admin');
-        // Override system prompt with admin agent prompt
-        if (adminContent.agentPrompt) {
-            try {
-                session.geminiClient.getChat().setSystemInstruction(adminContent.agentPrompt);
-            }
-            catch {
-                // Non-fatal
-            }
+        // Save original repo fields
+        const origSkills = this.repo.skills;
+        const origKnowledge = this.repo.knowledge;
+        const origAgents = this.repo.agents;
+        const origAutomations = this.repo.automations;
+        // Swap in admin content so create() builds the prompt correctly
+        this.repo.skills = adminContent.skills;
+        this.repo.knowledge = adminContent.knowledge;
+        this.repo.agents = {
+            main: adminContent.agentPrompt ?? undefined,
+            simple: undefined,
+            subagents: [],
+        };
+        this.repo.automations = [];
+        let session;
+        try {
+            session = await this.create('admin');
+        }
+        finally {
+            // Restore original repo fields
+            this.repo.skills = origSkills;
+            this.repo.knowledge = origKnowledge;
+            this.repo.agents = origAgents;
+            this.repo.automations = origAutomations;
         }
         session.appId = 'admin';
+        // Register admin file tools (read/write/delete repo files)
+        try {
+            const { createReadRepoFileTool, createWriteRepoFileTool, createDeleteRepoFileTool } = await import('./admin-file-tools.js');
+            const repoRoot = this.repo.origin;
+            const upstream = session.config.getUpstreamConfig();
+            const toolRegistry = upstream.getToolRegistry();
+            toolRegistry.registerTool(createReadRepoFileTool(repoRoot)); // eslint-disable-line @typescript-eslint/no-unsafe-type-assertion
+            toolRegistry.registerTool(createWriteRepoFileTool(repoRoot)); // eslint-disable-line @typescript-eslint/no-unsafe-type-assertion
+            toolRegistry.registerTool(createDeleteRepoFileTool(repoRoot)); // eslint-disable-line @typescript-eslint/no-unsafe-type-assertion
+            // Internal API tool — lets admin query eval results, health, context, etc.
+            if (getPort) {
+                const { createInternalApiTool } = await import('./admin-file-tools.js');
+                toolRegistry.registerTool(createInternalApiTool(getPort)); // eslint-disable-line @typescript-eslint/no-unsafe-type-assertion
+            }
+            await session.geminiClient.setTools();
+            process.stderr.write('[ADMIN] Registered admin tools (file tools + internal_api)\n');
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[ADMIN] Failed to register file tools: ${msg}\n`);
+        }
         return session;
     }
     /**
@@ -627,7 +753,11 @@ export class SessionManager {
     /**
      * Initialize MCP servers for a session from repo connections.
      */
-    async initMcp(session, repo) {
+    /**
+     * Initialize the shared MCP manager (once, reused across sessions).
+     * Avoids reconnecting MCP servers for every eval/judge/admin session.
+     */
+    async initSharedMcp(repo) {
         const mcpServers = this.buildMcpConfigs(repo);
         if (Object.keys(mcpServers).length === 0)
             return;
@@ -635,7 +765,7 @@ export class SessionManager {
         try {
             await manager.startServers(mcpServers);
             if (manager.connectedCount > 0) {
-                session.mcpManager = manager;
+                this.sharedMcpManager = manager;
             }
         }
         catch (err) {