@m6d/cortex-server 1.7.0 → 2.0.0

package/src/lib/cc/client.ts

@@ -0,0 +1,273 @@
+import { createHash } from "node:crypto";
+import type z from "zod";
+import type { ControlCenterConfig } from "@/config";
+import {
+    executeResponseSchema,
+    resolveResponseSchema,
+    runtimeAgentConfigSchema,
+    runtimeErrorSchema,
+    searchKnowledgeResponseSchema,
+    searchServicesResponseSchema,
+    searchToolsResponseSchema,
+} from "./types";
+import type { ExecuteRequest, ResolveRequest, SearchRequest } from "./types";
+
+type ControlCenterFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+export type ExecuteOptions = {
+    readOnly: boolean;
+    endUserToken?: string;
+    threadId: string;
+    turnKey: string;
+    stepIndex: number;
+    callIndex: number;
+    timeoutMs?: number;
+    abortSignal?: AbortSignal;
+};
+
+const retryAfterByUrl = new Map<string, number>();
+
+function normalizeQuery(query: string) {
+    return query.trim().slice(0, 4000);
+}
+
+export class ControlCenterClient {
+    public readonly url: string;
+    public readonly cacheKey: string;
+    private readonly apiKey: string;
+    private readonly fetcher: ControlCenterFetch;
+
+    public constructor(config: ControlCenterConfig, fetcher: ControlCenterFetch = fetch) {
+        this.url = config.url.replace(/\/+$/, "");
+        this.cacheKey = `${this.url}|${createHash("sha256").update(config.apiKey).digest("hex").slice(0, 16)}`;
+        this.apiKey = config.apiKey;
+        this.fetcher = fetcher;
+    }
+
+    public async getConfig(agentId: string, etag?: string, abortSignal?: AbortSignal) {
+        try {
+            const headers = new Headers();
+            if (etag !== undefined) headers.set("If-None-Match", etag);
+
+            const response = await this.request(
+                this.agentPath(agentId, "/config"),
+                { headers },
+                abortSignal,
+            );
+            if (!response) return null;
+            if (response.status === 304) return { status: "not-modified" } as const;
+            if (response.status === 404) return { status: "not-found" } as const;
+            if (!response.ok) return null;
+
+            const config = await this.parse(response, runtimeAgentConfigSchema);
+            if (!config) return null;
+
+            return {
+                status: "modified",
+                config,
+                etag: response.headers.get("ETag"),
+            } as const;
+        } catch {
+            return null;
+        }
+    }
+
+    public async resolve(agentId: string, request: ResolveRequest, abortSignal?: AbortSignal) {
+        const query = normalizeQuery(request.query);
+        if (!query) return null;
+        return this.post(
+            this.agentPath(agentId, "/resolve"),
+            { ...request, query },
+            resolveResponseSchema,
+            abortSignal,
+        );
+    }
+
+    public async searchTools(agentId: string, request: SearchRequest, abortSignal?: AbortSignal) {
+        const query = normalizeQuery(request.query);
+        if (!query) return null;
+        return this.post(
+            this.agentPath(agentId, "/search/tools"),
+            { ...request, query },
+            searchToolsResponseSchema,
+            abortSignal,
+        );
+    }
+
+    public async searchServices(
+        agentId: string,
+        request: SearchRequest,
+        abortSignal?: AbortSignal,
+    ) {
+        const query = normalizeQuery(request.query);
+        if (!query) return null;
+        return this.post(
+            this.agentPath(agentId, "/search/services"),
+            { ...request, query },
+            searchServicesResponseSchema,
+            abortSignal,
+        );
+    }
+
+    public async searchKnowledge(
+        agentId: string,
+        request: SearchRequest,
+        abortSignal?: AbortSignal,
+    ) {
+        const query = normalizeQuery(request.query);
+        if (!query) return null;
+        return this.post(
+            this.agentPath(agentId, "/search/knowledge"),
+            { ...request, query },
+            searchKnowledgeResponseSchema,
+            abortSignal,
+        );
+    }
+
+    public async execute(
+        agentId: string,
+        toolId: string,
+        request: ExecuteRequest,
+        options: ExecuteOptions,
+    ) {
+        try {
+            const headers = new Headers();
+            if (options.endUserToken !== undefined) {
+                headers.set("X-End-User-Token", options.endUserToken);
+            }
+            if (!options.readOnly) {
+                headers.set(
+                    "Idempotency-Key",
+                    `${options.threadId}:${options.turnKey}:${options.stepIndex}:${options.callIndex}`,
+                );
+            }
+
+            const path = this.agentPath(agentId, `/tools/${encodeURIComponent(toolId)}/execute`);
+            let response = await this.postResponse(
+                path,
+                request,
+                headers,
+                options.abortSignal,
+                options.timeoutMs,
+            );
+            if (!response) return null;
+
+            let result = await this.parse(
+                response,
+                response.ok ? executeResponseSchema : runtimeErrorSchema,
+            );
+            if (
+                response.status === 409 &&
+                result &&
+                "error" in result &&
+                result.error.kind === "rate_limited" &&
+                result.error.retryAfterSeconds !== undefined &&
+                result.error.retryAfterSeconds <= 5
+            ) {
+                const retryAfterSeconds = result.error.retryAfterSeconds;
+                await new Promise<void>((resolve) => setTimeout(resolve, retryAfterSeconds * 1000));
+                response = await this.postResponse(
+                    path,
+                    request,
+                    headers,
+                    options.abortSignal,
+                    options.timeoutMs,
+                );
+                if (!response) return null;
+                result = await this.parse(
+                    response,
+                    response.ok ? executeResponseSchema : runtimeErrorSchema,
+                );
+            }
+
+            return result;
+        } catch {
+            return null;
+        }
+    }
+
+    private agentPath(agentId: string, suffix: string) {
+        return `/api/runtime/agents/${encodeURIComponent(agentId)}${suffix}`;
+    }
+
+    private async post<TSchema extends z.ZodType>(
+        path: string,
+        body: unknown,
+        schema: TSchema,
+        abortSignal?: AbortSignal,
+    ) {
+        const response = await this.postResponse(path, body, undefined, abortSignal);
+        if (!response?.ok) return null;
+        return this.parse(response, schema);
+    }
+
+    private async postResponse(
+        path: string,
+        body: unknown,
+        requestHeaders?: Headers,
+        abortSignal?: AbortSignal,
+        timeoutMs?: number,
+    ) {
+        try {
+            const headers = new Headers(requestHeaders);
+            headers.set("Content-Type", "application/json");
+            return await this.request(
+                path,
+                {
+                    method: "POST",
+                    headers,
+                    body: JSON.stringify(body),
+                },
+                abortSignal,
+                timeoutMs,
+            );
+        } catch {
+            return null;
+        }
+    }
+
+    private async request(
+        path: string,
+        init?: RequestInit,
+        abortSignal?: AbortSignal,
+        timeoutMs = 15_000,
+    ) {
+        const url = `${this.url}${path}`;
+        const retryKey = `${this.cacheKey}|${path}`;
+        const retryAt = retryAfterByUrl.get(retryKey);
+        if (retryAt !== undefined) {
+            if (retryAt > Date.now()) return null;
+            retryAfterByUrl.delete(retryKey);
+        }
+
+        try {
+            const headers = new Headers(init?.headers);
+            headers.set("Authorization", `Bearer ${this.apiKey}`);
+            const timeoutSignal = AbortSignal.timeout(timeoutMs);
+            const signal = abortSignal
+                ? AbortSignal.any([abortSignal, timeoutSignal])
+                : timeoutSignal;
+            const response = await this.fetcher(url, { ...init, headers, signal });
+
+            if (response.status === 429) {
+                const retryAfterSeconds = Number(response.headers.get("Retry-After"));
+                if (Number.isInteger(retryAfterSeconds) && retryAfterSeconds > 0) {
+                    retryAfterByUrl.set(retryKey, Date.now() + retryAfterSeconds * 1000);
+                }
+            }
+
+            return response;
+        } catch {
+            return null;
+        }
+    }
+
+    private async parse<TSchema extends z.ZodType>(response: Response, schema: TSchema) {
+        try {
+            const result = schema.safeParse(await response.json());
+            return result.success ? result.data : null;
+        } catch {
+            return null;
+        }
+    }
+}

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

@@ -0,0 +1,32 @@
+import type { ControlCenterClient } from "./client";
+import type { RuntimeAgentConfig } from "./types";
+
+type CachedConfig = {
+    etag: string | null;
+    config: RuntimeAgentConfig;
+};
+
+const configs = new Map<string, CachedConfig>();
+
+export async function getControlCenterConfig(
+    cc: ControlCenterClient,
+    agentId: string,
+    abortSignal?: AbortSignal,
+) {
+    const key = `${cc.cacheKey}|${agentId}`;
+    const cached = configs.get(key);
+    const result = await cc.getConfig(agentId, cached?.etag ?? undefined, abortSignal);
+
+    if (result?.status === "modified") {
+        configs.set(key, { etag: result.etag, config: result.config });
+        return result.config;
+    }
+    if (result?.status === "not-modified" && cached) return cached.config;
+    if (result?.status === "not-found") {
+        configs.delete(key);
+        return null;
+    }
+
+    console.warn(`Control Center config unavailable for agent "${agentId}"`);
+    return cached?.config ?? null;
+}

package/src/lib/cc/format.ts

@@ -0,0 +1,96 @@
+import type { ResolveResponse, RuntimeAgentConfig } from "./types";
+
+type SharedShape = ResolveResponse["sharedShapes"][number];
+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"],
+    sources: Record<string, unknown>,
+) {
+    const variables: Record<string, string> = {};
+    for (const name of promptVariables) {
+        const value = sources[name];
+        if (typeof value === "string") variables[name] = value;
+    }
+    return variables;
+}
+
+export function formatSharedShapes(shapes: SharedShape[]) {
+    return shapes.map((shape) => `${shape.ref}: ${shape.shape}`).join("\n");
+}
+
+export function formatToolSignatures(tools: ToolSignature[]) {
+    return tools.map((tool) => tool.signature).join("\n\n");
+}
+
+export function formatServiceCards(services: ServiceCard[]) {
+    return services.map((service) => service.card).join("\n\n");
+}
+
+export function formatKnowledgeChunks(chunks: KnowledgeChunk[]) {
+    return chunks.map(formatKnowledgeChunk).join("\n\n");
+}
+
+function formatKnowledgeChunk(chunk: KnowledgeChunk) {
+    const { citation } = chunk;
+    const source = [
+        citation.service,
+        citation.documentTitle,
+        citation.section,
+        citation.page === null ? null : `p. ${citation.page}`,
+    ]
+        .filter(Boolean)
+        .join(", ");
+    return `${chunk.text}\n[Source: ${source}]`;
+}
+
+export type CcPromptInput = {
+    config: RuntimeAgentConfig;
+    resolved: ResolveResponse | null;
+    variables: Record<string, string>;
+};
+
+/**
+ * Dumb concatenator by contract: `signature`, `card`, and `shape` arrive
+ * pre-rendered from Control Center and are injected verbatim — never
+ * re-rendered from structured fields.
+ */
+export function buildCcSection(cc: CcPromptInput) {
+    const parts: string[] = [];
+
+    const prompt = substitutePromptVariables(cc.config.systemPrompt, cc.variables).trim();
+    if (prompt) parts.push(prompt);
+
+    if (cc.config.catalogBlurb) {
+        parts.push(`## Capabilities\n${cc.config.catalogBlurb}`);
+    }
+
+    if (cc.resolved) {
+        if (cc.resolved.sharedShapes.length > 0) {
+            parts.push(`## Response Shapes\n${formatSharedShapes(cc.resolved.sharedShapes)}`);
+        }
+        if (cc.resolved.tools.length > 0) {
+            parts.push(
+                "## Dynamic Tools\nCall these from executeCode via the `tools` global, e.g. `await tools.name(input)`.\n\n" +
+                    formatToolSignatures(cc.resolved.tools),
+            );
+        }
+        if (cc.resolved.services.length > 0) {
+            parts.push(`## Services\n${formatServiceCards(cc.resolved.services)}`);
+        }
+        if (cc.resolved.knowledge.length > 0) {
+            parts.push(`## Knowledge\n${formatKnowledgeChunks(cc.resolved.knowledge)}`);
+        }
+    }
+
+    return parts.join("\n\n");
+}

package/src/lib/cc/registry.ts

@@ -0,0 +1,62 @@
+import type { ControlCenterClient } from "./client";
+import type { RuntimeAgentConfig } from "./types";
+
+export type CcToolBinding = {
+    toolId: string;
+    readOnly: boolean;
+};
+
+/**
+ * Turn-scoped and mutable: seeded from /resolve, extended by searchTools
+ * mid-turn so a tool discovered at step 3 is callable at step 4.
+ */
+export type CcToolRegistry = Map<string, CcToolBinding>;
+
+export function registerCcTools(
+    registry: CcToolRegistry,
+    tools: { name: string; toolId: string; readOnly: boolean }[],
+) {
+    for (const tool of tools) {
+        registry.set(tool.name, { toolId: tool.toolId, readOnly: tool.readOnly });
+    }
+}
+
+// Dynamic tools run inside the sandbox, so they never appear as message tool
+// parts — track invocations here to feed /resolve's hints.recentToolNames.
+// ponytail: in-memory per-thread recency, move to the DB if multi-instance matters
+const MAX_RECENT_TOOLS = 20;
+const MAX_TRACKED_THREADS = 1_000;
+const recentToolsByThread = new Map<string, string[]>();
+
+export function recordRecentCcTool(threadId: string, name: string) {
+    const recent = recentToolsByThread.get(threadId) ?? [];
+    const next = [name, ...recent.filter((n) => n !== name)].slice(0, MAX_RECENT_TOOLS);
+    recentToolsByThread.delete(threadId);
+    recentToolsByThread.set(threadId, next);
+
+    if (recentToolsByThread.size > MAX_TRACKED_THREADS) {
+        const oldest = recentToolsByThread.keys().next().value;
+        if (oldest !== undefined) recentToolsByThread.delete(oldest);
+    }
+}
+
+export function getRecentCcTools(threadId: string) {
+    return recentToolsByThread.get(threadId) ?? [];
+}
+
+/** Everything a CC-aware tool needs for one turn. */
+export type CcRuntime = {
+    client: ControlCenterClient;
+    agentId: string;
+    config: RuntimeAgentConfig;
+    registry: CcToolRegistry;
+    threadId: string;
+    turnKey: string;
+    userId: string;
+    locale: RuntimeAgentConfig["defaultLocale"];
+    endUserToken: string;
+    abortSignal?: AbortSignal;
+    getStepIndex: () => number;
+    nextCallIndex: (stepIndex: number) => number;
+    onToolProgress?: (toolName: string, toolCallId: string, status: "started" | "finished") => void;
+};

package/src/lib/cc/types.ts

@@ -0,0 +1,44 @@
+import z from "zod";
+import {
+    RUNTIME_ERROR_KINDS,
+    runtimeErrorSchema as strictRuntimeErrorSchema,
+} from "@cortex/contracts/runtime";
+
+export {
+    AGENT_SLUG_PATTERN,
+    executeResponseSchema,
+    resolveResponseSchema,
+    runtimeAgentConfigSchema,
+    searchKnowledgeResponseSchema,
+    searchServicesResponseSchema,
+    searchToolsResponseSchema,
+    type ExecuteRequest,
+    type ResolveRequest,
+    type ResolveResponse,
+    type RuntimeAgentConfig,
+    type SearchRequest,
+} from "@cortex/contracts/runtime";
+
+const knownRuntimeErrorKinds = new Set<string>(RUNTIME_ERROR_KINDS);
+
+/**
+ * The contract's error envelope, hardened for this consumer: a newer runtime may
+ * answer with an error kind this build has never heard of, which must degrade to a
+ * generic non-retryable `internal` rather than fail the parse.
+ */
+export const runtimeErrorSchema = z.preprocess(function normalizeUnknownErrorKind(value) {
+    if (typeof value !== "object" || value === null || !("error" in value)) return value;
+
+    const error = value.error;
+    if (typeof error !== "object" || error === null || !("kind" in error)) return value;
+    if (typeof error.kind === "string" && knownRuntimeErrorKinds.has(error.kind)) return value;
+
+    return {
+        ...value,
+        error: {
+            ...error,
+            kind: "internal",
+            retryable: false,
+        },
+    };
+}, strictRuntimeErrorSchema);