@m6d/cortex-server 2.0.0 → 2.0.1

package/contracts/rich-text.ts

@@ -0,0 +1,207 @@
+/*
+ * The grammar and rendering pipeline for user-authored rich text that reaches
+ * the LLM (agent prompts, service descriptions). Both sides of the wire share
+ * it: the console edits and validates these strings, the console's runtime API
+ * pre-renders them (mentions + heading demotion), and `@m6d/cortex-server`
+ * applies per-request variable values. Two token grammars live here:
+ *
+ * - Tool mentions `@[name](uuid)` — the uuid is authoritative; the inline name
+ *   is only a display cache refreshed on save ({@link normalizeMentions}) and
+ *   resolved live when text is rendered for the LLM ({@link renderMentions}).
+ * - Variables `{{name}}` — validated against a known list at authoring time
+ *   ({@link analyzeVariables}) and substituted per request on the server
+ *   ({@link substituteVariables}).
+ */
+
+/** One mention token, unanchored and flagless — the editor's tokenizer anchors it, the helpers below add `g`. */
+export const MENTION_PATTERN_SOURCE = String.raw`@\[([^\]\n]*)\]\(([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\)`;
+
+const MENTION_PATTERN = new RegExp(MENTION_PATTERN_SOURCE, "g");
+
+const VARIABLE_PATTERN = /{{\s*([^{}]*?)\s*}}/g;
+
+export function extractMentionedToolIds(text: string) {
+    const ids: string[] = [];
+    for (const match of text.matchAll(MENTION_PATTERN)) {
+        const id = match[2];
+        if (id && !ids.includes(id)) ids.push(id);
+    }
+    return ids;
+}
+
+/** Replaces each mention token with the tool's current name (falling back to the cached inline name). */
+export function renderMentions(text: string, toolNameById: ReadonlyMap<string, string>) {
+    return text.replace(MENTION_PATTERN, (_, cachedName: string, toolId: string) => {
+        return toolNameById.get(toolId) ?? cachedName;
+    });
+}
+
+/** Refreshes stale display names inside stored text, keeping the tokens intact. */
+export function normalizeMentions(text: string, toolNameById: ReadonlyMap<string, string>) {
+    return text.replace(MENTION_PATTERN, (token, _cachedName: string, toolId: string) => {
+        const name = toolNameById.get(toolId);
+        return name === undefined ? token : `@[${name}](${toolId})`;
+    });
+}
+
+/** Splits the `{{variables}}` referenced in a text into known and unknown ones. */
+export function analyzeVariables<Variable extends string>(
+    text: string,
+    known: ReadonlyArray<Variable>,
+) {
+    const referenced = new Set(
+        Array.from(text.matchAll(VARIABLE_PATTERN), ([, name]) => name?.trim()),
+    );
+
+    return {
+        variables: known.filter((variable) => referenced.has(variable)),
+        unknownVariables: [...referenced].filter(
+            (variable): variable is string =>
+                variable !== undefined &&
+                !known.some((knownVariable) => knownVariable === variable),
+        ),
+    };
+}
+
+/** Fills `{{variables}}` with per-request values; unknown names stay verbatim. */
+export function substituteVariables(text: string, values: Record<string, string>) {
+    return text.replace(/\{\{(\w+)\}\}/g, (match, name: string) => values[name] ?? match);
+}
+
+/**
+ * Line-by-line fence state, following CommonMark's fence rules: a fence line
+ * is indented at most three spaces; an opening backtick fence's info string
+ * may not contain backticks; and a fence closes only on the same marker
+ * character, with at least the opening run's length, followed by nothing but
+ * whitespace — so a `~~~` line, a shorter same-marker run, or a ```` ```js ````
+ * info line inside a backtick fence all stay code content.
+ */
+function fenceTracker() {
+    let fence: { marker: string; length: number } | null = null;
+    return (line: string) => {
+        const match = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+        const delimiter = match?.[1];
+        const rest = match?.[2] ?? "";
+        if (delimiter) {
+            const marker = delimiter.charAt(0);
+            if (fence) {
+                if (
+                    marker === fence.marker &&
+                    delimiter.length >= fence.length &&
+                    rest.trim() === ""
+                ) {
+                    fence = null;
+                    return "close";
+                }
+                return "inside";
+            }
+            if (marker === "`" && rest.includes("`")) return "outside";
+            fence = { marker, length: delimiter.length };
+            return "open";
+        }
+        return fence ? "inside" : "outside";
+    };
+}
+
+/** ATX heading, CommonMark-style: up to three leading spaces, `#` run closed by space or line end. */
+const ATX_HEADING = /^( {0,3})(#{1,6})(?=[ \t]|$)/;
+
+/** Setext underline: a run of `=` or `-` alone on its line, up to three leading spaces. */
+const SETEXT_UNDERLINE = /^ {0,3}(=+|-+)[ \t]*$/;
+
+/** The skeleton owns `##` and `###`, so user headings start three levels below it. */
+function demotedHashes(level: number) {
+    return "#".repeat(Math.min(level + 3, 6));
+}
+
+/**
+ * Whether a line can be the text of a setext heading — i.e. it is an ordinary
+ * paragraph line, not a blank, a fence, another heading, or the start of a
+ * different block (quote/list), in which case the underline below it is a
+ * thematic break or list content rather than a heading marker.
+ */
+function isSetextText(line: string) {
+    return (
+        line.trim() !== "" &&
+        !ATX_HEADING.test(line) &&
+        !SETEXT_UNDERLINE.test(line) &&
+        !/^ {0,3}(`{3,}|~{3,})/.test(line) &&
+        !/^ {0,3}(>|[-*+][ \t]|\d+[.)][ \t])/.test(line)
+    );
+}
+
+/**
+ * Shifts user-authored headings down so they can never collide with the prompt
+ * skeleton, which owns `##` (sections) and `###` (card titles): `#` becomes
+ * `####`, deeper levels cap at `######`. Setext headings are rewritten as the
+ * equivalent demoted ATX heading, since two-level setext cannot express the
+ * shift. Fenced code is left alone.
+ */
+export function demoteHeadings(text: string) {
+    const lineState = fenceTracker();
+    const output: string[] = [];
+    for (const line of text.split("\n")) {
+        if (lineState(line) !== "outside") {
+            output.push(line);
+            continue;
+        }
+
+        const underline = SETEXT_UNDERLINE.exec(line)?.[1];
+        const previous = output[output.length - 1];
+        if (underline !== undefined && previous !== undefined && isSetextText(previous)) {
+            const level = underline.startsWith("=") ? 1 : 2;
+            output[output.length - 1] = `${demotedHashes(level)} ${previous.trim()}`;
+            continue;
+        }
+
+        output.push(
+            line.replace(ATX_HEADING, (_, indent: string, hashes: string) => {
+                return `${indent}${demotedHashes(hashes.length)}`;
+            }),
+        );
+    }
+    return output.join("\n");
+}
+
+/** The one render step for LLM-bound rich text: resolve mentions, then demote headings. */
+export function renderRichText(text: string, toolNameById: ReadonlyMap<string, string>) {
+    return demoteHeadings(renderMentions(text, toolNameById));
+}
+
+/**
+ * Reduces rich text to plain prose for embeddings: mentions become tool names
+ * (cached inline names when no map is given) and markdown syntax is dropped.
+ * ponytail: a regex stripper, not a markdown parser — nested emphasis or exotic
+ * constructs may leave residue; swap in a real parser if retrieval quality
+ * ever shows it.
+ */
+export function stripToPlaintext(
+    text: string,
+    toolNameById: ReadonlyMap<string, string> = new Map(),
+) {
+    const lineState = fenceTracker();
+    return renderMentions(text, toolNameById)
+        .split("\n")
+        .filter((line) => {
+            const state = lineState(line);
+            return state !== "open" && state !== "close";
+        })
+        .map((line) =>
+            line
+                .replace(/^ {0,3}#{1,6}[ \t]+/, "")
+                .replace(SETEXT_UNDERLINE, "")
+                .replace(/^\s{0,3}(>\s?)+/, "")
+                .replace(/^(\s*)([-*+]|\d+[.)])\s+/, "$1")
+                .replace(/^\s*([-*_]\s*){3,}$/, ""),
+        )
+        .join("\n")
+        .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1")
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+        .replace(/(\*\*|__)([^*_]+)\1/g, "$2")
+        .replace(/(^|\W)[*_]([^*_]+)[*_](?=\W|$)/gm, "$1$2")
+        .replace(/~~([^~]+)~~/g, "$1")
+        .replace(/`([^`]*)`/g, "$1")
+        .replace(/\\([\\*_#[\]()>!`~+.-])/g, "$1")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}

package/contracts/runtime.ts

@@ -13,7 +13,42 @@ export const AGENT_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
 /** Runtime contract §5: tool names become `tools.<name>()` sandbox bindings. */
 export const TOOL_NAME_PATTERN = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
 
-export const PROMPT_VARIABLES = ["userName", "channel", "locale"] as const;
+export const PROMPT_VARIABLES = ["userName", "channel", "locale", "utcTime", "timezone"] as const;
+
+/**
+ * One entry per prompt variable, driving editor autocomplete, validation, and
+ * runtime substitution alike. Adding a variable = extending the tuple above
+ * plus one entry here (the compiler enforces the pair); the consumer embedding
+ * the agent supplies the value in its session/request context under the same
+ * key. Descriptions are plain English on purpose: variables are code-like
+ * identifiers shown in an LTR suggestion list, not localized UI copy.
+ */
+export const PROMPT_VARIABLE_DEFINITIONS = {
+    userName: {
+        description: "Display name of the signed-in user",
+        example: "Sara",
+    },
+    channel: {
+        description: "Channel the conversation arrived on",
+        example: "web",
+    },
+    locale: {
+        description: "Resolved locale of the session",
+        example: "ar",
+    },
+    // The server computes utcTime per request (a consumer-supplied value
+    // still wins); timezone has no server default — only the consumer knows
+    // the session's zone, so it must arrive via session/request context or
+    // the placeholder stays literal.
+    utcTime: {
+        description: "Current time in UTC (ISO 8601)",
+        example: "2026-08-16T09:30:00Z",
+    },
+    timezone: {
+        description: "IANA time zone of the session",
+        example: "Asia/Dubai",
+    },
+} satisfies Record<(typeof PROMPT_VARIABLES)[number], { description: string; example: string }>;
 
 export const RUNTIME_ERROR_KINDS = [
     "timeout",

package/dist/contracts/rich-text.d.ts

@@ -0,0 +1,32 @@
+/** One mention token, unanchored and flagless — the editor's tokenizer anchors it, the helpers below add `g`. */
+export declare const MENTION_PATTERN_SOURCE: string;
+export declare function extractMentionedToolIds(text: string): string[];
+/** Replaces each mention token with the tool's current name (falling back to the cached inline name). */
+export declare function renderMentions(text: string, toolNameById: ReadonlyMap<string, string>): string;
+/** Refreshes stale display names inside stored text, keeping the tokens intact. */
+export declare function normalizeMentions(text: string, toolNameById: ReadonlyMap<string, string>): string;
+/** Splits the `{{variables}}` referenced in a text into known and unknown ones. */
+export declare function analyzeVariables<Variable extends string>(text: string, known: ReadonlyArray<Variable>): {
+    variables: Variable[];
+    unknownVariables: string[];
+};
+/** Fills `{{variables}}` with per-request values; unknown names stay verbatim. */
+export declare function substituteVariables(text: string, values: Record<string, string>): string;
+/**
+ * Shifts user-authored headings down so they can never collide with the prompt
+ * skeleton, which owns `##` (sections) and `###` (card titles): `#` becomes
+ * `####`, deeper levels cap at `######`. Setext headings are rewritten as the
+ * equivalent demoted ATX heading, since two-level setext cannot express the
+ * shift. Fenced code is left alone.
+ */
+export declare function demoteHeadings(text: string): string;
+/** The one render step for LLM-bound rich text: resolve mentions, then demote headings. */
+export declare function renderRichText(text: string, toolNameById: ReadonlyMap<string, string>): string;
+/**
+ * Reduces rich text to plain prose for embeddings: mentions become tool names
+ * (cached inline names when no map is given) and markdown syntax is dropped.
+ * ponytail: a regex stripper, not a markdown parser — nested emphasis or exotic
+ * constructs may leave residue; swap in a real parser if retrieval quality
+ * ever shows it.
+ */
+export declare function stripToPlaintext(text: string, toolNameById?: ReadonlyMap<string, string>): string;

package/dist/contracts/runtime.d.ts

@@ -3,14 +3,44 @@ import { z } from "zod";
 export declare const AGENT_SLUG_PATTERN: RegExp;
 /** Runtime contract §5: tool names become `tools.<name>()` sandbox bindings. */
 export declare const TOOL_NAME_PATTERN: RegExp;
-export declare const PROMPT_VARIABLES: readonly ["userName", "channel", "locale"];
+export declare const PROMPT_VARIABLES: readonly ["userName", "channel", "locale", "utcTime", "timezone"];
+/**
+ * One entry per prompt variable, driving editor autocomplete, validation, and
+ * runtime substitution alike. Adding a variable = extending the tuple above
+ * plus one entry here (the compiler enforces the pair); the consumer embedding
+ * the agent supplies the value in its session/request context under the same
+ * key. Descriptions are plain English on purpose: variables are code-like
+ * identifiers shown in an LTR suggestion list, not localized UI copy.
+ */
+export declare const PROMPT_VARIABLE_DEFINITIONS: {
+    userName: {
+        description: string;
+        example: string;
+    };
+    channel: {
+        description: string;
+        example: string;
+    };
+    locale: {
+        description: string;
+        example: string;
+    };
+    utcTime: {
+        description: string;
+        example: string;
+    };
+    timezone: {
+        description: string;
+        example: string;
+    };
+};
 export declare const RUNTIME_ERROR_KINDS: readonly ["timeout", "upstream_4xx", "upstream_5xx", "schema_mismatch", "rate_limited", "not_found", "unauthorized", "invalid_request", "egress_blocked", "internal"];
 /** The ways an execute output may disagree with the tool's declared schema. */
 export declare const JSON_SCHEMA_ISSUE_KINDS: readonly ["missing", "unexpected", "type_mismatch"];
 export declare const agentSlugSchema: z.ZodString;
 export declare const localeSchema: z.ZodEnum<{
-    en: "en";
     ar: "ar";
+    en: "en";
 }>;
 export declare const catalogVersionSchema: z.ZodString;
 export declare const sharedShapeSchema: z.ZodObject<{
@@ -54,11 +84,13 @@ export declare const runtimeAgentConfigSchema: z.ZodObject<{
         userName: "userName";
         channel: "channel";
         locale: "locale";
+        utcTime: "utcTime";
+        timezone: "timezone";
     }>>;
     catalogBlurb: z.ZodString;
     defaultLocale: z.ZodEnum<{
-        en: "en";
         ar: "ar";
+        en: "en";
     }>;
     metaTools: z.ZodObject<{
         searchKnowledge: z.ZodBoolean;
@@ -76,8 +108,8 @@ export declare const runtimeAgentConfigSchema: z.ZodObject<{
 export declare const resolveRequestSchema: z.ZodObject<{
     query: z.ZodString;
     locale: z.ZodOptional<z.ZodEnum<{
-        en: "en";
         ar: "ar";
+        en: "en";
     }>>;
     hints: z.ZodOptional<z.ZodObject<{
         threadId: z.ZodOptional<z.ZodString>;
@@ -95,8 +127,8 @@ export declare const resolveResponseSchema: z.ZodObject<{
     resolveId: z.ZodUUID;
     catalogVersion: z.ZodString;
     locale: z.ZodEnum<{
-        en: "en";
         ar: "ar";
+        en: "en";
     }>;
     knowledge: z.ZodArray<z.ZodObject<{
         chunkId: z.ZodUUID;
@@ -142,8 +174,8 @@ export declare const searchRequestSchema: z.ZodObject<{
     query: z.ZodString;
     limit: z.ZodDefault<z.ZodNumber>;
     locale: z.ZodOptional<z.ZodEnum<{
-        en: "en";
         ar: "ar";
+        en: "en";
     }>>;
     threadId: z.ZodOptional<z.ZodString>;
     service: z.ZodOptional<z.ZodString>;
@@ -211,8 +243,8 @@ export declare const executeRequestSchema: z.ZodObject<{
         threadId: z.ZodOptional<z.ZodString>;
         userId: z.ZodOptional<z.ZodString>;
         locale: z.ZodOptional<z.ZodEnum<{
-            en: "en";
             ar: "ar";
+            en: "en";
         }>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;

package/dist/src/lib/ai/cc-runtime.d.ts

@@ -31,9 +31,9 @@ export declare function createCcRuntime(options: CcRuntimeOptions): {
     config: {
         agentId: string;
         systemPrompt: string;
-        promptVariables: ("userName" | "channel" | "locale")[];
+        promptVariables: ("userName" | "channel" | "locale" | "utcTime" | "timezone")[];
         catalogBlurb: string;
-        defaultLocale: "en" | "ar";
+        defaultLocale: "ar" | "en";
         metaTools: {
             searchKnowledge: boolean;
             searchTools: boolean;
@@ -51,7 +51,7 @@ export declare function createCcRuntime(options: CcRuntimeOptions): {
     threadId: string;
     turnKey: string;
     userId: string;
-    locale: "en" | "ar";
+    locale: "ar" | "en";
     endUserToken: string;
     abortSignal: AbortSignal;
     getStepIndex: () => number;

package/dist/src/lib/ai/tools/search-common.d.ts

@@ -10,7 +10,7 @@ export declare function searchRequest(cc: CcRuntime, input: {
     query: string;
     limit?: number;
 }): {
-    locale: "en" | "ar";
+    locale: "ar" | "en";
     threadId: string;
     query: string;
     limit?: number;

package/dist/src/lib/cc/client.d.ts

@@ -30,9 +30,9 @@ export declare class ControlCenterClient {
         readonly config: {
             agentId: string;
             systemPrompt: string;
-            promptVariables: ("userName" | "channel" | "locale")[];
+            promptVariables: ("userName" | "channel" | "locale" | "utcTime" | "timezone")[];
             catalogBlurb: string;
-            defaultLocale: "en" | "ar";
+            defaultLocale: "ar" | "en";
             metaTools: {
                 searchKnowledge: boolean;
                 searchTools: boolean;
@@ -51,7 +51,7 @@ export declare class ControlCenterClient {
     resolve(agentId: string, request: ResolveRequest, abortSignal?: AbortSignal): Promise<{
         resolveId: string;
         catalogVersion: string;
-        locale: "en" | "ar";
+        locale: "ar" | "en";
         knowledge: {
             chunkId: string;
             text: string;

package/dist/src/lib/cc/config-cache.d.ts

@@ -2,9 +2,9 @@ import type { ControlCenterClient } from "./client";
 export declare function getControlCenterConfig(cc: ControlCenterClient, agentId: string, abortSignal?: AbortSignal): Promise<{
     agentId: string;
     systemPrompt: string;
-    promptVariables: ("userName" | "channel" | "locale")[];
+    promptVariables: ("userName" | "channel" | "locale" | "utcTime" | "timezone")[];
     catalogBlurb: string;
-    defaultLocale: "en" | "ar";
+    defaultLocale: "ar" | "en";
     metaTools: {
         searchKnowledge: boolean;
         searchTools: boolean;

package/package.json

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

package/src/lib/ai/index.ts

@@ -190,6 +190,13 @@ export async function startTurn(
                       config: cc.config,
                       resolved: ccResolved,
                       variables: buildPromptVariables(cc.config.promptVariables, {
+                          // Computed per request; consumer-supplied context
+                          // with the same key wins via the spreads below. No
+                          // such default for `timezone`: the server's zone is
+                          // not the session's, so guessing would feed the
+                          // model wrong user context — only the consumer can
+                          // supply it.
+                          utcTime: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
                           ...session,
                           ...requestContext,
                           locale: cc.locale,

package/src/lib/cc/format.ts

@@ -1,3 +1,5 @@
+import { substituteVariables } from "@cortex/contracts/rich-text";
+
 import type { ResolveResponse, RuntimeAgentConfig } from "./types";
 
 type SharedShape = ResolveResponse["sharedShapes"][number];
@@ -5,12 +7,6 @@ type ToolSignature = ResolveResponse["tools"][number];
 type ServiceCard = ResolveResponse["services"][number];
 type KnowledgeChunk = ResolveResponse["knowledge"][number];
 
-function substitutePromptVariables(template: string, variables: Record<string, string>) {
-    return template.replace(/\{\{(\w+)\}\}/g, function replaceVariable(match, name: string) {
-        return variables[name] ?? match;
-    });
-}
-
 /** Values for the published prompt's `{{variable}}` placeholders, read from session/request context. */
 export function buildPromptVariables(
     promptVariables: RuntimeAgentConfig["promptVariables"],
@@ -67,7 +63,7 @@ export type CcPromptInput = {
 export function buildCcSection(cc: CcPromptInput) {
     const parts: string[] = [];
 
-    const prompt = substitutePromptVariables(cc.config.systemPrompt, cc.variables).trim();
+    const prompt = substituteVariables(cc.config.systemPrompt, cc.variables).trim();
     if (prompt) parts.push(prompt);
 
     if (cc.config.catalogBlurb) {