@m6d/cortex-server 1.5.0 → 1.7.0

package/README.md

@@ -57,7 +57,7 @@ export default {
 
 `cortex.serve()` is async — it runs database migrations on startup.
 
-Each key in `agents` becomes a route prefix (e.g. `assistant` → `/agents/assistant/...`). Agents can define per-agent `systemPrompt`, `tools`, `backendFetch`, `loadSessionData`, and lifecycle hooks (`onToolCall`, `onStreamFinish`).
+Each key in `agents` becomes a route prefix (e.g. `assistant` → `/agents/assistant/...`). Agents can define per-agent `systemPrompt`, `tools`, `backendFetch`, `loadSessionData`, `resolveRequestContext`, and lifecycle hooks (`onToolCall`, `onStreamFinish`).
 
 ## Requirements
 

package/dist/src/ai/index.d.ts

@@ -1,4 +1,4 @@
 import type { ResolvedCortexAgentConfig } from "../config.ts";
 import type { Thread } from "../types.ts";
-export declare function stream(messages: unknown[], thread: Thread, userId: string, token: string, config: ResolvedCortexAgentConfig): Promise<Response>;
+export declare function stream(messages: unknown[], thread: Thread, userId: string, token: string, requestContext: Record<string, unknown>, config: ResolvedCortexAgentConfig): Promise<Response>;
 export declare function generateTitle(threadId: string, prompt: string, userId: string, config: ResolvedCortexAgentConfig): Promise<void>;

package/dist/src/ai/prompt.d.ts

@@ -1,9 +1,9 @@
 import type { ResolvedContext } from "../graph/resolver.ts";
-import type { ResolvedCortexAgentConfig } from "../config.ts";
+import type { PromptContext, ResolvedCortexAgentConfig } from "../config.ts";
 import type { Thread } from "../types.ts";
 /**
  * Resolves session data for the thread, loading from the configured
  * session loader if not already cached on the thread.
  */
 export declare function resolveSession(config: ResolvedCortexAgentConfig, thread: Thread, token: string): Promise<Record<string, unknown> | null>;
-export declare function buildSystemPrompt(config: ResolvedCortexAgentConfig, resolved: ResolvedContext | null, session: Record<string, unknown> | null): Promise<string>;
+export declare function buildSystemPrompt(config: ResolvedCortexAgentConfig, resolved: ResolvedContext | null, promptContext: PromptContext): Promise<string>;

package/dist/src/config.d.ts

@@ -10,6 +10,10 @@ export type KnowledgeConfig = {
     };
     domains?: Record<string, DomainDef>;
 };
+export type PromptContext<TSession extends Record<string, unknown> = Record<string, unknown>, TRequestContext extends Record<string, unknown> = Record<string, unknown>> = {
+    session: TSession | null;
+    requestContext: TRequestContext;
+};
 export type DatabaseConfig = {
     type: "mssql";
     connectionString: string;
@@ -22,8 +26,8 @@ export type StorageConfig = {
     secretKey: string;
     bucketName?: string;
 };
-export type CortexAgentDefinition = {
-    systemPrompt: string | ((session: Record<string, unknown> | null) => string | Promise<string>);
+export type CortexAgentDefinition<TSession extends Record<string, unknown> = Record<string, unknown>, TRequestContext extends Record<string, unknown> = Record<string, unknown>> = {
+    systemPrompt: string | ((context: PromptContext<TSession, TRequestContext>) => string | Promise<string>);
     tools?: ToolSet;
     backendFetch?: {
         baseUrl: string;
@@ -34,7 +38,8 @@ export type CortexAgentDefinition = {
         }) => Promise<Record<string, unknown>>;
         interceptor?: RequestInterceptorOptions;
     };
-    loadSessionData?: (token: string) => Promise<Record<string, unknown>>;
+    loadSessionData?: (token: string) => Promise<TSession>;
+    resolveRequestContext?: (request: Request) => TRequestContext | Promise<TRequestContext>;
     onToolCall?: (toolCall: {
         toolName: string;
         toolCallId: string;
@@ -92,7 +97,7 @@ export type ResolvedCortexAgentConfig = {
         url: string;
         apiKey: string;
     };
-    systemPrompt: string | ((session: Record<string, unknown> | null) => string | Promise<string>);
+    systemPrompt: string | ((context: PromptContext) => string | Promise<string>);
     tools?: ToolSet;
     backendFetch?: {
         baseUrl: string;
@@ -104,6 +109,7 @@ export type ResolvedCortexAgentConfig = {
         interceptor?: RequestInterceptorOptions;
     };
     loadSessionData?: (token: string) => Promise<Record<string, unknown>>;
+    resolveRequestContext?: (request: Request) => Record<string, unknown> | Promise<Record<string, unknown>>;
     onToolCall?: (toolCall: {
         toolName: string;
         toolCallId: string;
@@ -151,3 +157,9 @@ export type CortexConfig = {
     knowledge?: KnowledgeConfig;
     agents: Record<string, CortexAgentDefinition>;
 };
+/**
+ * Helper to define an agent with full type inference for `systemPrompt` context.
+ * The `context.session` type is inferred from `loadSessionData`'s return type,
+ * and `context.requestContext` is inferred from `resolveRequestContext`'s return type.
+ */
+export declare function defineAgent<TSession extends Record<string, unknown> = Record<string, unknown>, TRequestContext extends Record<string, unknown> = Record<string, unknown>>(config: CortexAgentDefinition<TSession, TRequestContext>): CortexAgentDefinition;

package/dist/src/index.d.ts

@@ -1,4 +1,5 @@
-export type { CortexConfig, CortexAgentDefinition, KnowledgeConfig, DatabaseConfig, StorageConfig, } from "./config";
+export type { CortexConfig, CortexAgentDefinition, KnowledgeConfig, DatabaseConfig, StorageConfig, PromptContext, } from "./config";
+export { defineAgent } from "./config";
 export type { ContextConfig, ThreadContextMeta } from "./ai/context/types";
 export type { Thread, AppEnv } from "./types";
 export type { CortexInstance } from "./factory";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@m6d/cortex-server",
-    "version": "1.5.0",
+    "version": "1.7.0",
     "description": "Reusable AI agent chat server library for Hono + Bun",
     "license": "MIT",
     "type": "module",

package/src/ai/index.ts

@@ -36,6 +36,7 @@ export async function stream(
     thread: Thread,
     userId: string,
     token: string,
+    requestContext: Record<string, unknown>,
     config: ResolvedCortexAgentConfig,
 ) {
     const abortController = new AbortController();
@@ -111,7 +112,10 @@ export async function stream(
         ...config.tools,
     } as ToolSet;
 
-    const systemPrompt = await buildSystemPrompt(config, resolved, session);
+    const systemPrompt = await buildSystemPrompt(config, resolved, {
+        session,
+        requestContext,
+    });
 
     // The context builder reserved a static token budget for the system prompt + tools.
     // Now that we have the actual values, verify the reserve was sufficient and trim

package/src/ai/prompt.ts

@@ -1,5 +1,5 @@
 import type { ResolvedContext } from "../graph/resolver.ts";
-import type { ResolvedCortexAgentConfig } from "../config.ts";
+import type { PromptContext, ResolvedCortexAgentConfig } from "../config.ts";
 import type { Thread } from "../types.ts";
 
 /**
@@ -26,12 +26,12 @@ export async function resolveSession(
 export async function buildSystemPrompt(
     config: ResolvedCortexAgentConfig,
     resolved: ResolvedContext | null,
-    session: Record<string, unknown> | null,
+    promptContext: PromptContext,
 ) {
     // Resolve the consumer's base system prompt
     let basePrompt: string;
     if (typeof config.systemPrompt === "function") {
-        basePrompt = await config.systemPrompt(session);
+        basePrompt = await config.systemPrompt(promptContext);
     } else {
         basePrompt = config.systemPrompt;
     }

package/src/config.ts

@@ -10,6 +10,14 @@ export type KnowledgeConfig = {
     domains?: Record<string, DomainDef>;
 };
 
+export type PromptContext<
+    TSession extends Record<string, unknown> = Record<string, unknown>,
+    TRequestContext extends Record<string, unknown> = Record<string, unknown>,
+> = {
+    session: TSession | null;
+    requestContext: TRequestContext;
+};
+
 export type DatabaseConfig = {
     type: "mssql";
     connectionString: string;
@@ -24,8 +32,13 @@ export type StorageConfig = {
     bucketName?: string;
 };
 
-export type CortexAgentDefinition = {
-    systemPrompt: string | ((session: Record<string, unknown> | null) => string | Promise<string>);
+export type CortexAgentDefinition<
+    TSession extends Record<string, unknown> = Record<string, unknown>,
+    TRequestContext extends Record<string, unknown> = Record<string, unknown>,
+> = {
+    systemPrompt:
+        | string
+        | ((context: PromptContext<TSession, TRequestContext>) => string | Promise<string>);
     tools?: ToolSet;
     backendFetch?: {
         baseUrl: string;
@@ -37,7 +50,8 @@ export type CortexAgentDefinition = {
         ) => Promise<Record<string, unknown>>;
         interceptor?: RequestInterceptorOptions;
     };
-    loadSessionData?: (token: string) => Promise<Record<string, unknown>>;
+    loadSessionData?: (token: string) => Promise<TSession>;
+    resolveRequestContext?: (request: Request) => TRequestContext | Promise<TRequestContext>;
     onToolCall?: (toolCall: {
         toolName: string;
         toolCallId: string;
@@ -93,7 +107,7 @@ export type ResolvedCortexAgentConfig = {
         url: string;
         apiKey: string;
     };
-    systemPrompt: string | ((session: Record<string, unknown> | null) => string | Promise<string>);
+    systemPrompt: string | ((context: PromptContext) => string | Promise<string>);
     tools?: ToolSet;
     backendFetch?: {
         baseUrl: string;
@@ -106,6 +120,9 @@ export type ResolvedCortexAgentConfig = {
         interceptor?: RequestInterceptorOptions;
     };
     loadSessionData?: (token: string) => Promise<Record<string, unknown>>;
+    resolveRequestContext?: (
+        request: Request,
+    ) => Record<string, unknown> | Promise<Record<string, unknown>>;
     onToolCall?: (toolCall: {
         toolName: string;
         toolCallId: string;
@@ -151,3 +168,15 @@ export type CortexConfig = {
     knowledge?: KnowledgeConfig;
     agents: Record<string, CortexAgentDefinition>;
 };
+
+/**
+ * Helper to define an agent with full type inference for `systemPrompt` context.
+ * The `context.session` type is inferred from `loadSessionData`'s return type,
+ * and `context.requestContext` is inferred from `resolveRequestContext`'s return type.
+ */
+export function defineAgent<
+    TSession extends Record<string, unknown> = Record<string, unknown>,
+    TRequestContext extends Record<string, unknown> = Record<string, unknown>,
+>(config: CortexAgentDefinition<TSession, TRequestContext>): CortexAgentDefinition {
+    return config as CortexAgentDefinition;
+}

package/src/factory.ts

@@ -95,6 +95,7 @@ export function createCortex(config: CortexConfig) {
                     tools: agentDef.tools,
                     backendFetch: agentDef.backendFetch,
                     loadSessionData: agentDef.loadSessionData,
+                    resolveRequestContext: agentDef.resolveRequestContext,
                     onToolCall: agentDef.onToolCall,
                     onStreamFinish: agentDef.onStreamFinish,
                     context: resolvedContext,

package/src/index.ts

@@ -5,7 +5,9 @@ export type {
     KnowledgeConfig,
     DatabaseConfig,
     StorageConfig,
+    PromptContext,
 } from "./config";
+export { defineAgent } from "./config";
 
 export type { ContextConfig, ThreadContextMeta } from "./ai/context/types";
 

package/src/routes/chat.ts

@@ -27,6 +27,9 @@ export function createChatRoutes() {
             const agentId = c.get("agentId");
             const { id: userId, token } = c.get("user");
             const { messages, id: threadId } = c.req.valid("json");
+            const requestContext = config.resolveRequestContext
+                ? await config.resolveRequestContext(c.req.raw)
+                : {};
 
             const thread = await config.db.threads.getById(userId, threadId);
 
@@ -34,7 +37,7 @@ export function createChatRoutes() {
                 throw new HTTPException(404, { message: "Not found" });
             }
 
-            return stream(messages, thread, userId, token, config);
+            return stream(messages, thread, userId, token, requestContext, config);
         },
     );