@m6d/cortex-cli 1.0.0 → 1.2.0

package/package.json

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

package/src/contracts/interactive.ts

@@ -0,0 +1,53 @@
+/**
+ * The embed ↔ widget handshake for interactive tools.
+ *
+ * A page embedded by the chat widget (a hosted checkout, signing page, …)
+ * reports its outcome with:
+ *
+ *     window.parent.postMessage(
+ *         { type: "cortex:interactive", status: "completed", reference: "session_123" },
+ *         "*",
+ *     );
+ *
+ * The widget accepts the message only when the event's origin matches the
+ * tool's configured `embedOrigin`, and treats the payload as untrusted — for
+ * tools with a verify endpoint the server re-checks the reference before the
+ * agent sees a result.
+ *
+ * Like `wire.ts`, this file is compiled into the client SDKs and must stay
+ * free of runtime dependencies. It is also the spec any future SDK (Flutter)
+ * reimplements against.
+ */
+
+export const INTERACTIVE_MESSAGE_TYPE = "cortex:interactive";
+
+export const INTERACTIVE_STATUSES = ["completed", "cancelled", "failed"] as const;
+
+export type InteractiveStatus = (typeof INTERACTIVE_STATUSES)[number];
+
+export type InteractiveHandshake = {
+    type: typeof INTERACTIVE_MESSAGE_TYPE;
+    status: InteractiveStatus;
+    /** Opaque id the tool's verify endpoint resolves (session id, envelope id, …). */
+    reference?: string;
+};
+
+/**
+ * Parse a `message` event into a handshake, or null when the origin doesn't
+ * match the tool's `embedOrigin` or the payload isn't a well-formed handshake.
+ * Call from the widget's `message` listener with `event.data` / `event.origin`.
+ */
+export function parseInteractiveHandshake(data: unknown, origin: string, embedOrigin: string) {
+    if (origin !== embedOrigin) return null;
+    if (typeof data !== "object" || data === null) return null;
+    const message = data as Record<string, unknown>;
+    if (message["type"] !== INTERACTIVE_MESSAGE_TYPE) return null;
+    const status = INTERACTIVE_STATUSES.find((known) => known === message["status"]);
+    if (!status) return null;
+    const reference = message["reference"];
+    return {
+        type: INTERACTIVE_MESSAGE_TYPE,
+        status,
+        ...(typeof reference === "string" ? { reference } : {}),
+    } satisfies InteractiveHandshake;
+}

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",
@@ -54,6 +89,19 @@ export const knowledgeChunkSchema = z.object({
     }),
 });
 
+/**
+ * Runtime contract §5.4: present on signatures of `interactive` tools — flows
+ * the end user completes in an embedded surface inside the chat widget. The
+ * tool's endpoint fields act as the *initiate* call (returns the embed URL);
+ * `hasVerify` marks a second, server-trusted call that settles the result.
+ */
+export const toolInteractionSchema = z.object({
+    surface: z.enum(["inline", "modal"]),
+    embedOrigin: z.url(),
+    hasVerify: z.boolean(),
+    resultDelivery: z.enum(["agent", "endpoint", "both"]),
+});
+
 export const toolSignatureSchema = z.object({
     toolId: z.uuid(),
     name: z.string().regex(TOOL_NAME_PATTERN),
@@ -63,6 +111,11 @@ export const toolSignatureSchema = z.object({
     signature: z.string(),
     score: z.number().nullable(),
     pinned: z.boolean(),
+    interaction: toolInteractionSchema.optional(),
+    /** Interactive tools only: the published input JSON Schema, verbatim.
+     * Client-executed declarations need a real schema — the rendered
+     * `signature` text alone is not enough for function calling. */
+    inputSchema: z.record(z.string(), z.unknown()).optional(),
 });
 
 export const serviceCardSchema = z.object({
@@ -159,6 +212,9 @@ export const searchKnowledgeResponseSchema = z.object({
 
 export const executeRequestSchema = z.object({
     input: z.record(z.string(), z.unknown()).default({}),
+    // Interactive tools only: absent | "initiate" targets the tool's endpoint
+    // fields, "verify" targets its verify endpoint config.
+    phase: z.enum(["initiate", "verify"]).optional(),
     context: z
         .object({
             threadId: z.string().max(128).optional(),
@@ -201,6 +257,7 @@ export const runtimeErrorSchema = z.object({
     }),
 });
 
+export type ToolInteraction = z.infer<typeof toolInteractionSchema>;
 export type RuntimeAgentConfig = z.infer<typeof runtimeAgentConfigSchema>;
 export type ResolveRequest = z.input<typeof resolveRequestSchema>;
 export type ResolveResponse = z.infer<typeof resolveResponseSchema>;

package/src/contracts/wire.ts

@@ -70,12 +70,29 @@ export type TokenUsage = {
     total: number;
 };
 
+/**
+ * How to launch one interactive tool: stamped by the server, per tool name, on
+ * the metadata of an assistant message that may carry its pending call. Kept in
+ * the message so the binding survives server restarts while a run is parked.
+ */
+export type InteractiveToolBinding = {
+    toolId: string;
+    surface: "inline" | "modal";
+    embedOrigin: string;
+    hasVerify: boolean;
+    resultDelivery: "agent" | "endpoint" | "both";
+};
+
 export type MessageMetadata = {
     modelId?: string;
     providerMetadata?: unknown;
     isAborted?: boolean;
     tokenUsage?: TokenUsage;
     attachments?: AttachmentSummary[];
+    interactiveTools?: Record<string, InteractiveToolBinding>;
+    /** Per tool call: the trusted reference its initiate call returned. A
+     * verified completion must match it — the browser's word is never enough. */
+    interactiveReferences?: Record<string, string>;
 };
 
 /**
@@ -93,6 +110,21 @@ export type CortexMessage<TPart = unknown> = {
     metadata?: MessageMetadata;
 };
 
+/**
+ * Response of `POST /chat/:chatId/tools/:toolCallId/initiate`. `interactive:
+ * false` means the pending call is not an interactive CC tool — the widget
+ * falls back to its default rendering for the call. The payload is for the
+ * widget only; it never reaches the LLM.
+ */
+export type InteractiveInitiateResult =
+    | { interactive: false }
+    | {
+          interactive: true;
+          embedUrl: string;
+          surface: "inline" | "modal";
+          embedOrigin: string;
+      };
+
 export type ThreadCreatedEvent = {
     type: "thread:created";
     payload: { thread: ThreadSummary };