@vesk/adapter 0.2.9 → 0.2.11

package/dist/dev-server.d.ts

@@ -1,7 +1,92 @@
 import { type Server } from 'node:http';
 import type { DevServerOptions } from '@vesk/adapter/src/types';
+/**
+ * Shape returned by the dev HMR state endpoint. Mirrors what the parallel
+ * `hmr.ts` agent's `getHmrState()` returns; we tolerate its absence at
+ * module-load time (see `devHmrState`) so this module stays importable even
+ * before the state provider lands.
+ */
+export interface DevHmrState {
+    status: 'up' | 'compiling' | 'error' | 'down';
+    lastCompileMs: number | null;
+    error: Record<string, unknown> | null;
+    hasError: boolean;
+    componentCount: number;
+}
+/** Default state when no HMR provider is available (no server). */
+export declare function defaultDevHmrState(): DevHmrState;
 export declare function bodyTooLarge(maxBytes: number): Error & {
     status: number;
 };
+export interface DevPanelResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+    /** When 'base64', the dev server writes Buffer.from(body, 'base64') to the socket (binary payloads like icons). */
+    encoding?: 'utf8' | 'base64';
+    /** When set, `body`/`encoding` are ignored and this async iterable of
+        (already-framed) strings is streamed to the client instead — used for
+        SSE agent progress. */
+    stream?: AsyncIterable<string>;
+}
+export interface PluginRouterChangeEvent {
+    type: 'activate' | 'deactivate' | 'install' | 'uninstall' | 'update';
+    name?: string;
+}
+export interface PluginStateRouterOptions {
+    appDir: string;
+    veskDir: string;
+    configPluginNames: string[];
+    getHmrState?: () => DevHmrState;
+    /** Called after a mutation so the caller can rebuild + notify HMR clients. */
+    onPluginChange?: (event: PluginRouterChangeEvent) => void | Promise<void>;
+}
+/**
+ * Pure, dependency-injectable router for the dev panel HTTP endpoints
+ * (`/__vesk/...`). Everything is testable with fake inputs — no socket, no
+ * listener. Returns `null` for paths that are not dev-panel endpoints so the
+ * dev server can fall through to its normal route handling.
+ *
+ * Endpoints:
+ *   GET  /__vesk/hmr/state                       → { ...DevHmrState }
+ *   GET  /__vesk/plugins                         → { plugins: PluginRecord[] } (registry-enriched)
+ *   POST /__vesk/plugins/activate                → { ok, record }
+ *   POST /__vesk/plugins/deactivate              → { ok, record }
+ *   POST /__vesk/plugins/install                 → { ok, record }
+ *   POST /__vesk/plugins/uninstall               → { ok }
+ *   POST /__vesk/plugins/update                  → { ok, record }
+ *   GET  /__vesk/plugins/search?q=<query>        → { results: PluginSearchResult[] }
+ *   GET  /__vesk/plugins/:name/icon              → { base64 + mime } (or 404)
+ *   GET  /__vesk/plugins/:name/exports           → { PluginExportsInfo }
+ *   (anything else under /__vesk/*)              → 404 { error }
+ */
+export declare function createPluginStateRouter(opts: PluginStateRouterOptions): {
+    route: (method: string, pathname: string, body?: unknown, search?: string) => Promise<DevPanelResponse | null>;
+};
+/**
+ * Inline bootstrap script injected after the dev/HMR scripts on every served
+ * dev page. On DOMContentLoaded it polls `/__vesk/hmr/state` and — if the
+ * server reports a persisted error — calls the client's registered
+ * `globalThis.__vesk_hmr_show(payload)` to re-open the error overlay. This
+ * satisfies the Nuxt-like "a refresh during an active error should still show
+ * the overlay" requirement, because the client bundle's own state fetch only
+ * fires after its module runs.
+ *
+ * Idempotency: the `window.__vesk_hmr_bootstrap` guard makes the inline script
+ * run at most once per page even if it is injected at multiple `</body>` sites
+ * (or on a page served more than once). The overlay itself cannot be duplicated
+ * because the client's `showOverlay` reuses a single `#__vesk_overlay` element
+ * (guarded in `createOverlay`), and `__vesk_hmr_show` is registered once by
+ * `registerGlobalHmr`. So a double-show (inline bootstrap + client's own
+ * `loadPersistedState`) re-renders the same overlay rather than stacking a
+ * second one.
+ */
+export declare function devBootstrapScript(): string;
+/**
+ * Inject the dev/HMR client script plus the inline state bootstrap into an HTML
+ * page at its first `</body>`. Idempotent when there is no `</body>`: the HTML
+ * is returned unchanged (never injected twice / never appended uncontrolled).
+ */
+export declare function injectDevScripts(html: string): string;
 export declare function startDevServer(appDir: string, options?: DevServerOptions): Promise<Server | void>;
 //# sourceMappingURL=dev-server.d.ts.map

package/dist/dev-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev-server.d.ts","sourceRoot":"","sources":["../src/dev-server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,MAAM,EAA6C,MAAM,WAAW,CAAC;AAQjG,OAAO,KAAK,EAAa,gBAAgB,EAAY,MAAM,yBAAyB,CAAC;AAWrF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAIzE;AA6DD,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoTvG"}
+{"version":3,"file":"dev-server.d.ts","sourceRoot":"","sources":["../src/dev-server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,MAAM,EAA6C,MAAM,WAAW,CAAC;AAUjG,OAAO,KAAK,EAAa,gBAAgB,EAAwB,MAAM,yBAAyB,CAAC;AAgBjG;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,IAAI,GAAG,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;IAC9C,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACtC,QAAQ,EAAE,OAAO,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,mEAAmE;AACnE,wBAAgB,kBAAkB,IAAI,WAAW,CAEhD;AAuCD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAIzE;AAkBD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,mHAAmH;IACnH,QAAQ,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC7B;;8BAE0B;IAC1B,MAAM,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,UAAU,GAAG,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,WAAW,CAAC;IAChC,8EAA8E;IAC9E,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,wBAAwB,GAAG;IACvE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;CAChH,CAUA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAa3C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrD;AA6CD,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoevG"}

package/dist/dev-server.js

@@ -5,10 +5,55 @@ import { fileURLToPath } from 'node:url';
 import { stripCodeTypes } from '@vesk/compiler/src/strip-ts';
 import { DEFAULT_MAX_BODY_BYTES } from '@vesk/compiler/src/server-codegen';
 import { build } from '@vesk/adapter/src/index';
-import { createHmrServer } from '@vesk/adapter/src/hmr';
+import { createHmrServer } from './hmr';
+import * as hmrApi from './hmr';
+import { createDevApiRouter } from './dev-api';
 import { buildRuntimeCode } from '@vesk/adapter/src/client-bundle';
-import { resolveWithin } from '@vesk/adapter/src/paths';
+import { resolveWithin, installMdReadHook } from '@vesk/adapter/src/paths';
+import { getPluginRecords } from './plugins';
+// @vesk/agentic — optional AI plugin; gated by active state if installed
+import { createAgentRouter } from '@vesk/agentic/src/dev-api';
+import { CheckpointManager } from '@vesk/agentic/src/checkpoints';
+import { AgentCapabilityTable } from '@vesk/agentic/src/permissions';
+import { openAiProvider } from '@vesk/agentic/src/providers/openai';
+import { anthropicProvider } from '@vesk/agentic/src/providers/anthropic';
+import { Agent } from '@vesk/agentic/src/loop';
+import { createVeskTools } from '@vesk/agentic/src/tools/vesk';
+import { getApiKey, loadAgenticConfig, SUPPORTED_PROVIDERS } from '@vesk/agentic/src/config';
 const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Default state when no HMR provider is available (no server). */
+export function defaultDevHmrState() {
+    return { status: 'up', lastCompileMs: null, error: null, hasError: false, componentCount: 0 };
+}
+/** The live HMR state provider: the parallel agent's `getHmrState` if present, else a safe no-server default. */
+const devHmrState = typeof hmrApi.getHmrState === 'function'
+    ? hmrApi.getHmrState
+    : defaultDevHmrState;
+/**
+ * Writes a handler Response to the socket, piping a streaming body
+ * chunk-by-chunk (SSE / text streams) instead of buffering everything.
+ */
+async function deliverResponse(res, response) {
+    res.writeHead(response.status, Object.fromEntries(response.headers));
+    const body = response.body;
+    if (body && typeof body.getReader === 'function') {
+        const reader = body.getReader();
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                res.write(Buffer.from(value));
+            }
+        }
+        catch {
+            /* stream aborted by the client */
+        }
+        res.end();
+        return;
+    }
+    res.end(await response.text());
+}
 export function bodyTooLarge(maxBytes) {
     const err = new Error(`Request body exceeds limit (${maxBytes} bytes)`);
     err.status = 413;
@@ -29,6 +74,77 @@ async function readBody(req, maxBytes = DEFAULT_MAX_BODY_BYTES) {
     }
     return Buffer.concat(chunks);
 }
+/**
+ * Pure, dependency-injectable router for the dev panel HTTP endpoints
+ * (`/__vesk/...`). Everything is testable with fake inputs — no socket, no
+ * listener. Returns `null` for paths that are not dev-panel endpoints so the
+ * dev server can fall through to its normal route handling.
+ *
+ * Endpoints:
+ *   GET  /__vesk/hmr/state                       → { ...DevHmrState }
+ *   GET  /__vesk/plugins                         → { plugins: PluginRecord[] } (registry-enriched)
+ *   POST /__vesk/plugins/activate                → { ok, record }
+ *   POST /__vesk/plugins/deactivate              → { ok, record }
+ *   POST /__vesk/plugins/install                 → { ok, record }
+ *   POST /__vesk/plugins/uninstall               → { ok }
+ *   POST /__vesk/plugins/update                  → { ok, record }
+ *   GET  /__vesk/plugins/search?q=<query>        → { results: PluginSearchResult[] }
+ *   GET  /__vesk/plugins/:name/icon              → { base64 + mime } (or 404)
+ *   GET  /__vesk/plugins/:name/exports           → { PluginExportsInfo }
+ *   (anything else under /__vesk/*)              → 404 { error }
+ */
+export function createPluginStateRouter(opts) {
+    // Delegates to the unified DevTools router (dev-api.ts) for the plugin +
+    // HMR-state surface, preserving the exact wire contract.
+    return createDevApiRouter({
+        appDir: opts.appDir,
+        veskDir: opts.veskDir,
+        configPluginNames: opts.configPluginNames,
+        getHmrState: opts.getHmrState,
+        onPluginChange: opts.onPluginChange,
+    });
+}
+/**
+ * Inline bootstrap script injected after the dev/HMR scripts on every served
+ * dev page. On DOMContentLoaded it polls `/__vesk/hmr/state` and — if the
+ * server reports a persisted error — calls the client's registered
+ * `globalThis.__vesk_hmr_show(payload)` to re-open the error overlay. This
+ * satisfies the Nuxt-like "a refresh during an active error should still show
+ * the overlay" requirement, because the client bundle's own state fetch only
+ * fires after its module runs.
+ *
+ * Idempotency: the `window.__vesk_hmr_bootstrap` guard makes the inline script
+ * run at most once per page even if it is injected at multiple `</body>` sites
+ * (or on a page served more than once). The overlay itself cannot be duplicated
+ * because the client's `showOverlay` reuses a single `#__vesk_overlay` element
+ * (guarded in `createOverlay`), and `__vesk_hmr_show` is registered once by
+ * `registerGlobalHmr`. So a double-show (inline bootstrap + client's own
+ * `loadPersistedState`) re-renders the same overlay rather than stacking a
+ * second one.
+ */
+export function devBootstrapScript() {
+    return ("<script>\n" +
+        "if(!window.__vesk_hmr_bootstrap){window.__vesk_hmr_bootstrap=1;" +
+        "(function(){function boot(){fetch('/__vesk/hmr/state')" +
+        ".then(function(r){return r.ok?r.json():null;}).then(function(s){" +
+        "if(s&&s.error&&window.__vesk_hmr_show){window.__vesk_hmr_show(s.error);}" +
+        "}).catch(function(){});}" +
+        "if(document.readyState==='loading'){document.addEventListener('DOMContentLoaded',boot);}else{boot();}" +
+        "})();" +
+        "}\n" +
+        "</script>");
+}
+/**
+ * Inject the dev/HMR client script plus the inline state bootstrap into an HTML
+ * page at its first `</body>`. Idempotent when there is no `</body>`: the HTML
+ * is returned unchanged (never injected twice / never appended uncontrolled).
+ */
+export function injectDevScripts(html) {
+    if (!html.includes('</body>'))
+        return html;
+    const scripts = '\t<script type="module" src="/_vesk/hmr.js"></script>\n' + devBootstrapScript() + '\n';
+    return html.replace('</body>', scripts + '</body>');
+}
 function makeWebRequest(nodeReq, url, maxBodyBytes = DEFAULT_MAX_BODY_BYTES) {
     const parsedUrl = new URL(url, `http://${nodeReq.headers.host || 'localhost'}`);
     const method = nodeReq.method || 'GET';
@@ -86,6 +202,139 @@ export async function startDevServer(appDir, options) {
         process.env.NODE_ENV = 'development';
     const devDir = resolve(appDir, '..', '.vesk', 'dev');
     const publicDir = options?.publicDir || resolve(appDir, '..', 'public');
+    installMdReadHook([publicDir, resolve(devDir, 'static', 'public')]);
+    // Dev-panel plugin list: plugin / module names declared in the dev server's own config.
+    const configPluginNames = (options?.plugins || []).map((p) => {
+        if (typeof p === 'string')
+            return p;
+        return p.name;
+    }).filter((n) => typeof n === 'string' && !!n);
+    // ── @vesk/agentic dev API (B6-plug) — chained BEFORE the core dev API ─────
+    // Chain: createAgentRouter (CheckpointManager + AgentCapabilityTable + Provider
+    // via openAiProvider/anthropicProvider, .env.local VK_{PROVIDER}_KEY) →
+    // createDevApiRouter. Gate: only expose /__vesk/agent/* when @vesk/agentic
+    // is installed AND active (otherwise lean core, no agent surface).
+    const agenticCheckpointManager = new CheckpointManager();
+    const agenticVeskDir = resolve(appDir, '..', '.vesk');
+    const agenticProjectDir = resolve(appDir, '..');
+    function isAgenticActive() {
+        try {
+            if (SUPPORTED_PROVIDERS.some((p) => !!getApiKey(agenticProjectDir, p)))
+                return true;
+        }
+        catch { }
+        try {
+            const records = getPluginRecords(appDir, agenticVeskDir, configPluginNames);
+            const rec = records.find((r) => r.name === '@vesk/agentic' || r.package === '@vesk/agentic');
+            if (!rec)
+                return false;
+            return rec.active;
+        }
+        catch {
+            return false;
+        }
+    }
+    function getAgenticPermissions() {
+        const rawMode = process.env.VESK_AGENTIC_MODE || 'explore';
+        const valid = ['explore', 'debug', 'agent'];
+        const mode = (valid.includes(rawMode) ? rawMode : 'explore');
+        return new AgentCapabilityTable(mode);
+    }
+    async function runAgenticAgent(prompt, _mode, providerConfig) {
+        const cfg = (providerConfig || {});
+        const provider = await buildAdapterAgenticProvider(cfg);
+        const tools = createVeskTools({ projectDir: agenticProjectDir, appDir, veskDir: agenticVeskDir });
+        const budget = resolveAdapterAgenticStepBudget(cfg);
+        const agent = new Agent({ provider, tools, maxSteps: budget.maxSteps, autoExtend: budget.autoExtend, hardMaxSteps: budget.hardMaxSteps });
+        return agent.run(prompt);
+    }
+    async function* runAgenticAgentStream(prompt, _mode, providerConfig) {
+        const cfg = (providerConfig || {});
+        const provider = await buildAdapterAgenticProvider(cfg);
+        const tools = createVeskTools({ projectDir: agenticProjectDir, appDir, veskDir: agenticVeskDir });
+        const budget = resolveAdapterAgenticStepBudget(cfg);
+        const agent = new Agent({ provider, tools, maxSteps: budget.maxSteps, autoExtend: budget.autoExtend, hardMaxSteps: budget.hardMaxSteps });
+        yield* agent.runStream(prompt);
+    }
+    async function buildAdapterAgenticProvider(cfg) {
+        const providerName = String(cfg.provider || loadAgenticConfig(agenticProjectDir).provider || 'openai');
+        const apiKey = cfg.apiKey || getApiKey(agenticProjectDir, providerName) || '';
+        const model = cfg.model || loadAgenticConfig(agenticProjectDir).model || (providerName === 'anthropic' ? 'claude-sonnet-4-6' : providerName === 'google' ? 'gemini-2.0-flash' : providerName === 'ollama' ? 'llama3.1' : providerName === 'opencode' ? 'claude-sonnet-4-6' : providerName === 'opencode-go' ? 'opencode-go/kimi-k3' : providerName === 'openrouter' ? 'openrouter/auto' : 'gpt-4o-mini');
+        const baseUrl = cfg.baseUrl || loadAgenticConfig(agenticProjectDir).baseUrl || undefined;
+        const maxTokens = typeof cfg.maxTokens === 'number' ? cfg.maxTokens : undefined;
+        if (providerName === 'anthropic')
+            return anthropicProvider({ apiKey, model, baseUrl, maxTokens });
+        if (providerName === 'google') {
+            const { googleProvider } = await import('@vesk/agentic/src/providers/google');
+            return googleProvider({ apiKey, model, baseUrl });
+        }
+        if (providerName === 'ollama') {
+            const { ollamaProvider } = await import('@vesk/agentic/src/providers/ollama');
+            return ollamaProvider({ model, baseUrl });
+        }
+        if (providerName === 'opencode')
+            return openAiProvider({ apiKey, model, baseUrl: baseUrl || 'https://opencode.ai/zen/v1' });
+        if (providerName === 'opencode-go')
+            return openAiProvider({ apiKey, model, baseUrl: baseUrl || 'https://opencode.ai/zen/go/v1' });
+        if (providerName === 'openrouter')
+            return openAiProvider({ apiKey, model, baseUrl: baseUrl || 'https://openrouter.ai/api/v1' });
+        if (providerName === 'loopers')
+            return openAiProvider({ apiKey, model, baseUrl: baseUrl || 'http://localhost:8080' });
+        return openAiProvider({ apiKey, model, baseUrl });
+    }
+    function resolveAdapterAgenticStepBudget(cfg) {
+        const fileCfg = loadAgenticConfig(agenticProjectDir);
+        const requestVal = typeof cfg.maxSteps === 'number' && Number.isFinite(cfg.maxSteps) ? cfg.maxSteps : NaN;
+        const fileVal = typeof fileCfg.maxSteps === 'number' && fileCfg.maxSteps > 0 ? fileCfg.maxSteps : NaN;
+        const maxSteps = Number.isFinite(requestVal) ? Math.max(1, Math.floor(requestVal)) : Number.isFinite(fileVal) ? Math.floor(fileVal) : 25;
+        return { maxSteps, autoExtend: true, hardMaxSteps: 200 };
+    }
+    let agentRouter = null;
+    try {
+        if (isAgenticActive()) {
+            agentRouter = createAgentRouter({
+                projectDir: agenticProjectDir,
+                appDir,
+                veskDir: agenticVeskDir,
+                getPermissions: getAgenticPermissions,
+                runAgent: runAgenticAgent,
+                runAgentStream: runAgenticAgentStream,
+                listCheckpoints: () => agenticCheckpointManager.listNewestFirst(),
+                rollback: (id) => agenticCheckpointManager.get(id) ?? null,
+                createCheckpoint: (...args) => {
+                    const first = args[0];
+                    if (first && typeof first === 'object' && ('label' in first || 'message' in first)) {
+                        return agenticCheckpointManager.create(first);
+                    }
+                    const msg = typeof first === 'string' ? first : 'checkpoint';
+                    return agenticCheckpointManager.create({ label: msg, message: msg });
+                },
+            });
+        }
+    }
+    catch {
+        agentRouter = null;
+    }
+    // Late-bound so the router's onPluginChange can broadcast over the HMR
+    // WebSocket, which is only created further down in this function.
+    let hmrSession = null;
+    const devPanel = createPluginStateRouter({
+        appDir,
+        veskDir: resolve(appDir, '..', '.vesk'),
+        configPluginNames,
+        getHmrState: devHmrState,
+        onPluginChange: async (event) => {
+            try {
+                await doBuild();
+                if (hmrSession) {
+                    hmrSession.broadcast('reload', { reason: `Plugin ${event.type}: ${event.name ?? ''}`, time: Date.now() });
+                }
+            }
+            catch {
+                /* plugin change rebuild is best-effort; the server keeps serving */
+            }
+        },
+    });
     let componentMap = new Map();
     const monorepoRouter = resolve(__dirname, '..', '..', 'compiler', 'dist', 'router.js');
     const pkgRouter = resolve(appDir, '..', 'node_modules', '@vesk/compiler', 'router.js');
@@ -126,6 +375,79 @@ export async function startDevServer(appDir, options) {
     await doBuild();
     const server = createServer(async (req, res) => {
         const url = new URL(req.url || '/', `http://localhost:${port}`);
+        // Dev panel endpoints (/__vesk/...): HMR state, plugin list, activate/
+        // deactivate/install/uninstall. Routed through the pure injectable router.
+        // Chain: agent router (CheckpointManager + AgentCapabilityTable + Provider
+        // via openAiProvider/anthropicProvider, .env.local VK_{PROVIDER}_KEY)
+        // is tried BEFORE the core dev panel, gated by @vesk/agentic active.
+        if (url.pathname.startsWith('/__vesk/')) {
+            let body = undefined;
+            if ((req.method || 'GET') === 'POST') {
+                try {
+                    const buf = await readBody(req, maxBodyBytes);
+                    body = buf.length > 0 ? JSON.parse(buf.toString()) : {};
+                }
+                catch (e) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: e instanceof Error ? e.message : String(e) }));
+                    return;
+                }
+            }
+            if (agentRouter) {
+                const agentResult = await agentRouter.route(req.method || 'GET', url.pathname, body, url.search);
+                if (agentResult) {
+                    if (agentResult.stream) {
+                        res.writeHead(agentResult.status, agentResult.headers);
+                        res.flushHeaders?.();
+                        void (async () => {
+                            try {
+                                for await (const chunk of agentResult.stream) {
+                                    if (!res.writableEnded)
+                                        res.write(chunk);
+                                }
+                            }
+                            catch {
+                                /* stream aborted */
+                            }
+                            finally {
+                                if (!res.writableEnded)
+                                    res.end();
+                            }
+                        })();
+                        return;
+                    }
+                    res.writeHead(agentResult.status, agentResult.headers);
+                    res.end(agentResult.encoding === 'base64' ? Buffer.from(agentResult.body, 'base64') : agentResult.body);
+                    return;
+                }
+            }
+            const result = await devPanel.route(req.method || 'GET', url.pathname, body, url.search);
+            if (result) {
+                if (result.stream) {
+                    res.writeHead(result.status, result.headers);
+                    res.flushHeaders?.();
+                    void (async () => {
+                        try {
+                            for await (const chunk of result.stream) {
+                                if (!res.writableEnded)
+                                    res.write(chunk);
+                            }
+                        }
+                        catch {
+                            /* stream aborted */
+                        }
+                        finally {
+                            if (!res.writableEnded)
+                                res.end();
+                        }
+                    })();
+                    return;
+                }
+                res.writeHead(result.status, result.headers);
+                res.end(result.encoding === 'base64' ? Buffer.from(result.body, 'base64') : result.body);
+                return;
+            }
+        }
         if (url.pathname === '/_vesk/hmr.js') {
             const monorepoRoot = resolve(__dirname, '..', '..', '..');
             const runtimeSrc = resolve(monorepoRoot, 'packages', 'runtime', 'dist');
@@ -195,7 +517,7 @@ export async function startDevServer(appDir, options) {
                             const contentType = headers['content-type'] || '';
                             let finalBody = body;
                             if (contentType.includes('text/html')) {
-                                finalBody = body.replace('</body>', '\t<script type="module" src="/_vesk/hmr.js"></script>\n</body>');
+                                finalBody = injectDevScripts(body);
                             }
                             res.writeHead(response.status, headers);
                             res.end(finalBody);
@@ -223,9 +545,7 @@ export async function startDevServer(appDir, options) {
                         const mod = await import(`${handlerPath}?t=${ssrVersion}`);
                         const webRequest = makeWebRequest(req, url.href, maxBodyBytes);
                         const response = await mod.handle(webRequest);
-                        const body = await response.text();
-                        res.writeHead(response.status, Object.fromEntries(response.headers));
-                        res.end(body);
+                        await deliverResponse(res, response);
                     }
                     catch (e) {
                         const message = e instanceof Error ? e.message : String(e);
@@ -250,7 +570,7 @@ export async function startDevServer(appDir, options) {
                         const contentType = headers['content-type'] || '';
                         let finalBody = body;
                         if (contentType.includes('text/html')) {
-                            finalBody = body.replace('</body>', '\t<script type="module" src="/_vesk/hmr.js"></script>\n</body>');
+                            finalBody = injectDevScripts(body);
                         }
                         res.writeHead(response.status, headers);
                         res.end(finalBody);
@@ -277,7 +597,7 @@ export async function startDevServer(appDir, options) {
                         const contentType = headers['content-type'] || '';
                         let finalBody = body;
                         if (contentType.includes('text/html')) {
-                            finalBody = body.replace('</body>', '\t<script type="module" src="/_vesk/hmr.js"></script>\n</body>');
+                            finalBody = injectDevScripts(body);
                         }
                         res.writeHead(200, headers);
                         res.end(finalBody);
@@ -294,6 +614,7 @@ export async function startDevServer(appDir, options) {
         res.end('<!DOCTYPE html><html><body><h1>404</h1><p>Not Found</p></body></html>');
     });
     const hmr = createHmrServer(server, appDir, devDir, componentMap);
+    hmrSession = hmr;
     const srcDir = resolve(appDir, '..', 'src');
     try {
         if (existsSync(srcDir)) {

package/dist/error-codeframe.d.ts

@@ -0,0 +1,23 @@
+export interface CodeLine {
+    no: number;
+    text: string;
+    isError: boolean;
+}
+export interface Codeframe {
+    file: string;
+    line: number;
+    column: number;
+    context: number;
+    code: CodeLine[];
+}
+export declare function buildCodeframe(src: string, line: number, column?: number, context?: number): Codeframe | null;
+export interface ErroredLocation {
+    file: string;
+    line: number | null;
+    column: number | null;
+    message: string;
+    stack: string | null;
+    codeframe: Codeframe | null;
+}
+export declare function parseCompilerError(err: unknown, file: string, src?: string): ErroredLocation | null;
+//# sourceMappingURL=error-codeframe.d.ts.map

package/dist/error-codeframe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codeframe.d.ts","sourceRoot":"","sources":["../src/error-codeframe.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,QAAQ,EAAE,CAAC;CAClB;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,SAAI,GAAG,SAAS,GAAG,IAAI,CAcxG;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;CAC7B;AAuBD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAwFnG"}

package/dist/error-codeframe.js

@@ -0,0 +1,127 @@
+export function buildCodeframe(src, line, column, context = 5) {
+    if (typeof src !== 'string' || src.length === 0)
+        return null;
+    if (typeof line !== 'number' || !Number.isInteger(line))
+        return null;
+    const lines = src.split('\n');
+    if (line < 1 || line > lines.length)
+        return null;
+    const col = typeof column === 'number' && Number.isInteger(column) && column >= 1 ? column : 1;
+    const window = typeof context === 'number' && Number.isFinite(context) && context >= 0 ? context : 5;
+    const start = Math.max(1, line - window);
+    const end = Math.min(lines.length, line + window);
+    const code = [];
+    for (let i = start; i <= end; i++) {
+        code.push({ no: i, text: lines[i - 1] ?? '', isError: i === line });
+    }
+    return { file: '', line, column: col, context: window, code };
+}
+const LOCATION_RE = /\((\d+):(\d+)\)/;
+function asRecord(v) {
+    if (typeof v === 'object' && v !== null)
+        return v;
+    return null;
+}
+function asNumber(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return Math.trunc(v);
+    return null;
+}
+function parseEmbeddedLocation(message) {
+    const m = message.match(LOCATION_RE);
+    if (!m)
+        return null;
+    const line = parseInt(m[1], 10);
+    const column = parseInt(m[2], 10);
+    if (!Number.isFinite(line) || !Number.isFinite(column))
+        return null;
+    return { line, column: column + 1 };
+}
+export function parseCompilerError(err, file, src) {
+    if (err === undefined || err === null)
+        return null;
+    const record = asRecord(err);
+    let message;
+    let stack = null;
+    if (record && typeof record.message === 'string') {
+        message = record.message;
+        if (typeof record.stack === 'string')
+            stack = record.stack;
+    }
+    else if (typeof err === 'string') {
+        message = err;
+    }
+    else {
+        try {
+            message = String(err);
+        }
+        catch {
+            message = 'Unknown compiler error';
+        }
+        const asAny = err;
+        if (asAny && typeof asAny.stack === 'string')
+            stack = asAny.stack;
+    }
+    let line = null;
+    let column = null;
+    let fileResolved = typeof file === 'string' ? file : '';
+    // acorn raises VeskError with `.loc { line, column }` (column 0-based) and
+    // other codegen errors carry `.position` / `.pos` plus `.line`/`.column`
+    // fields on the VeskError class itself. Prefer explicit fields.
+    if (record) {
+        const loc = asRecord(record.loc);
+        if (loc) {
+            const ln = asNumber(loc.line);
+            if (ln !== null) {
+                line = ln;
+                const rawCol = asNumber(loc.column);
+                column = rawCol !== null ? rawCol + 1 : 1;
+            }
+        }
+        if (line === null) {
+            const pos = asRecord(record.position);
+            if (pos) {
+                const ln = asNumber(pos.line);
+                if (ln !== null) {
+                    line = ln;
+                    const rawCol = asNumber(pos.column);
+                    column = rawCol !== null ? rawCol + 1 : 1;
+                }
+            }
+        }
+        if (line === null) {
+            const ln = asNumber(record.line);
+            if (ln !== null && ln > 0) {
+                line = ln;
+                const rawCol = asNumber(record.column);
+                if (rawCol !== null)
+                    column = rawCol;
+            }
+        }
+        if (typeof record.file === 'string' && record.file)
+            fileResolved = record.file;
+    }
+    // Fall back to the "(line:column)" embedded in the message text (column is
+    // 0-based in VeskError messages, matching acorn's loc).
+    if (line === null) {
+        const embedded = parseEmbeddedLocation(message);
+        if (embedded) {
+            line = embedded.line;
+            column = embedded.column;
+        }
+    }
+    let codeframe = null;
+    if (src !== undefined && typeof src === 'string' && src.length > 0 && line !== null) {
+        codeframe = buildCodeframe(src, line, column ?? 1);
+        if (codeframe)
+            codeframe.file = fileResolved;
+    }
+    return {
+        file: fileResolved,
+        line,
+        column,
+        message,
+        stack,
+        codeframe,
+    };
+}

package/dist/error-tips.d.ts

@@ -0,0 +1,7 @@
+export interface ErrorTips {
+    tips: string[];
+    suggestions: string[];
+    nextSteps: string[];
+}
+export declare function suggestFor(message: string): ErrorTips;
+//# sourceMappingURL=error-tips.d.ts.map

package/dist/error-tips.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-tips.d.ts","sourceRoot":"","sources":["../src/error-tips.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AA8FD,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAMrD"}