@amodalai/runtime 0.1.15 → 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/custom-tool-adapter.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { LoadedTool, CustomToolExecutor } from '@amodalai/core';
+import type { ManagedSession } from './session-manager.js';
+/**
+ * Adapts a repo LoadedTool to the upstream tool registry interface.
+ * Wraps the tool definition and delegates execution to the CustomToolExecutor.
+ */
+export declare class CustomToolAdapter {
+    readonly name: string;
+    readonly displayName: string;
+    private readonly tool;
+    private readonly session;
+    private readonly executor;
+    readonly kind: "declarative";
+    readonly description: string;
+    readonly parameterSchema: Record<string, unknown>;
+    constructor(tool: LoadedTool, session: ManagedSession, executor: CustomToolExecutor);
+    get isReadOnly(): boolean;
+    get toolAnnotations(): undefined;
+    getSchema(_modelId?: string): {
+        name: string;
+        description: string;
+        parametersJsonSchema: Record<string, unknown>;
+    };
+    get schema(): {
+        name: string;
+        description: string;
+        parametersJsonSchema: Record<string, unknown>;
+    };
+    /**
+     * Silently build an invocation (used by upstream tool execution flow).
+     */
+    /**
+     * Build an invocation object from params — used by Scheduler.
+     */
+    build(params: Record<string, unknown>): {
+        name: string;
+        execute: (abortSignal: AbortSignal) => Promise<{
+            llmContent: string;
+            returnDisplay?: string;
+            error?: {
+                message: string;
+                type: string;
+            };
+        }>;
+    };
+    silentBuild(params: Record<string, unknown>): {
+        name: string;
+        execute: (abortSignal: AbortSignal) => Promise<{
+            llmContent: string;
+            returnDisplay?: string;
+            error?: {
+                message: string;
+                type: string;
+            };
+        }>;
+    };
+    /**
+     * Build and execute in one step — matches the upstream DeclarativeTool interface.
+     */
+    validateBuildAndExecute(params: Record<string, unknown>, abortSignal: AbortSignal): Promise<{
+        llmContent: string;
+        returnDisplay?: string;
+        error?: {
+            message: string;
+            type: string;
+        };
+    }>;
+    private buildContext;
+}

package/dist/src/session/custom-tool-adapter.js

@@ -0,0 +1,149 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Adapts a repo LoadedTool to the upstream tool registry interface.
+ * Wraps the tool definition and delegates execution to the CustomToolExecutor.
+ */
+export class CustomToolAdapter {
+    name;
+    displayName;
+    tool;
+    session;
+    executor;
+    kind = 'declarative';
+    description;
+    parameterSchema;
+    constructor(tool, session, executor) {
+        this.name = tool.name;
+        this.displayName = tool.name;
+        this.description = tool.description;
+        this.parameterSchema = tool.parameters;
+        this.tool = tool;
+        this.session = session;
+        this.executor = executor;
+    }
+    get isReadOnly() {
+        return this.tool.confirm === false;
+    }
+    get toolAnnotations() {
+        return undefined;
+    }
+    getSchema(_modelId) {
+        return {
+            name: this.name,
+            description: this.description,
+            parametersJsonSchema: this.parameterSchema,
+        };
+    }
+    get schema() {
+        return this.getSchema();
+    }
+    /**
+     * Silently build an invocation (used by upstream tool execution flow).
+     */
+    /**
+     * Build an invocation object from params — used by Scheduler.
+     */
+    build(params) {
+        return {
+            name: this.name,
+            execute: async (abortSignal) => this.validateBuildAndExecute(params, abortSignal),
+        };
+    }
+    silentBuild(params) {
+        return this.build(params);
+    }
+    /**
+     * Build and execute in one step — matches the upstream DeclarativeTool interface.
+     */
+    async validateBuildAndExecute(params, abortSignal) {
+        try {
+            const ctx = this.buildContext(abortSignal);
+            const result = await this.executor.execute(this.tool, params, ctx);
+            const content = typeof result === 'string' ? result : JSON.stringify(result);
+            return { llmContent: content, returnDisplay: content };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                llmContent: `Error: ${message}`,
+                returnDisplay: message,
+                error: { message, type: 'EXECUTION_FAILED' },
+            };
+        }
+    }
+    buildContext(signal) {
+        const tool = this.tool;
+        const session = this.session;
+        const timeoutSignal = AbortSignal.timeout(tool.timeout);
+        const combinedSignal = AbortSignal.any([signal, timeoutSignal]);
+        return {
+            async request(connection, endpoint, params) {
+                const connections = session.config.getConnections();
+                const connConfig = connections[connection];
+                if (!connConfig) {
+                    throw new Error(`Connection "${connection}" not found`);
+                }
+                const method = params?.method ?? 'GET';
+                if (tool.confirm === false && method !== 'GET') {
+                    throw new Error(`Tool "${tool.name}" has confirm: false — only GET requests are allowed.`);
+                }
+                const baseUrl = typeof connConfig === 'object' && connConfig !== null && 'baseUrl' in connConfig
+                    ? String(connConfig['baseUrl'] ?? '')
+                    : '';
+                if (!baseUrl) {
+                    throw new Error(`Connection "${connection}" has no baseUrl`);
+                }
+                const url = `${baseUrl}${endpoint}`;
+                const fetchOpts = {
+                    method,
+                    signal: combinedSignal,
+                    headers: { 'Content-Type': 'application/json' },
+                };
+                if (params?.data) {
+                    fetchOpts.body = JSON.stringify(params.data);
+                }
+                const res = await fetch(url, fetchOpts);
+                const body = await res.text();
+                try {
+                    return JSON.parse(body);
+                }
+                catch {
+                    return { text: body, status: res.status };
+                }
+            },
+            async exec(command, options) {
+                const { exec: execCb } = await import('node:child_process');
+                const { promisify } = await import('node:util');
+                const execAsync = promisify(execCb);
+                try {
+                    const { stdout, stderr } = await execAsync(command, {
+                        signal: combinedSignal,
+                        timeout: options?.timeout ?? tool.timeout,
+                        cwd: options?.cwd,
+                    });
+                    return { stdout: stdout ?? '', stderr: stderr ?? '', exitCode: 0 };
+                }
+                catch (err) {
+                    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- exec error shape
+                    const e = err;
+                    return { stdout: e.stdout ?? '', stderr: e.stderr ?? '', exitCode: e.code ?? 1 };
+                }
+            },
+            env(name) {
+                if (!tool.env.includes(name))
+                    return undefined;
+                return process.env[name];
+            },
+            log(message) {
+                process.stderr.write(`[TOOL:${tool.name}] ${message}\n`);
+            },
+            user: { roles: [] },
+            signal: combinedSignal,
+        };
+    }
+}
+//# sourceMappingURL=custom-tool-adapter.js.map

package/dist/src/session/custom-tool-adapter.js.map

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

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

@@ -3,7 +3,8 @@
  * Copyright 2025 Amodal Labs, Inc.
  * SPDX-License-Identifier: MIT
  */
-import { AmodalConfig, type AmodalConfigParameters, Scheduler, type GeminiClient } from '@amodalai/core';
+import { AmodalConfig, type AmodalConfigParameters, Scheduler, type GeminiClient, PlanModeManager, McpManager } from '@amodalai/core';
+import type { AmodalRepo, CustomToolExecutor, CustomShellExecutor, StoreBackend } from '@amodalai/core';
 import type { AuthContext } from '../middleware/auth.js';
 export interface PendingAskUser {
     resolve: (answers: Record<string, string>) => void;
@@ -39,7 +40,36 @@ export interface ManagedSession {
     /** Provider used for this session (pinned at creation, survives hydration) */
     provider?: string;
     /** Store backend for cleanup on session destroy */
-    storeBackend?: import('@amodalai/core').StoreBackend;
+    storeBackend?: StoreBackend;
+    /** Plan mode manager (local dev) */
+    planModeManager?: PlanModeManager;
+    /** MCP server manager (local dev) */
+    mcpManager?: McpManager;
+    /** Session title */
+    title?: string;
+    /** Custom tool executor (local dev) */
+    toolExecutor?: CustomToolExecutor;
+    /** Custom shell executor (local dev) */
+    shellExecutor?: CustomShellExecutor;
+    /** 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 */
@@ -50,15 +80,39 @@ export interface SessionManagerOptions {
     cleanupIntervalMs?: number;
     /** Platform API URL (for loading org-specific config per session) */
     platformApiUrl?: string;
+    /** Repo for local dev mode — sessions initialized from repo config instead of platform API */
+    repo?: AmodalRepo;
+    /** Custom tool executor (local dev) */
+    toolExecutor?: CustomToolExecutor;
+    /** Custom shell executor (local dev) */
+    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 readonly baseParams;
+    private baseParams;
     private readonly ttlMs;
     private readonly platformApiUrl?;
+    private repo?;
+    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;
     constructor(options: SessionManagerOptions);
     /**
      * Create a new session with optional role override and auth context.
@@ -91,6 +145,50 @@ export declare class SessionManager {
      * Destroy a session, flushing its audit log.
      */
     destroy(id: string): Promise<void>;
+    /**
+     * Get the repo (local dev mode).
+     */
+    getRepo(): AmodalRepo | undefined;
+    /**
+     * Update the repo for new sessions (hot reload).
+     * Existing sessions keep their old config.
+     */
+    updateRepo(repo: AmodalRepo): void;
+    /**
+     * Re-register a session under a different ID (e.g., restoring original ID on session restore).
+     */
+    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/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(getPort?: () => number | null): Promise<ManagedSession>;
+    /**
+     * Get a persistent MCP manager for inspect/health operations.
+     * Lazy-initialized on first call, reused across requests.
+     */
+    getInspectMcpManager(): Promise<McpManager | undefined>;
+    /**
+     * Initialize MCP servers for a session from repo connections.
+     */
+    /**
+     * 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.
+     */
+    private buildCoreToolsList;
+    /**
+     * Build MCP server configs from repo connections.
+     */
+    private buildMcpConfigs;
     /**
      * Remove sessions that have been idle longer than the TTL.
      */