@m6d/cortex-cli 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@m6d/cortex-cli",
-    "version": "1.0.0",
+    "version": "1.1.0",
     "description": "Scaffold and operate Cortex servers",
     "license": "MIT",
     "type": "module",
@@ -33,5 +33,8 @@
     },
     "publishConfig": {
         "access": "public"
-    }
+    },
+    "releaseWatchPaths": [
+        "internal/contracts"
+    ]
 }

package/src/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/src/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",