@m6d/cortex-server 1.8.0 → 2.0.1

package/dist/src/lib/ai/redis-stream-log.d.ts

@@ -0,0 +1,39 @@
+import type { Redis } from "ioredis";
+import type { StreamChunk } from "@tanstack/ai";
+/**
+ * Whether a client-supplied resume offset belongs to `runId`. The offset names
+ * the log it replays, so an offset naming another run would replay that run's
+ * log to whoever presents it — matching the prefix this adapter encodes is what
+ * binds a resume to the thread the caller owns.
+ */
+export declare function offsetBelongsToRun(offset: string, runId: string): boolean;
+type RedisStreamLogOptions = {
+    /** `null` builds a producer (appends flow into the log); an offset builds a reader. */
+    resumeOffset: string | null;
+    /** How long the log stays replayable after its last append or `close()`. */
+    streamTtlMs: number;
+    /** How long a reader waits for the run's first entry before failing. */
+    firstChunkDeadlineMs: number;
+    /**
+     * Whether the run's producer is still alive. While it is, a caught-up
+     * reader parks indefinitely between chunks — the producer owns termination.
+     * Once it reports dead with the log still unclosed, the run was orphaned
+     * (producer crashed before `close()`), and the read fails so the joiner
+     * gets a terminal error instead of tailing forever.
+     */
+    isLive?: () => Promise<boolean>;
+};
+export declare function redisStreamLog(redis: Redis, runId: string, options: RedisStreamLogOptions): {
+    resumeFrom: () => string | null;
+    append: (chunks: import("@tanstack/ai").AGUIEvent[]) => Promise<string[]>;
+    snapshot: () => Promise<{
+        offset: string;
+        chunk: StreamChunk;
+    }[]>;
+    close: () => Promise<void>;
+    read: (offset: string, signal?: AbortSignal) => AsyncGenerator<{
+        offset: string;
+        chunk: StreamChunk;
+    }, void, any>;
+};
+export {};

package/dist/src/lib/ai/tools/execute-code.tool.d.ts

@@ -1,4 +1,18 @@
-import type { ResolvedCortexAgentConfig } from "../../config.ts";
-export declare function createExecuteCodeTool(backendFetch: NonNullable<ResolvedCortexAgentConfig["backendFetch"]>, token: string): import("ai").Tool<{
-    code: string;
-}, string>;
+import z from "zod";
+import type { ResolvedCortexAgentConfig } from "../../config";
+import type { CcRuntime } from "../../cc/registry";
+export type ExecuteCodeToolOptions = {
+    backendFetch?: NonNullable<ResolvedCortexAgentConfig["backendFetch"]>;
+    attachmentSentinels?: boolean;
+    token: string;
+    cc?: CcRuntime;
+};
+export declare function createExecuteCodeTool(options: ExecuteCodeToolOptions): import("@tanstack/ai").ServerTool<z.ZodObject<{
+    code: z.ZodString;
+}, z.core.$strip>, undefined, "executeCode", unknown, false, undefined> & {
+    inputSchema: z.ZodObject<{
+        code: z.ZodString;
+    }, z.core.$strip>;
+    outputSchema: undefined;
+    approvalSchema: undefined;
+};

package/dist/src/lib/ai/tools/query-graph.tool.d.ts

@@ -1,5 +1,13 @@
-import type { Neo4jClient } from "../../graph/neo4j.ts";
-export declare function createQueryGraphTool(neo4j: Neo4jClient): import("ai").Tool<{
-    query: string;
-    parameters?: string | undefined;
-}, string>;
+import z from "zod";
+import type { Neo4jClient } from "../../../../contracts/graph";
+export declare function createQueryGraphTool(neo4j: Neo4jClient): import("@tanstack/ai").ServerTool<z.ZodObject<{
+    query: z.ZodString;
+    parameters: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, undefined, "queryGraph", unknown, false, undefined> & {
+    inputSchema: z.ZodObject<{
+        query: z.ZodString;
+        parameters: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    outputSchema: undefined;
+    approvalSchema: undefined;
+};

package/dist/src/lib/ai/tools/read-attachment.tool.d.ts

@@ -0,0 +1,21 @@
+import z from "zod";
+import type { ResolvedCortexAgentConfig } from "../../config";
+type ReadAttachmentToolOptions = {
+    db: ResolvedCortexAgentConfig["db"];
+    storage: NonNullable<ResolvedCortexAgentConfig["storage"]>;
+    vision: NonNullable<ResolvedCortexAgentConfig["vision"]>;
+    threadId: string;
+    userId: string;
+};
+export declare function createReadAttachmentTool(options: ReadAttachmentToolOptions): import("@tanstack/ai").ServerTool<z.ZodObject<{
+    attachmentId: z.ZodString;
+    query: z.ZodString;
+}, z.core.$strip>, undefined, "readAttachment", unknown, false, undefined> & {
+    inputSchema: z.ZodObject<{
+        attachmentId: z.ZodString;
+        query: z.ZodString;
+    }, z.core.$strip>;
+    outputSchema: undefined;
+    approvalSchema: undefined;
+};
+export {};

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

@@ -0,0 +1,17 @@
+import z from "zod";
+import type { CcRuntime } from "../../cc/registry";
+/** The input shape all three catalog search tools share; only the query hint differs. */
+export declare function searchInputSchema(queryDescription: string): z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** The runtime search request those tools send: the model's input plus the turn's context. */
+export declare function searchRequest(cc: CcRuntime, input: {
+    query: string;
+    limit?: number;
+}): {
+    locale: "ar" | "en";
+    threadId: string;
+    query: string;
+    limit?: number;
+};

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

@@ -0,0 +1,15 @@
+import z from "zod";
+import type { CcRuntime } from "../../cc/registry";
+export declare function createSearchKnowledgeTool(cc: CcRuntime): import("@tanstack/ai").ServerTool<z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodOptional<z.ZodNumber>;
+    service: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, undefined, "searchKnowledge", unknown, false, undefined> & {
+    inputSchema: z.ZodObject<{
+        query: z.ZodString;
+        limit: z.ZodOptional<z.ZodNumber>;
+        service: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    outputSchema: undefined;
+    approvalSchema: undefined;
+};

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

@@ -0,0 +1,12 @@
+import type { CcRuntime } from "../../cc/registry";
+export declare function createSearchServicesTool(cc: CcRuntime): import("@tanstack/ai").ServerTool<import("zod").ZodObject<{
+    query: import("zod").ZodString;
+    limit: import("zod").ZodOptional<import("zod").ZodNumber>;
+}, import("zod/v4/core").$strip>, undefined, "searchServices", unknown, false, undefined> & {
+    inputSchema: import("zod").ZodObject<{
+        query: import("zod").ZodString;
+        limit: import("zod").ZodOptional<import("zod").ZodNumber>;
+    }, import("zod/v4/core").$strip>;
+    outputSchema: undefined;
+    approvalSchema: undefined;
+};

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

@@ -0,0 +1,12 @@
+import type { CcRuntime } from "../../cc/registry";
+export declare function createSearchToolsTool(cc: CcRuntime): import("@tanstack/ai").ServerTool<import("zod").ZodObject<{
+    query: import("zod").ZodString;
+    limit: import("zod").ZodOptional<import("zod").ZodNumber>;
+}, import("zod/v4/core").$strip>, undefined, "searchTools", unknown, false, undefined> & {
+    inputSchema: import("zod").ZodObject<{
+        query: import("zod").ZodString;
+        limit: import("zod").ZodOptional<import("zod").ZodNumber>;
+    }, import("zod/v4/core").$strip>;
+    outputSchema: undefined;
+    approvalSchema: undefined;
+};

package/dist/src/lib/ai/turn-tools.d.ts

@@ -0,0 +1,39 @@
+import type { AnyServerTool } from "@tanstack/ai";
+import type { ResolvedCortexAgentConfig } from "../config";
+import type { Attachment, Thread } from "../types";
+import type { CcRuntime } from "../cc/registry";
+import type { Neo4jClient } from "../../../contracts/graph";
+type TurnToolsOptions = {
+    config: ResolvedCortexAgentConfig;
+    cc: CcRuntime | undefined;
+    neo4j: Neo4jClient | undefined;
+    thread: Thread;
+    userId: string;
+    token: string;
+    session: Record<string, unknown> | null;
+    requestContext: Record<string, unknown>;
+    threadAttachments: Attachment[];
+};
+/**
+ * Assembles the tool set for one turn: built-ins gated on what the agent has
+ * configured, then the agent's own tools.
+ *
+ * User tools are appended last and deliberately win on name collision — an agent
+ * must be able to replace a built-in it doesn't want.
+ */
+export declare function buildTurnTools(options: TurnToolsOptions): AnyServerTool[];
+/**
+ * Instruments tool calls for the callbacks an agent configured. Returns
+ * `undefined` when nothing is listening, so the caller can skip the middleware
+ * entirely.
+ */
+export declare function createToolInstrumentation(options: TurnToolsOptions & {
+    onToolStart: (toolName: string, toolCallId: string) => void;
+    onToolFinish: (toolName: string, toolCallId: string) => void;
+}): {
+    name: string;
+    onBeforeToolCall(_ctx: import("@tanstack/ai").ChatMiddlewareContext<unknown>, { toolName, toolCallId, args }: import("@tanstack/ai").ToolCallHookContext): void;
+    onAfterToolCall(_ctx: import("@tanstack/ai").ChatMiddlewareContext<unknown>, { toolName, toolCallId }: import("@tanstack/ai").AfterToolCallInfo): void;
+} | undefined;
+export declare function hasDefaultAttachmentInterceptor(config: ResolvedCortexAgentConfig): boolean;
+export {};

package/dist/src/lib/ai/vision/rasterize-pdf.d.ts

@@ -0,0 +1,26 @@
+export type RasterizedPdf = {
+    pages: {
+        data: Uint8Array;
+        width: number;
+        height: number;
+    }[];
+    totalPages: number;
+    truncatedBy?: "page-limit" | "payload-limit";
+};
+export type RasterizePdfWorkerRequest = {
+    bytes: Uint8Array;
+    maxPayloadBytes?: number;
+};
+export type RasterizePdfWorkerResponse = {
+    status: "success";
+    result: RasterizedPdf;
+} | {
+    status: "error";
+    message: string;
+};
+type RasterizePdfOptions = {
+    abortSignal?: AbortSignal;
+    maxPayloadBytes?: number;
+};
+export declare function rasterizePdf(bytes: Uint8Array, options?: RasterizePdfOptions): Promise<RasterizedPdf>;
+export {};

package/dist/src/lib/ai/vision/rasterize-pdf.worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/ai/vision/vision-reader.d.ts

@@ -0,0 +1,45 @@
+import type { ResolvedCortexAgentConfig } from "../../config";
+type VisionConfig = NonNullable<ResolvedCortexAgentConfig["vision"]>;
+export declare function describeAttachment(vision: VisionConfig, contentType: string, base64: string, abortSignal?: AbortSignal): Promise<{
+    status: "skipped";
+    error?: undefined;
+    text?: undefined;
+    note?: undefined;
+} | {
+    status: "failed";
+    error: string;
+    text?: undefined;
+    note?: undefined;
+} | {
+    status: "success";
+    text: string;
+    note: string;
+    error?: undefined;
+} | {
+    status: "failed";
+    error?: undefined;
+    text?: undefined;
+    note?: undefined;
+}>;
+export declare function answerQuestionAbout(vision: VisionConfig, contentType: string, base64: string, query: string, abortSignal?: AbortSignal): Promise<{
+    status: "skipped";
+    error?: undefined;
+    text?: undefined;
+    note?: undefined;
+} | {
+    status: "failed";
+    error: string;
+    text?: undefined;
+    note?: undefined;
+} | {
+    status: "success";
+    text: string;
+    note: string;
+    error?: undefined;
+} | {
+    status: "failed";
+    error?: undefined;
+    text?: undefined;
+    note?: undefined;
+}>;
+export {};

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

@@ -0,0 +1,183 @@
+import type { ControlCenterConfig } from "../config";
+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;
+};
+export declare class ControlCenterClient {
+    readonly url: string;
+    readonly cacheKey: string;
+    private readonly apiKey;
+    private readonly fetcher;
+    constructor(config: ControlCenterConfig, fetcher?: ControlCenterFetch);
+    getConfig(agentId: string, etag?: string, abortSignal?: AbortSignal): Promise<{
+        readonly status: "not-modified";
+        readonly config?: undefined;
+        readonly etag?: undefined;
+    } | {
+        readonly status: "not-found";
+        readonly config?: undefined;
+        readonly etag?: undefined;
+    } | {
+        readonly status: "modified";
+        readonly config: {
+            agentId: string;
+            systemPrompt: string;
+            promptVariables: ("userName" | "channel" | "locale" | "utcTime" | "timezone")[];
+            catalogBlurb: string;
+            defaultLocale: "ar" | "en";
+            metaTools: {
+                searchKnowledge: boolean;
+                searchTools: boolean;
+                searchServices: boolean;
+            };
+            limits: {
+                resolveTokenBudget: number;
+                executeTimeoutMs: number;
+                maxResponseBytes: number;
+            };
+            catalogVersion: string;
+            publishedAt: string;
+        };
+        readonly etag: string | null;
+    } | null>;
+    resolve(agentId: string, request: ResolveRequest, abortSignal?: AbortSignal): Promise<{
+        resolveId: string;
+        catalogVersion: string;
+        locale: "ar" | "en";
+        knowledge: {
+            chunkId: string;
+            text: string;
+            score: number;
+            citation: {
+                documentId: string;
+                documentTitle: string;
+                page: number | null;
+                section: string | null;
+                uri: string | null;
+                service: string | null;
+            };
+        }[];
+        tools: {
+            toolId: string;
+            name: string;
+            version: number;
+            readOnly: boolean;
+            tags: string[];
+            signature: string;
+            score: number | null;
+            pinned: boolean;
+        }[];
+        services: {
+            serviceId: string;
+            key: string;
+            name: string;
+            card: string;
+            score: number;
+        }[];
+        sharedShapes: {
+            ref: string;
+            shape: string;
+        }[];
+        budget: {
+            requested: number;
+            used: number;
+            truncated: boolean;
+        };
+    } | null>;
+    searchTools(agentId: string, request: SearchRequest, abortSignal?: AbortSignal): Promise<{
+        catalogVersion: string;
+        tools: {
+            toolId: string;
+            name: string;
+            version: number;
+            readOnly: boolean;
+            tags: string[];
+            signature: string;
+            score: number | null;
+            pinned: boolean;
+        }[];
+        sharedShapes: {
+            ref: string;
+            shape: string;
+        }[];
+    } | null>;
+    searchServices(agentId: string, request: SearchRequest, abortSignal?: AbortSignal): Promise<{
+        catalogVersion: string;
+        services: {
+            serviceId: string;
+            key: string;
+            name: string;
+            card: string;
+            score: number;
+        }[];
+        tools: {
+            toolId: string;
+            name: string;
+            version: number;
+            readOnly: boolean;
+            tags: string[];
+            signature: string;
+            score: number | null;
+            pinned: boolean;
+        }[];
+        sharedShapes: {
+            ref: string;
+            shape: string;
+        }[];
+    } | null>;
+    searchKnowledge(agentId: string, request: SearchRequest, abortSignal?: AbortSignal): Promise<{
+        catalogVersion: string;
+        knowledge: {
+            chunkId: string;
+            text: string;
+            score: number;
+            citation: {
+                documentId: string;
+                documentTitle: string;
+                page: number | null;
+                section: string | null;
+                uri: string | null;
+                service: string | null;
+            };
+        }[];
+    } | null>;
+    execute(agentId: string, toolId: string, request: ExecuteRequest, options: ExecuteOptions): Promise<{
+        error: {
+            kind: "timeout" | "upstream_4xx" | "upstream_5xx" | "schema_mismatch" | "rate_limited" | "not_found" | "unauthorized" | "invalid_request" | "egress_blocked" | "internal";
+            detail: string;
+            retryable: boolean;
+            retryAfterSeconds?: number | undefined;
+            upstreamStatus?: number | undefined;
+        };
+    } | {
+        toolId: string;
+        name: string;
+        version: number;
+        output: unknown;
+        meta: {
+            upstreamStatus: number;
+            durationMs: number;
+            replayed: boolean;
+            truncated: boolean;
+            truncatedPaths: string[];
+            drift: {
+                path: string;
+                kind: "missing" | "unexpected" | "type_mismatch";
+            }[];
+        };
+    } | null>;
+    private agentPath;
+    private post;
+    private postResponse;
+    private request;
+    private parse;
+}
+export {};

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

@@ -0,0 +1,20 @@
+import type { ControlCenterClient } from "./client";
+export declare function getControlCenterConfig(cc: ControlCenterClient, agentId: string, abortSignal?: AbortSignal): Promise<{
+    agentId: string;
+    systemPrompt: string;
+    promptVariables: ("userName" | "channel" | "locale" | "utcTime" | "timezone")[];
+    catalogBlurb: string;
+    defaultLocale: "ar" | "en";
+    metaTools: {
+        searchKnowledge: boolean;
+        searchTools: boolean;
+        searchServices: boolean;
+    };
+    limits: {
+        resolveTokenBudget: number;
+        executeTimeoutMs: number;
+        maxResponseBytes: number;
+    };
+    catalogVersion: string;
+    publishedAt: string;
+} | null>;

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

@@ -0,0 +1,23 @@
+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];
+/** Values for the published prompt's `{{variable}}` placeholders, read from session/request context. */
+export declare function buildPromptVariables(promptVariables: RuntimeAgentConfig["promptVariables"], sources: Record<string, unknown>): Record<string, string>;
+export declare function formatSharedShapes(shapes: SharedShape[]): string;
+export declare function formatToolSignatures(tools: ToolSignature[]): string;
+export declare function formatServiceCards(services: ServiceCard[]): string;
+export declare function formatKnowledgeChunks(chunks: KnowledgeChunk[]): string;
+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 declare function buildCcSection(cc: CcPromptInput): string;
+export {};

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

@@ -0,0 +1,34 @@
+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 declare function registerCcTools(registry: CcToolRegistry, tools: {
+    name: string;
+    toolId: string;
+    readOnly: boolean;
+}[]): void;
+export declare function recordRecentCcTool(threadId: string, name: string): void;
+export declare function getRecentCcTools(threadId: string): string[];
+/** 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/dist/src/lib/cc/types.d.ts

@@ -0,0 +1,27 @@
+import z from "zod";
+export { AGENT_SLUG_PATTERN, executeResponseSchema, resolveResponseSchema, runtimeAgentConfigSchema, searchKnowledgeResponseSchema, searchServicesResponseSchema, searchToolsResponseSchema, type ExecuteRequest, type ResolveRequest, type ResolveResponse, type RuntimeAgentConfig, type SearchRequest, } from "../../../contracts/runtime";
+/**
+ * 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 declare const runtimeErrorSchema: z.ZodPreprocess<z.ZodObject<{
+    error: z.ZodObject<{
+        kind: z.ZodEnum<{
+            timeout: "timeout";
+            upstream_4xx: "upstream_4xx";
+            upstream_5xx: "upstream_5xx";
+            schema_mismatch: "schema_mismatch";
+            rate_limited: "rate_limited";
+            not_found: "not_found";
+            unauthorized: "unauthorized";
+            invalid_request: "invalid_request";
+            egress_blocked: "egress_blocked";
+            internal: "internal";
+        }>;
+        detail: z.ZodString;
+        retryable: z.ZodBoolean;
+        retryAfterSeconds: z.ZodOptional<z.ZodNumber>;
+        upstreamStatus: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>>;