@entrinsik/vite-plugin-informer 2.2.0 → 2.4.0

package/bin/deploy.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 
-import dotenv from 'dotenv';
 import { readFile, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { deploy } from '../src/deploy.js';
+import { loadEnv, parseModeArg } from '../src/env.js';
 
-dotenv.config();
+const mode = parseModeArg(process.argv);
+loadEnv({ mode });
 
 const baseUrl = process.env.INFORMER_URL;
 const apiKey = process.env.INFORMER_API_KEY;

package/bin/init.js

@@ -8,141 +8,59 @@ import { randomUUID } from 'node:crypto';
 const cwd = process.cwd();
 
 /**
- * Generate the default data-access.yaml content with helpful comments
+ * Generate the default informer.yaml content with helpful comments
  */
-function generateDataAccessYaml() {
-    return `# Data Access Configuration
-# ========================
-# This file controls which Informer APIs your report can access.
-# Without this file, all API access is blocked (secure by default).
+function generateInformerYaml() {
+    return `# Informer App Configuration
+# =========================
+# This file controls which Informer APIs your app can access and defines
+# custom roles for role-based UIs.
 #
-# Documentation: https://docs.entrinsik.com/informer/magic-reports/data-access
+# Without an access section, all API access is blocked (secure by default).
 
 # ============================================================================
-# DATASETS
+# DATA ACCESS
 # ============================================================================
-# Grant access to dataset search and field metadata.
-# Each entry generates:
-#   - POST /api/datasets/{id}/_search
-#   - GET /api/datasets/{id}/fields
+# The access section controls which APIs the app can call when shared.
 #
-# Simple access (full dataset):
+# access:
 #   datasets:
-#     - admin:sales-data
-#     - admin:customers
-#
-# With row-level security (filter injected server-side):
-#   datasets:
-#     - id: admin:orders
+#     - admin:sales-data             # Full dataset access
+#     - id: admin:orders             # With row-level security
 #       filter:
-#         region: $user.custom.region      # User only sees their region
-#         sales_rep: $user.username        # User only sees their own records
-#
-datasets: []
-
-# ============================================================================
-# QUERIES
-# ============================================================================
-# Grant access to execute saved queries.
-# Each entry generates:
-#   - POST /api/queries/{id}/_execute
+#         region: $user.custom.region
 #
-# Example:
 #   queries:
-#     - admin:daily-summary
-#     - admin:monthly-report
-#
-queries: []
-
-# ============================================================================
-# INTEGRATIONS
-# ============================================================================
-# Grant access to make requests through integrations (Salesforce, REST APIs, etc.)
-# Each entry generates:
-#   - POST /api/integrations/{id}/request
+#     - admin:monthly-summary
 #
-# Simple access:
 #   integrations:
 #     - salesforce
-#     - quickbooks
-#
-# With credential injection (headers/params expanded server-side, never exposed to JS):
-#   integrations:
-#     - id: partner-api
-#       headers:
-#         Authorization: Bearer $user.custom.partnerToken
-#         X-Client-ID: $tenant.id
-#       params:
-#         user_id: $user.custom.externalId
-#
-# With path restrictions (only allow specific endpoints):
-#   integrations:
-#     - id: salesforce
-#       paths:
-#         - /data/*/query
-#         - /data/*/sobjects/*
-#
-integrations: []
-
-# ============================================================================
-# DATASOURCES
-# ============================================================================
-# Grant access to run SQL queries against datasources.
-# Each entry generates:
-#   - POST /api/datasources/{id}/_query
 #
-# Example:
 #   datasources:
 #     - postgres-main
-#     - mysql-analytics
-#
-datasources: []
-
-# ============================================================================
-# LIBRARIES
-# ============================================================================
-# Grant access to read files from other libraries.
-# Each entry generates:
-#   - GET /api/libraries/{id}/contents/*
-#
-# Example:
-#   libraries:
-#     - admin:shared-assets
-#     - admin:common-templates
-#
-libraries: []
-
-# ============================================================================
-# RAW API ACCESS (Advanced)
-# ============================================================================
-# For edge cases not covered by resource types above.
-# Specify exact method and path.
 #
-# Example:
-#   apis:
+#   apis:                            # Raw API paths (advanced)
 #     - POST /api/custom/endpoint
-#     - GET /api/special/resource
-#
-apis: []
+
+access:
+  datasets: []
+  queries: []
+  integrations: []
 
 # ============================================================================
-# VARIABLE REFERENCE
+# ROLES (optional)
 # ============================================================================
-# Variables are expanded server-side, keeping sensitive values secure.
-#
-# User variables:
-#   $user.username      - Login name
-#   $user.email         - Email address
-#   $user.displayName   - Full name (e.g., "John Smith")
-#   $user.custom.xxx    - Custom user field value
-#
-# Tenant variables:
-#   $tenant.id          - Tenant identifier
-#
-# Report variables:
-#   $report.id          - Report UUID
-#   $report.name        - Report display name
+# Define custom roles that publishers assign when sharing the app.
+# Roles are available in client code via window.__INFORMER__.roles
+# and in server handlers via request.roles.
 #
+# roles:
+#   - id: viewer
+#     name: Viewer
+#     description: Can view reports but not take actions
+#   - id: approver
+#     name: Approver
+#     description: Can approve or reject requests
 `;
 }
 
@@ -187,7 +105,7 @@ function packageNameToDisplayName(name) {
 }
 
 async function init() {
-    console.log('Initializing Informer Magic Report project...\n');
+    console.log('Initializing Informer App project...\n');
 
     // 1. Check for package.json
     const pkgPath = resolve(cwd, 'package.json');
@@ -210,9 +128,9 @@ async function init() {
     // 3. Get report info from user
     const defaultName = pkg.informer?.name || packageNameToDisplayName(pkg.name || basename(cwd));
 
-    console.log('Configure your Magic Report:\n');
+    console.log('Configure your app:\n');
 
-    const reportName = await prompt('Report name', defaultName);
+    const reportName = await prompt('App name', defaultName);
 
     console.log('');
 
@@ -276,11 +194,11 @@ INFORMER_API_KEY=your-api-key
         console.log('Created .env (update with your credentials)');
     }
 
-    // 9. Create data-access.yaml if it doesn't exist
-    const dataAccessPath = resolve(cwd, 'data-access.yaml');
-    if (!await exists(dataAccessPath)) {
-        await writeFile(dataAccessPath, generateDataAccessYaml());
-        console.log('Created data-access.yaml (configure API access for your report)');
+    // 9. Create informer.yaml if it doesn't exist
+    const informerYamlPath = resolve(cwd, 'informer.yaml');
+    if (!await exists(informerYamlPath)) {
+        await writeFile(informerYamlPath, generateInformerYaml());
+        console.log('Created informer.yaml (configure API access and roles)');
     }
 
     // 10. Add .env to .gitignore if not present
@@ -289,11 +207,9 @@ INFORMER_API_KEY=your-api-key
     console.log('\nSetup complete!\n');
     console.log('Next steps:');
     console.log('  1. Update .env with your Informer credentials');
-    console.log('  2. Update data-access.yaml with the datasets/APIs your report needs');
+    console.log('  2. Update informer.yaml with the datasets/APIs your app needs');
     console.log('  3. Run: npm install');
     console.log('  4. Run: npm run dev');
-    console.log('  5. Install the Claude skill: /plugin marketplace add entrinsik-org/claude-plugins');
-    console.log('  6. Then: /plugin install magic-reports@entrinsik-plugins');
     console.log('');
 }
 

package/bin/workspace.js

@@ -1,22 +1,28 @@
 #!/usr/bin/env node
 
-import dotenv from 'dotenv';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { createClient } from '../src/client.js';
+import { loadEnv, envWritePath, parseModeArg } from '../src/env.js';
 import { init, migrate, reset } from '../src/workspace.js';
 
-dotenv.config();
+const mode = parseModeArg(process.argv);
+loadEnv({ mode });
 
-const command = process.argv[2];
+// Strip --mode <value> from argv before parsing the command
+const args = process.argv.slice(2).filter((arg, i, arr) => arg !== '--mode' && arr[i - 1] !== '--mode');
+const command = args[0];
 
 if (!command || !['init', 'migrate', 'reset'].includes(command)) {
-    console.error('Usage: informer-workspace <init|migrate|reset>');
+    console.error('Usage: informer-workspace <init|migrate|reset> [--mode <name>]');
     console.error('');
     console.error('Commands:');
     console.error('  init      Create a dev workspace datasource and run migrations');
     console.error('  migrate   Run pending migrations against the dev workspace');
     console.error('  reset     Drop all tables and re-run all migrations');
+    console.error('');
+    console.error('Options:');
+    console.error('  --mode <name>  Load .env.<name> (e.g. --mode test, --mode production)');
     process.exit(1);
 }
 
@@ -33,7 +39,7 @@ if (!baseUrl || (!apiKey && (!user || !pass))) {
 
 const api = createClient({ baseUrl, apiKey, user, pass });
 const migrationsDir = resolve('migrations');
-const envPath = resolve('.env');
+const envPath = envWritePath({ mode });
 
 try {
     if (command === 'init') {

package/package.json

@@ -1,46 +1,47 @@
 {
-  "name": "@entrinsik/vite-plugin-informer",
-  "version": "2.2.0",
-  "description": "Vite plugin and publish tool for local Magic Report development",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/entrinsik-org/i5.git",
-    "directory": "packages/vite-plugin-informer"
-  },
-  "publishConfig": {
-    "registry": "https://docker.entrinsik.com/repository/entNPM/"
-  },
-  "author": "Entrinsik Inc.",
-  "license": "UNLICENSED",
-  "type": "module",
-  "types": "index.d.ts",
-  "main": "./src/index.js",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "exports": {
-    ".": {
-      "types": "./index.d.ts",
-      "default": "./src/index.js"
+    "name": "@entrinsik/vite-plugin-informer",
+    "version": "2.4.0",
+    "description": "Vite plugin and deploy tool for Informer App development",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/entrinsik-org/i5.git",
+        "directory": "packages/vite-plugin-informer"
     },
-    "./deploy": "./src/deploy.js",
-    "./workspace": "./src/workspace.js"
-  },
-  "bin": {
-    "informer-deploy": "./bin/deploy.js",
-    "informer-init": "./bin/init.js",
-    "informer-workspace": "./bin/workspace.js",
-    "create-magic-report": "./bin/init.js"
-  },
-  "files": [
-    "src",
-    "bin",
-    "index.d.ts"
-  ],
-  "peerDependencies": {
-    "vite": ">=5.0.0"
-  },
-  "dependencies": {
-    "dotenv": "16.6.1"
-  }
+    "publishConfig": {
+        "registry": "https://docker.entrinsik.com/repository/entNPM/"
+    },
+    "author": "Entrinsik Inc.",
+    "license": "UNLICENSED",
+    "type": "module",
+    "types": "index.d.ts",
+    "main": "./src/index.js",
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "exports": {
+        ".": {
+            "types": "./index.d.ts",
+            "default": "./src/index.js"
+        },
+        "./deploy": "./src/deploy.js",
+        "./workspace": "./src/workspace.js"
+    },
+    "bin": {
+        "informer-deploy": "./bin/deploy.js",
+        "informer-init": "./bin/init.js",
+        "informer-workspace": "./bin/workspace.js",
+        "create-magic-report": "./bin/init.js"
+    },
+    "files": [
+        "src",
+        "bin",
+        "index.d.ts"
+    ],
+    "peerDependencies": {
+        "vite": ">=5.0.0"
+    },
+    "dependencies": {
+        "dotenv": "16.6.1",
+        "yaml": "^2.7.0"
+    }
 }

package/src/agent-dev.js

@@ -0,0 +1,450 @@
+import { createHmac } from 'node:crypto';
+import { readFile, readdir, stat, access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse as parseUrl } from 'node:url';
+import yaml from 'yaml';
+const parseYaml = yaml.parse;
+
+const MAX_STEPS = 20;
+
+/**
+ * Read and parse informer.yaml from the project root.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<Object|null>} Parsed YAML or null
+ */
+async function loadInformerYaml(projectRoot) {
+    const yamlPath = join(projectRoot, 'informer.yaml');
+    try {
+        await access(yamlPath);
+        const content = await readFile(yamlPath, 'utf8');
+        return parseYaml(content);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Scan the tools/ directory for .js files that export a handler.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<Array<{ name: string, filePath: string }>>}
+ */
+async function scanLocalTools(projectRoot) {
+    const toolsDir = join(projectRoot, 'tools');
+    try {
+        await access(toolsDir);
+    } catch {
+        return [];
+    }
+
+    const tools = [];
+    await walkToolFiles(toolsDir, 'tools', tools);
+    return tools;
+}
+
+async function walkToolFiles(dir, basePath, results) {
+    let items;
+    try {
+        items = await readdir(dir);
+    } catch {
+        return;
+    }
+
+    for (const item of items) {
+        const full = join(dir, item);
+        const childPath = `${basePath}/${item}`;
+        const s = await stat(full);
+
+        if (s.isDirectory()) {
+            await walkToolFiles(full, childPath, results);
+        } else if (item.endsWith('.js')) {
+            const name = childPath
+                .replace(/^tools\//, '')
+                .replace(/\.js$/, '')
+                .replace(/\//g, '_');
+            results.push({ name, filePath: full });
+        }
+    }
+}
+
+/**
+ * Read an SSE stream from a fetch response, collecting text and tool calls.
+ *
+ * @param {Response} response - Fetch response with SSE body
+ * @returns {Promise<{ text: string, toolCalls: Array<{ id: string, name: string, input: Object }>, usage: Object }>}
+ */
+async function readSSE(response) {
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let text = '';
+    const toolCalls = [];
+    const pendingInputs = new Map(); // toolCallId -> partial JSON string
+    let usage = {};
+
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop();
+
+        for (const line of lines) {
+            if (!line.startsWith('data: ')) continue;
+            const payload = line.slice(6);
+            if (payload === '[DONE]') break;
+
+            try {
+                const event = JSON.parse(payload);
+                switch (event.type) {
+                    case 'text-delta':
+                        text += event.delta;
+                        break;
+                    case 'tool-input-start':
+                        pendingInputs.set(event.toolCallId, '');
+                        break;
+                    case 'tool-input-delta':
+                        if (pendingInputs.has(event.toolCallId)) {
+                            pendingInputs.set(
+                                event.toolCallId,
+                                pendingInputs.get(event.toolCallId) + event.inputTextDelta
+                            );
+                        }
+                        break;
+                    case 'tool-input-available':
+                        toolCalls.push({
+                            id: event.toolCallId,
+                            name: event.toolName,
+                            input: event.input || {}
+                        });
+                        pendingInputs.delete(event.toolCallId);
+                        break;
+                    case 'finish-step':
+                        if (event.usage) usage = event.usage;
+                        break;
+                }
+            } catch {
+                // Skip malformed SSE events
+            }
+        }
+    }
+
+    return { text, toolCalls, usage };
+}
+
+/**
+ * Create Connect middleware for local agent development.
+ *
+ * Provides:
+ *   GET  /api/_agent          → list agents from informer.yaml
+ *   POST /api/_agent/:name/_trigger → run agent locally with tool dispatch
+ *
+ * @param {Object} viteServer - Vite dev server instance
+ * @param {Object} opts - Configuration
+ * @returns {Function} Connect middleware
+ */
+export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot }) {
+
+    // query() — proxies to the workspace _sql endpoint (same as server-routes.js)
+    async function query(sql, params) {
+        if (!devWorkspaceId) {
+            throw new Error('query() requires INFORMER_DEV_WORKSPACE. Run: npx informer-workspace init');
+        }
+
+        const resp = await globalThis.fetch(`${serverOrigin}/api/datasources/${devWorkspaceId}/_sql`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Authorization: authHeader },
+            body: JSON.stringify({ sql, params: params || [] })
+        });
+
+        if (!resp.ok) {
+            const err = await resp.json().catch(() => ({}));
+            throw new Error(`query() failed: ${resp.status} ${err.message || resp.statusText}`);
+        }
+
+        const data = await resp.json();
+        return data.rows;
+    }
+
+    // fetch() — proxies API calls to the Informer server (same as server-routes.js)
+    async function apiFetch(path, opts = {}) {
+        const method = (opts.method || 'GET').toUpperCase();
+        const url = `${serverOrigin}/api/${path.replace(/^\/?(?:api\/)?/, '')}`;
+        const fetchOpts = {
+            method,
+            headers: { Authorization: authHeader, 'Content-Type': 'application/json' }
+        };
+
+        if (opts.body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+            fetchOpts.body = JSON.stringify(opts.body);
+        }
+
+        const resp = await globalThis.fetch(url, fetchOpts);
+        let body;
+        try { body = await resp.json(); } catch { body = await resp.text(); }
+        return { status: resp.status, body };
+    }
+
+    // emit() — no-op in dev mode (logs to console)
+    function emit(event, payload) {
+        console.log(`[agent-dev] emit("${event}",`, JSON.stringify(payload), ')');
+        return { ok: true };
+    }
+
+    // crypto helper — mirrors the sandbox's crypto.hmac()
+    const cryptoHelper = {
+        hmac(algorithm, key, data, encoding) {
+            return createHmac(algorithm, key).update(data).digest(encoding || 'hex');
+        }
+    };
+
+    // log helper — mirrors sandbox log(message, data) + log.info/warn/error/debug
+    const logCall = (level, message, data) => {
+        const msg = typeof message === 'string' ? message : JSON.stringify(message);
+        const args = [`[app-log] [${level}] ${msg}`];
+        if (data) args.push(data);
+        console.log(...args);
+    };
+    const log = Object.assign(
+        (message, data) => logCall('info', message, data),
+        {
+            debug: (message, data) => logCall('debug', message, data),
+            info: (message, data) => logCall('info', message, data),
+            warn: (message, data) => logCall('warn', message, data),
+            error: (message, data) => logCall('error', message, data)
+        }
+    );
+
+    // markdown helper — passthrough in dev (production uses `marked`)
+    const markdown = (text) => text;
+
+    return async function agentDevMiddleware(req, res, next) {
+        try {
+            const parsed = parseUrl(req.url, true);
+            const routePath = parsed.pathname || '/';
+
+            // GET / → list agents
+            if (req.method === 'GET' && (routePath === '/' || routePath === '')) {
+                const yaml = await loadInformerYaml(projectRoot);
+                const agents = yaml && yaml.agents ? Object.entries(yaml.agents).map(([name, def]) => ({
+                    name,
+                    description: def.description || null,
+                    model: def.model || 'go_everyday',
+                    tools: def.tools || [],
+                    on: def.on || []
+                })) : [];
+
+                res.statusCode = 200;
+                res.setHeader('Content-Type', 'application/json');
+                res.end(JSON.stringify(agents));
+                return;
+            }
+
+            // POST /:name/_trigger → run agent
+            const triggerMatch = routePath.match(/^\/([^/]+)\/_trigger$/);
+            if (req.method === 'POST' && triggerMatch) {
+                const agentName = decodeURIComponent(triggerMatch[1]);
+
+                // Read request body
+                const chunks = [];
+                for await (const chunk of req) {
+                    chunks.push(chunk);
+                }
+                const rawBody = Buffer.concat(chunks).toString('utf8');
+                let body = {};
+                if (rawBody) {
+                    try { body = JSON.parse(rawBody); } catch { body = {}; }
+                }
+
+                const triggerEvent = {
+                    event: body.event || '_manual',
+                    payload: body.payload || {}
+                };
+
+                // Load agent definition
+                const yaml = await loadInformerYaml(projectRoot);
+                if (!yaml || !yaml.agents || !yaml.agents[agentName]) {
+                    res.statusCode = 404;
+                    res.setHeader('Content-Type', 'application/json');
+                    res.end(JSON.stringify({ error: `Agent "${agentName}" not found in informer.yaml` }));
+                    return;
+                }
+
+                const agentDef = yaml.agents[agentName];
+                const model = agentDef.model || 'go_everyday';
+                const instructions = agentDef.instructions || '';
+                const agentToolNames = agentDef.tools || [];
+
+                // Load tool handlers via ssrLoadModule
+                const localTools = await scanLocalTools(projectRoot);
+                const toolMap = new Map(localTools.map(t => [t.name, t]));
+
+                const loadedTools = {};
+                for (const toolName of agentToolNames) {
+                    const tool = toolMap.get(toolName);
+                    if (!tool) {
+                        console.warn(`[agent-dev] Tool "${toolName}" not found in tools/`);
+                        continue;
+                    }
+
+                    const mod = await viteServer.ssrLoadModule(tool.filePath);
+                    if (typeof mod.handler !== 'function') {
+                        console.warn(`[agent-dev] Tool "${toolName}" has no handler export`);
+                        continue;
+                    }
+
+                    loadedTools[toolName] = {
+                        handler: mod.handler,
+                        description: mod.description || `Tool: ${toolName}`,
+                        schema: mod.schema || { type: 'object', properties: {} }
+                    };
+                }
+
+                // Build AI SDK tool definitions for _chat
+                const chatTools = {};
+                for (const [name, tool] of Object.entries(loadedTools)) {
+                    // Ensure schema always has type: 'object' at top level (Anthropic API requires it)
+                    const schema = tool.schema || {};
+                    chatTools[name] = {
+                        description: tool.description,
+                        inputSchema: {
+                            type: 'object',
+                            ...schema
+                        }
+                    };
+                }
+
+                // Run the AI loop
+                console.log(`[agent-dev] Triggering "${agentName}" (model: ${model}, tools: ${Object.keys(loadedTools).join(', ')})`);
+                for (const [name, def] of Object.entries(chatTools)) {
+                    console.log(`[agent-dev] Tool "${name}" schema:`, JSON.stringify(def.inputSchema));
+                }
+
+                const messages = [
+                    {
+                        role: 'user',
+                        parts: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                event: triggerEvent.event,
+                                payload: triggerEvent.payload,
+                                timestamp: new Date().toISOString()
+                            })
+                        }]
+                    }
+                ];
+
+                const steps = [];
+                let totalTokens = 0;
+
+                for (let step = 0; step < MAX_STEPS; step++) {
+                    // Call the AI model
+                    const chatResp = await globalThis.fetch(`${serverOrigin}/api/models/${model}/_chat`, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json', Authorization: authHeader },
+                        body: JSON.stringify({
+                            messages,
+                            system: instructions,
+                            tools: Object.keys(chatTools).length > 0 ? chatTools : undefined,
+                            webSearch: !!agentDef.webSearch,
+                            maxSteps: 1
+                        })
+                    });
+
+                    if (!chatResp.ok) {
+                        const err = await chatResp.json().catch(() => ({}));
+                        throw new Error(`Model call failed: ${chatResp.status} ${err.message || chatResp.statusText}`);
+                    }
+
+                    const { text, toolCalls, usage } = await readSSE(chatResp);
+                    totalTokens += (usage.promptTokens || 0) + (usage.completionTokens || 0);
+
+                    // No tool calls — model is done
+                    if (toolCalls.length === 0) {
+                        if (text) {
+                            steps.push({ type: 'text', text });
+                            console.log(`[agent-dev] Step ${step}: text response (${text.length} chars)`);
+                        }
+                        break;
+                    }
+
+                    // Execute tool calls locally
+                    const assistantParts = [];
+                    if (text) {
+                        assistantParts.push({ type: 'text', text });
+                    }
+
+                    const toolResultParts = [];
+
+                    for (const tc of toolCalls) {
+                        console.log(`[agent-dev] Step ${step}: calling tool "${tc.name}"`, JSON.stringify(tc.input));
+
+                        assistantParts.push({
+                            type: 'tool-invocation',
+                            toolCallId: tc.id,
+                            toolName: tc.name,
+                            args: tc.input,
+                            state: 'result'
+                        });
+
+                        const tool = loadedTools[tc.name];
+                        let result;
+
+                        if (tool) {
+                            try {
+                                result = await tool.handler(tc.input, { query, fetch: apiFetch, emit, crypto: cryptoHelper, markdown, log, context: triggerEvent });
+                            } catch (err) {
+                                console.error(`[agent-dev] Tool "${tc.name}" failed:`, err.message);
+                                result = { error: err.message };
+                            }
+                        } else {
+                            result = { error: `Unknown tool: ${tc.name}` };
+                        }
+
+                        console.log(`[agent-dev]   → result:`, JSON.stringify(result).slice(0, 200));
+
+                        toolResultParts.push({
+                            type: 'tool-result',
+                            toolCallId: tc.id,
+                            toolName: tc.name,
+                            result: JSON.stringify(result)
+                        });
+
+                        steps.push({
+                            type: 'tool_call',
+                            toolCalls: [{ name: tc.name, args: tc.input, result }]
+                        });
+                    }
+
+                    // Append assistant message with tool invocations + tool results
+                    messages.push({ role: 'assistant', parts: assistantParts });
+                    messages.push({ role: 'tool', parts: toolResultParts });
+                }
+
+                const runResult = {
+                    agent: agentName,
+                    trigger: triggerEvent.event,
+                    status: 'completed',
+                    tokens: totalTokens,
+                    steps
+                };
+
+                console.log(`[agent-dev] Agent "${agentName}" completed: ${steps.length} steps, ${totalTokens} tokens`);
+
+                res.statusCode = 200;
+                res.setHeader('Content-Type', 'application/json');
+                res.end(JSON.stringify(runResult));
+                return;
+            }
+
+            next();
+        } catch (err) {
+            console.error('[agent-dev]', err);
+            res.statusCode = 500;
+            res.setHeader('Content-Type', 'application/json');
+            res.end(JSON.stringify({ error: err.message }));
+        }
+    };
+}

package/src/deploy.js

@@ -14,7 +14,7 @@ const CHUNK_THRESHOLD = 512 * 1024; // 512KB
 const ROOT_CONFIG_FILES = ['informer.yaml', 'data-access.yaml'];
 
 /**
- * Deploy a built Vite project to Informer as an App (or legacy Magic Report).
+ * Deploy a built Vite project to Informer as an App.
  *
  * Tries the new /api/apps endpoint first. If the server doesn't support it,
  * falls back to the legacy /api/reports endpoint transparently.
@@ -149,7 +149,7 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
         }
     }
 
-    // 7. Upload config files from project root (e.g., data-access.yaml)
+    // 7. Upload config files from project root (informer.yaml, data-access.yaml)
     const projectRoot = dirname(distDir);
     let configCount = 0;
     for (const configFile of ROOT_CONFIG_FILES) {
@@ -188,7 +188,30 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
         // No migrations directory, skip
     }
 
-    // 9. Upload server/ directory from project root (if it exists)
+    // 9. Upload tools/ directory from project root (if it exists)
+    const toolsDir = join(projectRoot, 'tools');
+    let toolsCount = 0;
+    try {
+        await access(toolsDir);
+        const toolFiles = await walkDir(toolsDir);
+        for (const filePath of toolFiles) {
+            const relPath = posix.normalize(relative(projectRoot, filePath).split('\\').join('/'));
+            const content = await readFile(filePath);
+            const ext = '.' + relPath.split('.').pop();
+            const isText = TEXT_EXTENSIONS.has(ext.toLowerCase());
+            const payload = isText
+                ? { content: content.toString('utf8'), encoding: 'utf8' }
+                : { content: content.toString('base64'), encoding: 'base64' };
+
+            await api.put(`${entityPath}/contents/${relPath}`, payload);
+            console.log(`  ${relPath} (from project root)`);
+            toolsCount++;
+        }
+    } catch {
+        // No tools directory, skip
+    }
+
+    // 10. Upload server/ directory from project root (if it exists)
     const serverDir = join(projectRoot, 'server');
     let serverCount = 0;
     try {
@@ -211,7 +234,30 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
         // No server directory, skip
     }
 
-    // 10. Deploy: run migrations + scan/bundle server routes
+    // 11. Upload webhooks/ directory from project root (if it exists)
+    const webhooksDir = join(projectRoot, 'webhooks');
+    let webhooksCount = 0;
+    try {
+        await access(webhooksDir);
+        const webhookFiles = await walkDir(webhooksDir);
+        for (const filePath of webhookFiles) {
+            const relPath = posix.normalize(relative(projectRoot, filePath).split('\\').join('/'));
+            const content = await readFile(filePath);
+            const ext = '.' + relPath.split('.').pop();
+            const isText = TEXT_EXTENSIONS.has(ext.toLowerCase());
+            const payload = isText
+                ? { content: content.toString('utf8'), encoding: 'utf8' }
+                : { content: content.toString('base64'), encoding: 'base64' };
+
+            await api.put(`${entityPath}/contents/${relPath}`, payload);
+            console.log(`  ${relPath} (from project root)`);
+            webhooksCount++;
+        }
+    } catch {
+        // No webhooks directory, skip
+    }
+
+    // 12. Deploy: run migrations + scan/bundle server routes + webhooks + tools + agents
     if (apiPrefix === 'apps') {
         try {
             console.log('Deploying...');
@@ -226,14 +272,31 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
                         console.log(`    ${r}`);
                     }
                 }
+                if (result.webhooks && result.webhooks.length > 0) {
+                    console.log(`  Registered ${result.webhooks.length} webhook(s):`);
+                    for (const r of result.webhooks) {
+                        console.log(`    ${r}`);
+                    }
+                }
+                if (result.tools && result.tools.length > 0) {
+                    console.log(`  Registered ${result.tools.length} tool(s): ${result.tools.join(', ')}`);
+                }
+                if (result.agents && result.agents.length > 0) {
+                    console.log(`  Deployed ${result.agents.length} agent(s): ${result.agents.join(', ')}`);
+                }
+            }
+        } catch (err) {
+            if (err.status === 404) {
+                // Server may not support _deploy yet — ignore
+            } else {
+                const detail = err.body || err.message;
+                console.error(`  Deploy failed: ${detail}`);
             }
-        } catch {
-            // Server may not support _deploy yet — ignore
         }
     }
 
-    // 11. Print URL and return UUID for saving
-    const totalFiles = entries.length + configCount + migrationsCount + serverCount;
+    // 13. Print URL and return UUID for saving
+    const totalFiles = entries.length + configCount + migrationsCount + toolsCount + serverCount + webhooksCount;
     const base = baseUrl.replace(/\/+$/, '');
     const entityUrl = apiPrefix === 'apps'
         ? `${base}/api/apps/${naturalId}/view`

package/src/env.js

@@ -0,0 +1,86 @@
+import dotenv from 'dotenv';
+import { existsSync } from 'node:fs';
+import { resolve, dirname, parse as parsePath } from 'node:path';
+
+/**
+ * Build an ordered list of .env file paths for dotenv to load.
+ *
+ * Priority (first match wins in dotenv):
+ *   1. <cwd>/.env.<mode>   (mode-specific, e.g. .env.test)
+ *   2. <cwd>/.env          (local defaults)
+ *   3. <parent>/.env.<mode> (walk up for monorepo shared config)
+ *   4. <parent>/.env
+ *   ... continues up to first parent that contains a .env file
+ *
+ * When mode is 'development' (Vite default), mode-specific files are skipped
+ * since .env already serves that purpose.
+ *
+ * @param {{ mode?: string, cwd?: string }} options
+ * @returns {string[]} Ordered file paths (may include non-existent files — dotenv ignores those)
+ */
+export function buildEnvPaths({ mode, cwd } = {}) {
+    const dir = cwd || process.cwd();
+    const useMode = mode && mode !== 'development';
+
+    // Local project .env files (highest priority)
+    const paths = [];
+    if (useMode) paths.push(resolve(dir, `.env.${mode}`));
+    paths.push(resolve(dir, '.env'));
+
+    // Walk up to parent directories for monorepo fallback
+    let current = dirname(dir);
+    const { root } = parsePath(dir);
+
+    while (current !== root) {
+        if (useMode) paths.push(resolve(current, `.env.${mode}`));
+        paths.push(resolve(current, '.env'));
+
+        // Stop at the first ancestor that has any .env file
+        const hasEnv = useMode
+            ? existsSync(resolve(current, `.env.${mode}`)) || existsSync(resolve(current, '.env'))
+            : existsSync(resolve(current, '.env'));
+
+        if (hasEnv) break;
+
+        current = dirname(current);
+    }
+
+    return paths;
+}
+
+/**
+ * Load environment variables using mode-aware, parent-walking dotenv paths.
+ *
+ * @param {{ mode?: string, cwd?: string }} options
+ */
+export function loadEnv({ mode, cwd } = {}) {
+    const paths = buildEnvPaths({ mode, cwd });
+    dotenv.config({ path: paths });
+}
+
+/**
+ * Determine the .env file path to write workspace IDs into.
+ * Writes to .env.<mode> when a non-default mode is active, otherwise .env.
+ *
+ * @param {{ mode?: string, cwd?: string }} options
+ * @returns {string}
+ */
+export function envWritePath({ mode, cwd } = {}) {
+    const dir = cwd || process.cwd();
+    const useMode = mode && mode !== 'development';
+    return resolve(dir, useMode ? `.env.${mode}` : '.env');
+}
+
+/**
+ * Parse --mode <name> from a process.argv array.
+ *
+ * @param {string[]} argv
+ * @returns {string|null}
+ */
+export function parseModeArg(argv) {
+    const idx = argv.indexOf('--mode');
+    if (idx !== -1 && idx + 1 < argv.length) {
+        return argv[idx + 1];
+    }
+    return null;
+}

package/src/index.js

@@ -1,13 +1,14 @@
-import dotenv from 'dotenv';
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { createClient } from './client.js';
+import { loadEnv, envWritePath } from './env.js';
 import { createMiddleware as createServerRoutes } from './server-routes.js';
+import { createAgentMiddleware } from './agent-dev.js';
 import { init, migrate } from './workspace.js';
 
 /**
- * Vite plugin for local Magic Report development.
+ * Vite plugin for local Informer App development.
  *
  * - Proxies /api requests to the Informer server with Basic auth
  * - Runs server/ route handlers locally via ssrLoadModule (if server/ dir exists)
@@ -22,12 +23,14 @@ export default function informer(options = {}) {
     let authHeader = null;
     let serverOrigin = null;
     let devWorkspaceId = null;
+    let activeMode = null;
 
     return {
         name: 'vite-plugin-informer',
 
-        config(_, { command }) {
-            dotenv.config();
+        config(_, { command, mode }) {
+            activeMode = mode;
+            loadEnv({ mode });
 
             isDev = command === 'serve';
 
@@ -56,7 +59,8 @@ export default function informer(options = {}) {
                                 changeOrigin: true,
                                 headers: {
                                     Authorization: authHeader
-                                }
+                                },
+                                ...options.proxy
                             }
                         }
                     };
@@ -105,7 +109,7 @@ export default function informer(options = {}) {
                             api,
                             slug,
                             migrationsDir,
-                            envPath: resolve(projectRoot, '.env')
+                            envPath: envWritePath({ mode: activeMode })
                         });
                         devWorkspaceId = result.workspaceId;
                     }
@@ -129,6 +133,20 @@ export default function informer(options = {}) {
                 server.middlewares.use('/api/_server', serverRoutes);
             }
 
+            // Mount agent dev middleware if tools/ or informer.yaml agents exist
+            const toolsDir = resolve(projectRoot, 'tools');
+            const yamlPath = resolve(projectRoot, 'informer.yaml');
+
+            if (existsSync(toolsDir) || existsSync(yamlPath)) {
+                const agentDev = createAgentMiddleware(server, {
+                    serverOrigin,
+                    authHeader,
+                    devWorkspaceId,
+                    projectRoot
+                });
+                server.middlewares.use('/api/_agent', agentDev);
+            }
+
         },
 
         transformIndexHtml: {

package/src/server-routes.js

@@ -1,3 +1,4 @@
+import { createHmac } from 'node:crypto';
 import { readdir, stat } from 'node:fs/promises';
 import { join, relative, posix } from 'node:path';
 import { parse as parseUrl } from 'node:url';
@@ -218,17 +219,50 @@ export function createMiddleware(viteServer, { serverOrigin, authHeader, devWork
                 return;
             }
 
-            // Read request body
+            // Read request body — preserve raw bytes for HMAC verification
             const chunks = [];
             for await (const chunk of req) {
                 chunks.push(chunk);
             }
-            const rawBody = Buffer.concat(chunks).toString('utf8');
+            const rawBody = Buffer.concat(chunks).toString('utf8') || null;
             let body = null;
             if (rawBody) {
                 try { body = JSON.parse(rawBody); } catch { body = rawBody; }
             }
 
+            // crypto helper — mirrors the sandbox's crypto.hmac()
+            const cryptoHelper = {
+                hmac(algorithm, key, data, encoding) {
+                    return createHmac(algorithm, key).update(data).digest(encoding || 'hex');
+                }
+            };
+
+            // log helper — mirrors sandbox log(message, data) + log.info/warn/error/debug
+            const logCall = (level, message, data) => {
+                const msg = typeof message === 'string' ? message : JSON.stringify(message);
+                const args = [`[app-log] [${level}] ${msg}`];
+                if (data) args.push(data);
+                console.log(...args);
+            };
+            const log = Object.assign(
+                (message, data) => logCall('info', message, data),
+                {
+                    debug: (message, data) => logCall('debug', message, data),
+                    info: (message, data) => logCall('info', message, data),
+                    warn: (message, data) => logCall('warn', message, data),
+                    error: (message, data) => logCall('error', message, data)
+                }
+            );
+
+            // markdown helper — passthrough in dev (production uses `marked`)
+            const markdown = (text) => text;
+
+            // emit helper — no-op in dev (logs to console)
+            const emit = (event, payload) => {
+                console.log(`[app-event] emit("${event}",`, JSON.stringify(payload), ')');
+                return { ok: true };
+            };
+
             // Build request context
             const request = {
                 method: req.method.toUpperCase(),
@@ -236,12 +270,32 @@ export function createMiddleware(viteServer, { serverOrigin, authHeader, devWork
                 params: match.params,
                 query: parsed.query || {},
                 body,
+                rawBody,
                 headers: req.headers,
-                roles: roles || []
+                roles: roles || [],
+                user: {
+                    username: 'dev-user',
+                    displayName: 'Dev User',
+                    email: null,
+                    timezone: null
+                }
             };
 
+            // respond() — sends early response, handler continues in background
+            let responded = false;
+            function respond(earlyBody) {
+                if (responded) return;
+                responded = true;
+                res.statusCode = 200;
+                res.setHeader('Content-Type', 'application/json');
+                res.end(JSON.stringify(earlyBody));
+            }
+
             // Call handler
-            const result = await handler({ query, fetch: apiFetch, env: {}, request });
+            const result = await handler({ query, fetch: apiFetch, respond, emit, crypto: cryptoHelper, markdown, log, env: {}, request });
+
+            // If respond() was already called, the response is already sent
+            if (responded) return;
 
             // Normalize response (mirrors app-sandbox.js buildInvokeScript logic)
             let status, responseBody, responseHeaders;

package/src/workspace.js

@@ -1,5 +1,5 @@
 import { readdir, readFile, writeFile, access } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, basename } from 'node:path';
 
 /**
  * Execute raw SQL against a workspace datasource via the _sql route.
@@ -122,7 +122,7 @@ export async function init({ api, slug, migrationsDir, envPath }) {
     }
 
     await writeFile(envPath, envContent);
-    console.log(`Saved INFORMER_DEV_WORKSPACE=${workspaceId} to .env`);
+    console.log(`Saved INFORMER_DEV_WORKSPACE=${workspaceId} to ${basename(envPath)}`);
 
     return { workspaceId, ...result };
 }