@constructive-io/graphql-server 5.14.6 → 5.15.0

package/agentic/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Agent threads REST API — server-internal Express router
+ *
+ * Stateful agent-thread service (chat streaming, billing metering, inference
+ * logging) mounted by the GraphQL server. Uses @constructive-io/express-context
+ * for tenant-scoped database access.
+ *
+ * LLM provider config is resolved per-database via `ctx.useLlm()` (from the
+ * llm_module table), falling back to env vars from @constructive-io/llm-env when the module
+ * is not provisioned. Discovery and billing are handled by the shared loaders
+ * in express-context — no custom caching here.
+ *
+ * @example
+ * ```typescript
+ * import { createContextMiddleware } from '@constructive-io/express-context';
+ * import { createAgenticRouter } from './agentic';
+ *
+ * app.use(createContextMiddleware());
+ * app.use(createAgenticRouter());
+ * ```
+ */
+export { createAgenticRouter } from './router';
+export type { BillingClient, InferenceLogEntry, LlmConfig } from '@constructive-io/express-context';
+export type { LlmEnvOptions, LlmProviderConfig, ResolvedLlmEnvOptions } from '@constructive-io/llm-env';
+export { getEnvOptions as getLlmEnvOptions, getEnvVars as getLlmEnvVars, llmDefaults } from '@constructive-io/llm-env';

package/agentic/index.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Agent threads REST API — server-internal Express router
+ *
+ * Stateful agent-thread service (chat streaming, billing metering, inference
+ * logging) mounted by the GraphQL server. Uses @constructive-io/express-context
+ * for tenant-scoped database access.
+ *
+ * LLM provider config is resolved per-database via `ctx.useLlm()` (from the
+ * llm_module table), falling back to env vars from @constructive-io/llm-env when the module
+ * is not provisioned. Discovery and billing are handled by the shared loaders
+ * in express-context — no custom caching here.
+ *
+ * @example
+ * ```typescript
+ * import { createContextMiddleware } from '@constructive-io/express-context';
+ * import { createAgenticRouter } from './agentic';
+ *
+ * app.use(createContextMiddleware());
+ * app.use(createAgenticRouter());
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.llmDefaults = exports.getLlmEnvVars = exports.getLlmEnvOptions = exports.createAgenticRouter = void 0;
+var router_1 = require("./router");
+Object.defineProperty(exports, "createAgenticRouter", { enumerable: true, get: function () { return router_1.createAgenticRouter; } });
+var llm_env_1 = require("@constructive-io/llm-env");
+Object.defineProperty(exports, "getLlmEnvOptions", { enumerable: true, get: function () { return llm_env_1.getEnvOptions; } });
+Object.defineProperty(exports, "getLlmEnvVars", { enumerable: true, get: function () { return llm_env_1.getEnvVars; } });
+Object.defineProperty(exports, "llmDefaults", { enumerable: true, get: function () { return llm_env_1.llmDefaults; } });

package/agentic/router.d.ts

@@ -0,0 +1,21 @@
+/**
+ * router — Express router for the agentic-server
+ *
+ * Provides REST endpoints for AI agent conversations:
+ *
+ *   POST /v1/threads                             → create thread
+ *   POST /v1/threads/:thread_id/messages         → send message + stream response
+ *   POST /v1/orgs/:entity_id/threads             → create thread (entity-scoped)
+ *   POST /v1/orgs/:entity_id/threads/:thread_id/messages → send message (entity-scoped)
+ *   POST /v1/embed                               → generate embedding
+ *
+ * All routes require `req.constructive` (from @constructive-io/express-context).
+ * Billing (check_quota + record_usage) and inference logging are automatic
+ * when the billing/inference_log modules are provisioned.
+ *
+ * LLM provider config is resolved per-database via `ctx.useLlm()` from the
+ * llm_module table, falling back to env vars (EMBEDDER_*, CHAT_*) when the
+ * module is not provisioned.
+ */
+import { Router } from 'express';
+export declare function createAgenticRouter(): Router;

package/agentic/router.js

@@ -0,0 +1,522 @@
+"use strict";
+/**
+ * router — Express router for the agentic-server
+ *
+ * Provides REST endpoints for AI agent conversations:
+ *
+ *   POST /v1/threads                             → create thread
+ *   POST /v1/threads/:thread_id/messages         → send message + stream response
+ *   POST /v1/orgs/:entity_id/threads             → create thread (entity-scoped)
+ *   POST /v1/orgs/:entity_id/threads/:thread_id/messages → send message (entity-scoped)
+ *   POST /v1/embed                               → generate embedding
+ *
+ * All routes require `req.constructive` (from @constructive-io/express-context).
+ * Billing (check_quota + record_usage) and inference logging are automatic
+ * when the billing/inference_log modules are provisioned.
+ *
+ * LLM provider config is resolved per-database via `ctx.useLlm()` from the
+ * llm_module table, falling back to env vars (EMBEDDER_*, CHAT_*) when the
+ * module is not provisioned.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgenticRouter = createAgenticRouter;
+const ollama_1 = require("@agentic-kit/ollama");
+const llm_env_1 = require("@constructive-io/llm-env");
+const logger_1 = require("@pgpmjs/logger");
+const express_1 = __importStar(require("express"));
+const log = new logger_1.Logger('agentic-server');
+function resolveChatAdapter(llm) {
+    const provider = llm?.chatProvider ?? (0, llm_env_1.getEnvOptions)().chat.provider;
+    const model = llm?.chatModel ?? (0, llm_env_1.getEnvOptions)().chat.model;
+    const baseUrl = llm?.chatBaseUrl ?? (0, llm_env_1.getEnvOptions)().chat.baseUrl;
+    if (provider === 'ollama') {
+        return { adapter: new ollama_1.OllamaAdapter(baseUrl), model, baseUrl, provider };
+    }
+    return null;
+}
+function resolveEmbeddingAdapter(llm) {
+    const provider = llm?.embeddingProvider ?? (0, llm_env_1.getEnvOptions)().embedding.provider;
+    const model = llm?.embeddingModel ?? (0, llm_env_1.getEnvOptions)().embedding.model;
+    const baseUrl = llm?.embeddingBaseUrl ?? (0, llm_env_1.getEnvOptions)().embedding.baseUrl;
+    if (provider === 'ollama') {
+        return { adapter: new ollama_1.OllamaAdapter(baseUrl), model, provider };
+    }
+    return null;
+}
+// ─── Route Handlers ─────────────────────────────────────────────────────────
+async function handleCreateThread(req, res, entityId) {
+    const ctx = req.constructive;
+    if (!ctx?.userId) {
+        res.status(401).json({ error: 'Authentication required' });
+        return;
+    }
+    const agentChat = await ctx.useModule('agentChat');
+    if (!agentChat?.threadTableName) {
+        res.status(404).json({ error: 'Agent module not provisioned for this database' });
+        return;
+    }
+    const body = req.body || {};
+    const { schemaName, threadTableName } = agentChat;
+    const result = await ctx.withPgClient(async (client) => {
+        const { rows } = await client.query(`INSERT INTO "${schemaName}"."${threadTableName}"
+       (entity_id, owner_id, mode, model, system_prompt, title)
+       VALUES ($1, $2, $3, $4, $5, $6)
+       RETURNING id, mode, model, system_prompt, status, created_at`, [
+            entityId,
+            ctx.userId,
+            body.mode ?? 'ask',
+            body.model ?? null,
+            body.system_prompt ?? null,
+            body.title ?? null
+        ]);
+        return rows[0];
+    });
+    res.status(201).json({
+        id: result.id,
+        mode: result.mode,
+        model: result.model,
+        system_prompt: result.system_prompt,
+        status: result.status,
+        created_at: result.created_at
+    });
+}
+async function handleSendMessage(req, res, entityId) {
+    const ctx = req.constructive;
+    if (!ctx?.userId) {
+        res.status(401).json({ error: 'Authentication required' });
+        return;
+    }
+    const agentChat = await ctx.useModule('agentChat');
+    if (!agentChat?.threadTableName || !agentChat?.messageTableName) {
+        res.status(404).json({ error: 'Agent module not provisioned for this database' });
+        return;
+    }
+    const body = req.body || {};
+    if (!body.messages?.length) {
+        res.status(400).json({ error: 'messages[] is required and must not be empty' });
+        return;
+    }
+    const { schemaName, threadTableName, messageTableName } = agentChat;
+    const threadId = req.params.thread_id;
+    const userId = ctx.userId;
+    // Verify thread exists (RLS enforced)
+    const threadRow = await ctx.withPgClient(async (client) => {
+        const { rows } = await client.query(`SELECT id, mode, model, system_prompt, status
+       FROM "${schemaName}"."${threadTableName}"
+       WHERE id = $1`, [threadId]);
+        return rows[0];
+    });
+    if (!threadRow) {
+        res.status(404).json({ error: 'Thread not found' });
+        return;
+    }
+    // Resolve shared billing client and LLM config (lazy, cached per request)
+    const [billing, llm] = await Promise.all([ctx.useBilling(), ctx.useLlm()]);
+    const chatAdapter = resolveChatAdapter(llm);
+    if (!chatAdapter) {
+        res.status(503).json({ error: 'No LLM provider configured' });
+        return;
+    }
+    const model = body.model ?? threadRow.model ?? chatAdapter.model;
+    const meterSlug = model;
+    // Quota check
+    if (billing) {
+        const allowed = await billing.checkQuota(meterSlug);
+        if (!allowed) {
+            res.status(429).json({
+                error: 'Token quota exceeded',
+                meter: meterSlug,
+                entity_id: entityId
+            });
+            return;
+        }
+    }
+    // Persist user messages
+    await ctx.withPgClient(async (client) => {
+        for (const msg of body.messages) {
+            if (msg.role === 'user') {
+                await client.query(`INSERT INTO "${schemaName}"."${messageTableName}"
+           (thread_id, owner_id, entity_id, author_role, parts)
+           VALUES ($1, $2, (SELECT entity_id FROM "${schemaName}"."${threadTableName}" WHERE id = $1), $3, $4)`, [threadId, userId, 'user', JSON.stringify([{ type: 'text', text: msg.content }])]);
+            }
+        }
+    });
+    // Load full thread history
+    const history = await ctx.withPgClient(async (client) => {
+        const { rows } = await client.query(`SELECT author_role, parts, created_at
+       FROM "${schemaName}"."${messageTableName}"
+       WHERE thread_id = $1
+       ORDER BY created_at ASC`, [threadId]);
+        return rows;
+    });
+    const llmMessages = [];
+    if (threadRow.system_prompt) {
+        llmMessages.push({ role: 'system', content: threadRow.system_prompt });
+    }
+    for (const row of history) {
+        const parts = Array.isArray(row.parts) ? row.parts : [];
+        const textContent = parts
+            .filter((p) => p.type === 'text')
+            .map((p) => p.text)
+            .join('');
+        if (textContent) {
+            llmMessages.push({
+                role: row.author_role === 'user' ? 'user' : 'assistant',
+                content: textContent
+            });
+        }
+    }
+    const startTime = Date.now();
+    const shouldStream = body.stream !== false;
+    if (shouldStream) {
+        await handleStreamingResponse(req, res, {
+            ctx, chatAdapter, model, llmMessages, body,
+            entityId, userId, threadId,
+            schemaName, threadTableName, messageTableName,
+            billing, startTime, meterSlug
+        });
+    }
+    else {
+        await handleBatchResponse(req, res, {
+            ctx, chatAdapter, model, llmMessages, body,
+            entityId, userId, threadId,
+            schemaName, threadTableName, messageTableName,
+            billing, startTime, meterSlug
+        });
+    }
+}
+async function handleStreamingResponse(_req, res, mc) {
+    const { ctx, chatAdapter, model, llmMessages, body, entityId, userId, threadId, schemaName, threadTableName, messageTableName, billing, startTime, meterSlug } = mc;
+    res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        Connection: 'keep-alive',
+        'X-Accel-Buffering': 'no'
+    });
+    const messageId = `msg_${Date.now()}`;
+    try {
+        const systemMsg = llmMessages.find(m => m.role === 'system');
+        const nonSystem = llmMessages.filter(m => m.role !== 'system');
+        const modelDesc = chatAdapter.adapter.createModel(model, { maxOutputTokens: undefined });
+        const context = {
+            systemPrompt: systemMsg?.content,
+            messages: nonSystem.map((m) => ({
+                role: m.role,
+                content: m.content,
+                timestamp: Date.now()
+            }))
+        };
+        const stream = chatAdapter.adapter.stream(modelDesc, context, {
+            temperature: body.temperature
+        });
+        let streamedContent = '';
+        for await (const event of stream) {
+            if (event.type === 'text_delta') {
+                streamedContent += event.delta;
+                const sseEvent = {
+                    id: messageId,
+                    choices: [{
+                            index: 0,
+                            delta: { content: event.delta, role: 'assistant' },
+                            finish_reason: null
+                        }],
+                    model
+                };
+                res.write(`data: ${JSON.stringify(sseEvent)}\n\n`);
+            }
+        }
+        const result = await stream.result();
+        const content = streamedContent;
+        const latencyMs = Date.now() - startTime;
+        const usage = {
+            input: result.usage.input,
+            output: result.usage.output,
+            reasoning: result.usage.reasoning,
+            cacheRead: result.usage.cacheRead,
+            cacheWrite: result.usage.cacheWrite,
+            totalTokens: result.usage.totalTokens
+        };
+        res.write('data: [DONE]\n\n');
+        res.end();
+        // Persist assistant message (fire-and-forget)
+        if (content) {
+            ctx.withPgClient(async (client) => {
+                await client.query(`INSERT INTO "${schemaName}"."${messageTableName}"
+           (thread_id, owner_id, entity_id, author_role, parts, model)
+           VALUES ($1, $2, (SELECT entity_id FROM "${schemaName}"."${threadTableName}" WHERE id = $1), $3, $4, $5)`, [threadId, userId, 'assistant', JSON.stringify([{ type: 'text', text: content }]), model]);
+            }).catch((err) => log.error('Failed to persist assistant message:', err));
+        }
+        // Record billing usage + inference log (fire-and-forget)
+        if (billing && usage.totalTokens > 0) {
+            billing.recordUsage(meterSlug, usage.totalTokens, {
+                input_tokens: usage.input,
+                output_tokens: usage.output,
+                cache_read_tokens: usage.cacheRead,
+                cache_write_tokens: usage.cacheWrite,
+                model,
+                latency_ms: latencyMs,
+                stream: true
+            }).catch(() => { });
+            billing.logInference({
+                entityId, actorId: userId, model, provider: chatAdapter.provider,
+                service: 'llm', operation: 'chat',
+                inputTokens: usage.input, outputTokens: usage.output,
+                totalTokens: usage.totalTokens, latencyMs, status: 'ok'
+            }).catch(() => { });
+        }
+    }
+    catch (streamErr) {
+        log.error('Streaming error:', streamErr);
+        const errorEvent = { error: { message: streamErr.message, type: 'stream_error' } };
+        res.write(`data: ${JSON.stringify(errorEvent)}\n\n`);
+        res.write('data: [DONE]\n\n');
+        res.end();
+    }
+}
+async function handleBatchResponse(_req, res, mc) {
+    const { ctx, chatAdapter, model, llmMessages, body, entityId, userId, threadId, schemaName, threadTableName, messageTableName, billing, startTime, meterSlug } = mc;
+    const systemMsg = llmMessages.find(m => m.role === 'system');
+    const nonSystem = llmMessages.filter(m => m.role !== 'system');
+    const modelDesc = chatAdapter.adapter.createModel(model, { maxOutputTokens: undefined });
+    const context = {
+        systemPrompt: systemMsg?.content,
+        messages: nonSystem.map((m) => ({
+            role: m.role,
+            content: m.content,
+            timestamp: Date.now()
+        }))
+    };
+    const stream = chatAdapter.adapter.stream(modelDesc, context, {
+        temperature: body.temperature
+    });
+    const result = await stream.result();
+    const content = result.content
+        .filter((block) => block.type === 'text')
+        .map((block) => block.text)
+        .join('');
+    const latencyMs = Date.now() - startTime;
+    const usage = {
+        input: result.usage.input,
+        output: result.usage.output,
+        reasoning: result.usage.reasoning,
+        cacheRead: result.usage.cacheRead,
+        cacheWrite: result.usage.cacheWrite,
+        totalTokens: result.usage.totalTokens
+    };
+    // Persist assistant message
+    await ctx.withPgClient(async (client) => {
+        await client.query(`INSERT INTO "${schemaName}"."${messageTableName}"
+       (thread_id, owner_id, entity_id, author_role, parts, model)
+       VALUES ($1, $2, (SELECT entity_id FROM "${schemaName}"."${threadTableName}" WHERE id = $1), $3, $4, $5)`, [threadId, userId, 'assistant', JSON.stringify([{ type: 'text', text: content }]), model]);
+    });
+    // Record billing + inference log (fire-and-forget)
+    if (billing && usage.totalTokens > 0) {
+        billing.recordUsage(meterSlug, usage.totalTokens, {
+            input_tokens: usage.input,
+            output_tokens: usage.output,
+            cache_read_tokens: usage.cacheRead,
+            cache_write_tokens: usage.cacheWrite,
+            model,
+            latency_ms: latencyMs,
+            stream: false
+        }).catch(() => { });
+        billing.logInference({
+            entityId, actorId: userId, model, provider: chatAdapter.provider,
+            service: 'llm', operation: 'chat',
+            inputTokens: usage.input, outputTokens: usage.output,
+            totalTokens: usage.totalTokens, latencyMs, status: 'ok'
+        }).catch(() => { });
+    }
+    res.json({
+        id: `msg_${Date.now()}`,
+        choices: [{
+                index: 0,
+                message: { role: 'assistant', content },
+                finish_reason: 'stop'
+            }],
+        model,
+        usage: {
+            prompt_tokens: usage.input,
+            completion_tokens: usage.output,
+            total_tokens: usage.totalTokens
+        }
+    });
+}
+// ─── Embedding Handler ──────────────────────────────────────────────────────
+async function handleEmbed(req, res) {
+    const ctx = req.constructive;
+    if (!ctx?.userId) {
+        res.status(401).json({ error: 'Authentication required' });
+        return;
+    }
+    const body = req.body || {};
+    if (!body.input) {
+        res.status(400).json({ error: 'input is required' });
+        return;
+    }
+    const llm = await ctx.useLlm();
+    const embedAdapter = resolveEmbeddingAdapter(llm);
+    if (!embedAdapter) {
+        res.status(503).json({ error: 'No embedding provider configured' });
+        return;
+    }
+    const model = body.model ?? embedAdapter.model;
+    const inputs = Array.isArray(body.input) ? body.input : [body.input];
+    // Resolve shared billing client
+    const billing = await ctx.useBilling();
+    // Quota check
+    if (billing) {
+        const allowed = await billing.checkQuota(model);
+        if (!allowed) {
+            res.status(429).json({ error: 'Embedding quota exceeded', meter: model });
+            return;
+        }
+    }
+    const startTime = Date.now();
+    try {
+        const results = await Promise.all(inputs.map((text) => embedAdapter.adapter.embed(text, model)));
+        const latencyMs = Date.now() - startTime;
+        const totalTokens = results.reduce((sum, r) => sum + r.promptTokens, 0);
+        // Record usage + inference log (fire-and-forget)
+        if (billing && totalTokens > 0) {
+            billing.recordUsage(model, totalTokens, {
+                input_tokens: totalTokens,
+                model,
+                latency_ms: latencyMs,
+                batch_size: inputs.length
+            }).catch(() => { });
+            billing.logInference({
+                entityId: ctx.userId,
+                actorId: ctx.userId,
+                model,
+                provider: embedAdapter.provider,
+                service: 'embedding',
+                operation: 'embed',
+                inputTokens: totalTokens,
+                outputTokens: 0,
+                totalTokens,
+                latencyMs,
+                status: 'ok'
+            }).catch(() => { });
+        }
+        res.json({
+            object: 'list',
+            data: results.map((r, i) => ({
+                object: 'embedding',
+                index: i,
+                embedding: r.embedding
+            })),
+            model,
+            usage: {
+                prompt_tokens: totalTokens,
+                total_tokens: totalTokens
+            }
+        });
+    }
+    catch (err) {
+        log.error('Embedding error:', err);
+        res.status(500).json({ error: err.message ?? 'Embedding failed' });
+    }
+}
+// ─── Router Factory ─────────────────────────────────────────────────────────
+function createAgenticRouter() {
+    const router = (0, express_1.Router)();
+    router.use(express_1.default.json());
+    // Entity-scoped routes
+    router.post('/v1/orgs/:entity_id/threads', async (req, res) => {
+        try {
+            await handleCreateThread(req, res, req.params.entity_id);
+        }
+        catch (err) {
+            log.error('Error creating thread:', err);
+            if (!res.headersSent)
+                res.status(500).json({ error: 'Internal server error' });
+        }
+    });
+    router.post('/v1/orgs/:entity_id/threads/:thread_id/messages', async (req, res) => {
+        try {
+            await handleSendMessage(req, res, req.params.entity_id);
+        }
+        catch (err) {
+            log.error('Error in messages endpoint:', err);
+            if (!res.headersSent)
+                res.status(500).json({ error: 'Internal server error' });
+        }
+    });
+    // Global routes (entity_id = user_id from JWT)
+    router.post('/v1/threads', async (req, res) => {
+        try {
+            const userId = req.constructive?.userId;
+            if (!userId) {
+                res.status(401).json({ error: 'Authentication required' });
+                return;
+            }
+            await handleCreateThread(req, res, userId);
+        }
+        catch (err) {
+            log.error('Error creating thread:', err);
+            if (!res.headersSent)
+                res.status(500).json({ error: 'Internal server error' });
+        }
+    });
+    router.post('/v1/threads/:thread_id/messages', async (req, res) => {
+        try {
+            const userId = req.constructive?.userId;
+            if (!userId) {
+                res.status(401).json({ error: 'Authentication required' });
+                return;
+            }
+            await handleSendMessage(req, res, userId);
+        }
+        catch (err) {
+            log.error('Error in messages endpoint:', err);
+            if (!res.headersSent)
+                res.status(500).json({ error: 'Internal server error' });
+        }
+    });
+    // Embedding endpoint
+    router.post('/v1/embed', async (req, res) => {
+        try {
+            await handleEmbed(req, res);
+        }
+        catch (err) {
+            log.error('Error in embed endpoint:', err);
+            if (!res.headersSent)
+                res.status(500).json({ error: 'Internal server error' });
+        }
+    });
+    return router;
+}

package/esm/agentic/index.js

@@ -0,0 +1,23 @@
+/**
+ * Agent threads REST API — server-internal Express router
+ *
+ * Stateful agent-thread service (chat streaming, billing metering, inference
+ * logging) mounted by the GraphQL server. Uses @constructive-io/express-context
+ * for tenant-scoped database access.
+ *
+ * LLM provider config is resolved per-database via `ctx.useLlm()` (from the
+ * llm_module table), falling back to env vars from @constructive-io/llm-env when the module
+ * is not provisioned. Discovery and billing are handled by the shared loaders
+ * in express-context — no custom caching here.
+ *
+ * @example
+ * ```typescript
+ * import { createContextMiddleware } from '@constructive-io/express-context';
+ * import { createAgenticRouter } from './agentic';
+ *
+ * app.use(createContextMiddleware());
+ * app.use(createAgenticRouter());
+ * ```
+ */
+export { createAgenticRouter } from './router';
+export { getEnvOptions as getLlmEnvOptions, getEnvVars as getLlmEnvVars, llmDefaults } from '@constructive-io/llm-env';

package/esm/agentic/router.js

@@ -0,0 +1,486 @@
+/**
+ * router — Express router for the agentic-server
+ *
+ * Provides REST endpoints for AI agent conversations:
+ *
+ *   POST /v1/threads                             → create thread
+ *   POST /v1/threads/:thread_id/messages         → send message + stream response
+ *   POST /v1/orgs/:entity_id/threads             → create thread (entity-scoped)
+ *   POST /v1/orgs/:entity_id/threads/:thread_id/messages → send message (entity-scoped)
+ *   POST /v1/embed                               → generate embedding
+ *
+ * All routes require `req.constructive` (from @constructive-io/express-context).
+ * Billing (check_quota + record_usage) and inference logging are automatic
+ * when the billing/inference_log modules are provisioned.
+ *
+ * LLM provider config is resolved per-database via `ctx.useLlm()` from the
+ * llm_module table, falling back to env vars (EMBEDDER_*, CHAT_*) when the
+ * module is not provisioned.
+ */
+import { OllamaAdapter } from '@agentic-kit/ollama';
+import { getEnvOptions as getLlmEnvOptions } from '@constructive-io/llm-env';
+import { Logger } from '@pgpmjs/logger';
+import express, { Router } from 'express';
+const log = new Logger('agentic-server');
+function resolveChatAdapter(llm) {
+    const provider = llm?.chatProvider ?? getLlmEnvOptions().chat.provider;
+    const model = llm?.chatModel ?? getLlmEnvOptions().chat.model;
+    const baseUrl = llm?.chatBaseUrl ?? getLlmEnvOptions().chat.baseUrl;
+    if (provider === 'ollama') {
+        return { adapter: new OllamaAdapter(baseUrl), model, baseUrl, provider };
+    }
+    return null;
+}
+function resolveEmbeddingAdapter(llm) {
+    const provider = llm?.embeddingProvider ?? getLlmEnvOptions().embedding.provider;
+    const model = llm?.embeddingModel ?? getLlmEnvOptions().embedding.model;
+    const baseUrl = llm?.embeddingBaseUrl ?? getLlmEnvOptions().embedding.baseUrl;
+    if (provider === 'ollama') {
+        return { adapter: new OllamaAdapter(baseUrl), model, provider };
+    }
+    return null;
+}
+// ─── Route Handlers ─────────────────────────────────────────────────────────
+async function handleCreateThread(req, res, entityId) {
+    const ctx = req.constructive;
+    if (!ctx?.userId) {
+        res.status(401).json({ error: 'Authentication required' });
+        return;
+    }
+    const agentChat = await ctx.useModule('agentChat');
+    if (!agentChat?.threadTableName) {
+        res.status(404).json({ error: 'Agent module not provisioned for this database' });
+        return;
+    }
+    const body = req.body || {};
+    const { schemaName, threadTableName } = agentChat;
+    const result = await ctx.withPgClient(async (client) => {
+        const { rows } = await client.query(`INSERT INTO "${schemaName}"."${threadTableName}"
+       (entity_id, owner_id, mode, model, system_prompt, title)
+       VALUES ($1, $2, $3, $4, $5, $6)
+       RETURNING id, mode, model, system_prompt, status, created_at`, [
+            entityId,
+            ctx.userId,
+            body.mode ?? 'ask',
+            body.model ?? null,
+            body.system_prompt ?? null,
+            body.title ?? null
+        ]);
+        return rows[0];
+    });
+    res.status(201).json({
+        id: result.id,
+        mode: result.mode,
+        model: result.model,
+        system_prompt: result.system_prompt,
+        status: result.status,
+        created_at: result.created_at
+    });
+}
+async function handleSendMessage(req, res, entityId) {
+    const ctx = req.constructive;
+    if (!ctx?.userId) {
+        res.status(401).json({ error: 'Authentication required' });
+        return;
+    }
+    const agentChat = await ctx.useModule('agentChat');
+    if (!agentChat?.threadTableName || !agentChat?.messageTableName) {
+        res.status(404).json({ error: 'Agent module not provisioned for this database' });
+        return;
+    }
+    const body = req.body || {};
+    if (!body.messages?.length) {
+        res.status(400).json({ error: 'messages[] is required and must not be empty' });
+        return;
+    }
+    const { schemaName, threadTableName, messageTableName } = agentChat;
+    const threadId = req.params.thread_id;
+    const userId = ctx.userId;
+    // Verify thread exists (RLS enforced)
+    const threadRow = await ctx.withPgClient(async (client) => {
+        const { rows } = await client.query(`SELECT id, mode, model, system_prompt, status
+       FROM "${schemaName}"."${threadTableName}"
+       WHERE id = $1`, [threadId]);
+        return rows[0];
+    });
+    if (!threadRow) {
+        res.status(404).json({ error: 'Thread not found' });
+        return;
+    }
+    // Resolve shared billing client and LLM config (lazy, cached per request)
+    const [billing, llm] = await Promise.all([ctx.useBilling(), ctx.useLlm()]);
+    const chatAdapter = resolveChatAdapter(llm);
+    if (!chatAdapter) {
+        res.status(503).json({ error: 'No LLM provider configured' });
+        return;
+    }
+    const model = body.model ?? threadRow.model ?? chatAdapter.model;
+    const meterSlug = model;
+    // Quota check
+    if (billing) {
+        const allowed = await billing.checkQuota(meterSlug);
+        if (!allowed) {
+            res.status(429).json({
+                error: 'Token quota exceeded',
+                meter: meterSlug,
+                entity_id: entityId
+            });
+            return;
+        }
+    }
+    // Persist user messages
+    await ctx.withPgClient(async (client) => {
+        for (const msg of body.messages) {
+            if (msg.role === 'user') {
+                await client.query(`INSERT INTO "${schemaName}"."${messageTableName}"
+           (thread_id, owner_id, entity_id, author_role, parts)
+           VALUES ($1, $2, (SELECT entity_id FROM "${schemaName}"."${threadTableName}" WHERE id = $1), $3, $4)`, [threadId, userId, 'user', JSON.stringify([{ type: 'text', text: msg.content }])]);
+            }
+        }
+    });
+    // Load full thread history
+    const history = await ctx.withPgClient(async (client) => {
+        const { rows } = await client.query(`SELECT author_role, parts, created_at
+       FROM "${schemaName}"."${messageTableName}"
+       WHERE thread_id = $1
+       ORDER BY created_at ASC`, [threadId]);
+        return rows;
+    });
+    const llmMessages = [];
+    if (threadRow.system_prompt) {
+        llmMessages.push({ role: 'system', content: threadRow.system_prompt });
+    }
+    for (const row of history) {
+        const parts = Array.isArray(row.parts) ? row.parts : [];
+        const textContent = parts
+            .filter((p) => p.type === 'text')
+            .map((p) => p.text)
+            .join('');
+        if (textContent) {
+            llmMessages.push({
+                role: row.author_role === 'user' ? 'user' : 'assistant',
+                content: textContent
+            });
+        }
+    }
+    const startTime = Date.now();
+    const shouldStream = body.stream !== false;
+    if (shouldStream) {
+        await handleStreamingResponse(req, res, {
+            ctx, chatAdapter, model, llmMessages, body,
+            entityId, userId, threadId,
+            schemaName, threadTableName, messageTableName,
+            billing, startTime, meterSlug
+        });
+    }
+    else {
+        await handleBatchResponse(req, res, {
+            ctx, chatAdapter, model, llmMessages, body,
+            entityId, userId, threadId,
+            schemaName, threadTableName, messageTableName,
+            billing, startTime, meterSlug
+        });
+    }
+}
+async function handleStreamingResponse(_req, res, mc) {
+    const { ctx, chatAdapter, model, llmMessages, body, entityId, userId, threadId, schemaName, threadTableName, messageTableName, billing, startTime, meterSlug } = mc;
+    res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        Connection: 'keep-alive',
+        'X-Accel-Buffering': 'no'
+    });
+    const messageId = `msg_${Date.now()}`;
+    try {
+        const systemMsg = llmMessages.find(m => m.role === 'system');
+        const nonSystem = llmMessages.filter(m => m.role !== 'system');
+        const modelDesc = chatAdapter.adapter.createModel(model, { maxOutputTokens: undefined });
+        const context = {
+            systemPrompt: systemMsg?.content,
+            messages: nonSystem.map((m) => ({
+                role: m.role,
+                content: m.content,
+                timestamp: Date.now()
+            }))
+        };
+        const stream = chatAdapter.adapter.stream(modelDesc, context, {
+            temperature: body.temperature
+        });
+        let streamedContent = '';
+        for await (const event of stream) {
+            if (event.type === 'text_delta') {
+                streamedContent += event.delta;
+                const sseEvent = {
+                    id: messageId,
+                    choices: [{
+                            index: 0,
+                            delta: { content: event.delta, role: 'assistant' },
+                            finish_reason: null
+                        }],
+                    model
+                };
+                res.write(`data: ${JSON.stringify(sseEvent)}\n\n`);
+            }
+        }
+        const result = await stream.result();
+        const content = streamedContent;
+        const latencyMs = Date.now() - startTime;
+        const usage = {
+            input: result.usage.input,
+            output: result.usage.output,
+            reasoning: result.usage.reasoning,
+            cacheRead: result.usage.cacheRead,
+            cacheWrite: result.usage.cacheWrite,
+            totalTokens: result.usage.totalTokens
+        };
+        res.write('data: [DONE]\n\n');
+        res.end();
+        // Persist assistant message (fire-and-forget)
+        if (content) {
+            ctx.withPgClient(async (client) => {
+                await client.query(`INSERT INTO "${schemaName}"."${messageTableName}"
+           (thread_id, owner_id, entity_id, author_role, parts, model)
+           VALUES ($1, $2, (SELECT entity_id FROM "${schemaName}"."${threadTableName}" WHERE id = $1), $3, $4, $5)`, [threadId, userId, 'assistant', JSON.stringify([{ type: 'text', text: content }]), model]);
+            }).catch((err) => log.error('Failed to persist assistant message:', err));
+        }
+        // Record billing usage + inference log (fire-and-forget)
+        if (billing && usage.totalTokens > 0) {
+            billing.recordUsage(meterSlug, usage.totalTokens, {
+                input_tokens: usage.input,
+                output_tokens: usage.output,
+                cache_read_tokens: usage.cacheRead,
+                cache_write_tokens: usage.cacheWrite,
+                model,
+                latency_ms: latencyMs,
+                stream: true
+            }).catch(() => { });
+            billing.logInference({
+                entityId, actorId: userId, model, provider: chatAdapter.provider,
+                service: 'llm', operation: 'chat',
+                inputTokens: usage.input, outputTokens: usage.output,
+                totalTokens: usage.totalTokens, latencyMs, status: 'ok'
+            }).catch(() => { });
+        }
+    }
+    catch (streamErr) {
+        log.error('Streaming error:', streamErr);
+        const errorEvent = { error: { message: streamErr.message, type: 'stream_error' } };
+        res.write(`data: ${JSON.stringify(errorEvent)}\n\n`);
+        res.write('data: [DONE]\n\n');
+        res.end();
+    }
+}
+async function handleBatchResponse(_req, res, mc) {
+    const { ctx, chatAdapter, model, llmMessages, body, entityId, userId, threadId, schemaName, threadTableName, messageTableName, billing, startTime, meterSlug } = mc;
+    const systemMsg = llmMessages.find(m => m.role === 'system');
+    const nonSystem = llmMessages.filter(m => m.role !== 'system');
+    const modelDesc = chatAdapter.adapter.createModel(model, { maxOutputTokens: undefined });
+    const context = {
+        systemPrompt: systemMsg?.content,
+        messages: nonSystem.map((m) => ({
+            role: m.role,
+            content: m.content,
+            timestamp: Date.now()
+        }))
+    };
+    const stream = chatAdapter.adapter.stream(modelDesc, context, {
+        temperature: body.temperature
+    });
+    const result = await stream.result();
+    const content = result.content
+        .filter((block) => block.type === 'text')
+        .map((block) => block.text)
+        .join('');
+    const latencyMs = Date.now() - startTime;
+    const usage = {
+        input: result.usage.input,
+        output: result.usage.output,
+        reasoning: result.usage.reasoning,
+        cacheRead: result.usage.cacheRead,
+        cacheWrite: result.usage.cacheWrite,
+        totalTokens: result.usage.totalTokens
+    };
+    // Persist assistant message
+    await ctx.withPgClient(async (client) => {
+        await client.query(`INSERT INTO "${schemaName}"."${messageTableName}"
+       (thread_id, owner_id, entity_id, author_role, parts, model)
+       VALUES ($1, $2, (SELECT entity_id FROM "${schemaName}"."${threadTableName}" WHERE id = $1), $3, $4, $5)`, [threadId, userId, 'assistant', JSON.stringify([{ type: 'text', text: content }]), model]);
+    });
+    // Record billing + inference log (fire-and-forget)
+    if (billing && usage.totalTokens > 0) {
+        billing.recordUsage(meterSlug, usage.totalTokens, {
+            input_tokens: usage.input,
+            output_tokens: usage.output,
+            cache_read_tokens: usage.cacheRead,
+            cache_write_tokens: usage.cacheWrite,
+            model,
+            latency_ms: latencyMs,
+            stream: false
+        }).catch(() => { });
+        billing.logInference({
+            entityId, actorId: userId, model, provider: chatAdapter.provider,
+            service: 'llm', operation: 'chat',
+            inputTokens: usage.input, outputTokens: usage.output,
+            totalTokens: usage.totalTokens, latencyMs, status: 'ok'
+        }).catch(() => { });
+    }
+    res.json({
+        id: `msg_${Date.now()}`,
+        choices: [{
+                index: 0,
+                message: { role: 'assistant', content },
+                finish_reason: 'stop'
+            }],
+        model,
+        usage: {
+            prompt_tokens: usage.input,
+            completion_tokens: usage.output,
+            total_tokens: usage.totalTokens
+        }
+    });
+}
+// ─── Embedding Handler ──────────────────────────────────────────────────────
+async function handleEmbed(req, res) {
+    const ctx = req.constructive;
+    if (!ctx?.userId) {
+        res.status(401).json({ error: 'Authentication required' });
+        return;
+    }
+    const body = req.body || {};
+    if (!body.input) {
+        res.status(400).json({ error: 'input is required' });
+        return;
+    }
+    const llm = await ctx.useLlm();
+    const embedAdapter = resolveEmbeddingAdapter(llm);
+    if (!embedAdapter) {
+        res.status(503).json({ error: 'No embedding provider configured' });
+        return;
+    }
+    const model = body.model ?? embedAdapter.model;
+    const inputs = Array.isArray(body.input) ? body.input : [body.input];
+    // Resolve shared billing client
+    const billing = await ctx.useBilling();
+    // Quota check
+    if (billing) {
+        const allowed = await billing.checkQuota(model);
+        if (!allowed) {
+            res.status(429).json({ error: 'Embedding quota exceeded', meter: model });
+            return;
+        }
+    }
+    const startTime = Date.now();
+    try {
+        const results = await Promise.all(inputs.map((text) => embedAdapter.adapter.embed(text, model)));
+        const latencyMs = Date.now() - startTime;
+        const totalTokens = results.reduce((sum, r) => sum + r.promptTokens, 0);
+        // Record usage + inference log (fire-and-forget)
+        if (billing && totalTokens > 0) {
+            billing.recordUsage(model, totalTokens, {
+                input_tokens: totalTokens,
+                model,
+                latency_ms: latencyMs,
+                batch_size: inputs.length
+            }).catch(() => { });
+            billing.logInference({
+                entityId: ctx.userId,
+                actorId: ctx.userId,
+                model,
+                provider: embedAdapter.provider,
+                service: 'embedding',
+                operation: 'embed',
+                inputTokens: totalTokens,
+                outputTokens: 0,
+                totalTokens,
+                latencyMs,
+                status: 'ok'
+            }).catch(() => { });
+        }
+        res.json({
+            object: 'list',
+            data: results.map((r, i) => ({
+                object: 'embedding',
+                index: i,
+                embedding: r.embedding
+            })),
+            model,
+            usage: {
+                prompt_tokens: totalTokens,
+                total_tokens: totalTokens
+            }
+        });
+    }
+    catch (err) {
+        log.error('Embedding error:', err);
+        res.status(500).json({ error: err.message ?? 'Embedding failed' });
+    }
+}
+// ─── Router Factory ─────────────────────────────────────────────────────────
+export function createAgenticRouter() {
+    const router = Router();
+    router.use(express.json());
+    // Entity-scoped routes
+    router.post('/v1/orgs/:entity_id/threads', async (req, res) => {
+        try {
+            await handleCreateThread(req, res, req.params.entity_id);
+        }
+        catch (err) {
+            log.error('Error creating thread:', err);
+            if (!res.headersSent)
+                res.status(500).json({ error: 'Internal server error' });
+        }
+    });
+    router.post('/v1/orgs/:entity_id/threads/:thread_id/messages', async (req, res) => {
+        try {
+            await handleSendMessage(req, res, req.params.entity_id);
+        }
+        catch (err) {
+            log.error('Error in messages endpoint:', err);
+            if (!res.headersSent)
+                res.status(500).json({ error: 'Internal server error' });
+        }
+    });
+    // Global routes (entity_id = user_id from JWT)
+    router.post('/v1/threads', async (req, res) => {
+        try {
+            const userId = req.constructive?.userId;
+            if (!userId) {
+                res.status(401).json({ error: 'Authentication required' });
+                return;
+            }
+            await handleCreateThread(req, res, userId);
+        }
+        catch (err) {
+            log.error('Error creating thread:', err);
+            if (!res.headersSent)
+                res.status(500).json({ error: 'Internal server error' });
+        }
+    });
+    router.post('/v1/threads/:thread_id/messages', async (req, res) => {
+        try {
+            const userId = req.constructive?.userId;
+            if (!userId) {
+                res.status(401).json({ error: 'Authentication required' });
+                return;
+            }
+            await handleSendMessage(req, res, userId);
+        }
+        catch (err) {
+            log.error('Error in messages endpoint:', err);
+            if (!res.headersSent)
+                res.status(500).json({ error: 'Internal server error' });
+        }
+    });
+    // Embedding endpoint
+    router.post('/v1/embed', async (req, res) => {
+        try {
+            await handleEmbed(req, res);
+        }
+        catch (err) {
+            log.error('Error in embed endpoint:', err);
+            if (!res.headersSent)
+                res.status(500).json({ error: 'Internal server error' });
+        }
+    });
+    return router;
+}

package/esm/server.js

@@ -4,13 +4,13 @@ import { getEnvOptions } from '@constructive-io/graphql-env';
 import { middleware as parseDomains } from '@constructive-io/url-domains';
 import { Logger } from '@pgpmjs/logger';
 import { healthz, poweredBy, svcCache, trustProxy } from '@pgpmjs/server-utils';
-import { createAgenticRouter } from 'agentic-server';
 import cookieParser from 'cookie-parser';
 import express from 'express';
 import { closeAllCaches, graphileCache } from 'graphile-cache';
 import graphqlUpload from 'graphql-upload';
 import { getPgPool } from 'pg-cache';
 import requestIp from 'request-ip';
+import { createAgenticRouter } from './agentic';
 import { closeDebugDatabasePools } from './diagnostics/debug-db-snapshot';
 import { startDebugSampler } from './diagnostics/debug-sampler';
 import { isDevelopmentObservabilityMode, isGraphqlObservabilityEnabled, isGraphqlObservabilityRequested, isLoopbackHost } from './diagnostics/observability';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/graphql-server",
-  "version": "5.14.6",
+  "version": "5.15.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "Constructive GraphQL Server",
   "main": "index.js",
@@ -41,11 +41,13 @@
     "backend"
   ],
   "dependencies": {
+    "@agentic-kit/ollama": "2.12.2",
     "@constructive-io/csrf": "^0.26.2",
     "@constructive-io/errors": "^0.8.2",
     "@constructive-io/express-context": "^0.23.2",
     "@constructive-io/graphql-env": "^3.28.2",
     "@constructive-io/graphql-types": "^3.27.2",
+    "@constructive-io/llm-env": "^0.12.2",
     "@constructive-io/query-builder": "^3.9.4",
     "@constructive-io/s3-utils": "^2.29.2",
     "@constructive-io/url-domains": "^2.28.2",
@@ -54,7 +56,6 @@
     "@pgpmjs/logger": "^2.23.2",
     "@pgpmjs/server-utils": "^3.24.2",
     "@pgpmjs/types": "^2.49.2",
-    "agentic-server": "0.21.2",
     "cors": "^2.8.6",
     "deepmerge": "^4.3.1",
     "express": "^5.2.1",
@@ -65,8 +66,8 @@
     "graphile-build-pg": "5.0.2",
     "graphile-cache": "^4.9.2",
     "graphile-config": "1.0.1",
-    "graphile-function-bindings": "^1.10.6",
-    "graphile-settings": "^6.11.6",
+    "graphile-function-bindings": "^1.10.7",
+    "graphile-settings": "^6.11.7",
     "graphile-utils": "5.0.1",
     "graphql": "16.13.0",
     "graphql-upload": "^13.0.0",
@@ -87,11 +88,13 @@
     "@types/graphql-upload": "^8.0.12",
     "@types/pg": "^8.20.0",
     "@types/request-ip": "^0.0.41",
+    "@types/supertest": "^7.2.0",
     "cookie-parser": "^1.4.7",
-    "graphile-test": "5.10.6",
+    "graphile-test": "5.10.7",
     "makage": "^0.3.0",
     "nodemon": "^3.1.14",
+    "supertest": "^7.2.2",
     "ts-node": "^10.9.2"
   },
-  "gitHead": "45cd961cf956d2d28e4d09b20db4204982c33593"
+  "gitHead": "6d3e25dc5c9f93421dba49ddedf93239f87213a8"
 }

package/server.js

@@ -10,13 +10,13 @@ const graphql_env_1 = require("@constructive-io/graphql-env");
 const url_domains_1 = require("@constructive-io/url-domains");
 const logger_1 = require("@pgpmjs/logger");
 const server_utils_1 = require("@pgpmjs/server-utils");
-const agentic_server_1 = require("agentic-server");
 const cookie_parser_1 = __importDefault(require("cookie-parser"));
 const express_1 = __importDefault(require("express"));
 const graphile_cache_1 = require("graphile-cache");
 const graphql_upload_1 = __importDefault(require("graphql-upload"));
 const pg_cache_1 = require("pg-cache");
 const request_ip_1 = __importDefault(require("request-ip"));
+const agentic_1 = require("./agentic");
 const debug_db_snapshot_1 = require("./diagnostics/debug-db-snapshot");
 const debug_sampler_1 = require("./diagnostics/debug-sampler");
 const observability_1 = require("./diagnostics/observability");
@@ -180,7 +180,7 @@ class Server {
         app.use('/graphql', csrfProtect); // Enforce CSRF on GraphQL mutations
         // LLM Agent REST API — mounted before graphile so SSE streaming
         // routes are handled without going through PostGraphile
-        app.use((0, agentic_server_1.createAgenticRouter)());
+        app.use((0, agentic_1.createAgenticRouter)());
         // REST function invocation routes (POST /fn/:alias, GET /fn/invocations/:id)
         app.use((0, fn_1.createFnRouter)());
         app.use((0, graphile_1.graphile)(effectiveOpts));