@m6d/cortex-cli 1.0.0

package/src/contracts/runtime.ts

@@ -0,0 +1,208 @@
+import { z } from "zod";
+
+/*
+ * The HTTP contract of the cortex-cc runtime API: the console (`apps/cortex-cc`)
+ * validates requests against these schemas and `@m6d/cortex-server` validates the
+ * responses it gets back. Request types use `z.input` because the callers build
+ * payloads the runtime's parser then fills defaults into.
+ */
+
+/** Runtime contract §1.1: the `:id` path param, validated on both sides of the wire. */
+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 RUNTIME_ERROR_KINDS = [
+    "timeout",
+    "upstream_4xx",
+    "upstream_5xx",
+    "schema_mismatch",
+    "rate_limited",
+    "not_found",
+    "unauthorized",
+    "invalid_request",
+    "egress_blocked",
+    "internal",
+] as const;
+
+/** The ways an execute output may disagree with the tool's declared schema. */
+export const JSON_SCHEMA_ISSUE_KINDS = ["missing", "unexpected", "type_mismatch"] as const;
+
+export const agentSlugSchema = z.string().regex(AGENT_SLUG_PATTERN);
+export const localeSchema = z.enum(["en", "ar"]);
+export const catalogVersionSchema = z.string().regex(/^[0-9a-f]{16}$/);
+
+export const sharedShapeSchema = z.object({
+    ref: z.string().regex(/^\$R\d+$/),
+    shape: z.string(),
+});
+
+export const knowledgeChunkSchema = z.object({
+    chunkId: z.uuid(),
+    text: z.string(),
+    score: z.number(),
+    citation: z.object({
+        documentId: z.uuid(),
+        documentTitle: z.string(),
+        page: z.number().int().positive().nullable(),
+        section: z.string().nullable(),
+        uri: z.url().nullable(),
+        service: z.string().nullable(),
+    }),
+});
+
+export const toolSignatureSchema = z.object({
+    toolId: z.uuid(),
+    name: z.string().regex(TOOL_NAME_PATTERN),
+    version: z.number().int().positive(),
+    readOnly: z.boolean(),
+    tags: z.array(z.string()),
+    signature: z.string(),
+    score: z.number().nullable(),
+    pinned: z.boolean(),
+});
+
+export const serviceCardSchema = z.object({
+    serviceId: z.uuid(),
+    key: z
+        .string()
+        .regex(/^[a-z0-9]+(-[a-z0-9]+)*$/)
+        .max(64),
+    name: z.string(),
+    card: z.string(),
+    score: z.number(),
+});
+
+export const runtimeAgentConfigSchema = z.object({
+    agentId: agentSlugSchema,
+    systemPrompt: z.string(),
+    promptVariables: z.array(z.enum(PROMPT_VARIABLES)),
+    catalogBlurb: z.string(),
+    defaultLocale: localeSchema,
+    metaTools: z.object({
+        searchKnowledge: z.boolean(),
+        searchTools: z.boolean(),
+        searchServices: z.boolean(),
+    }),
+    limits: z.object({
+        resolveTokenBudget: z.number().int().positive(),
+        executeTimeoutMs: z.number().int().positive(),
+        maxResponseBytes: z.number().int().positive(),
+    }),
+    catalogVersion: catalogVersionSchema,
+    publishedAt: z.iso.datetime(),
+});
+
+export const resolveRequestSchema = z.object({
+    query: z.string().trim().min(1).max(4000),
+    locale: localeSchema.optional(),
+    hints: z
+        .object({
+            threadId: z.string().max(128).optional(),
+            recentToolNames: z.array(z.string()).max(20).default([]),
+            turnIndex: z.number().int().min(0).optional(),
+        })
+        .optional(),
+    tokenBudget: z.number().int().min(500).max(20000).optional(),
+    limits: z
+        .object({
+            knowledge: z.number().int().min(0).max(20).default(6),
+            tools: z.number().int().min(0).max(20).default(8),
+            services: z.number().int().min(0).max(20).default(5),
+        })
+        .optional(),
+});
+
+export const resolveResponseSchema = z.object({
+    resolveId: z.uuid(),
+    catalogVersion: catalogVersionSchema,
+    locale: localeSchema,
+    knowledge: z.array(knowledgeChunkSchema),
+    tools: z.array(toolSignatureSchema),
+    services: z.array(serviceCardSchema),
+    sharedShapes: z.array(sharedShapeSchema),
+    budget: z.object({
+        requested: z.number().int(),
+        used: z.number().int(),
+        truncated: z.boolean(),
+    }),
+});
+
+export const searchRequestSchema = z.object({
+    query: z.string().trim().min(1).max(4000),
+    limit: z.number().int().min(1).max(20).default(5),
+    locale: localeSchema.optional(),
+    threadId: z.string().max(128).optional(),
+    service: z.string().max(64).optional(),
+});
+
+export const searchToolsResponseSchema = z.object({
+    catalogVersion: catalogVersionSchema,
+    tools: z.array(toolSignatureSchema),
+    sharedShapes: z.array(sharedShapeSchema),
+});
+
+export const searchServicesResponseSchema = z.object({
+    catalogVersion: catalogVersionSchema,
+    services: z.array(serviceCardSchema),
+    tools: z.array(toolSignatureSchema),
+    sharedShapes: z.array(sharedShapeSchema),
+});
+
+export const searchKnowledgeResponseSchema = z.object({
+    catalogVersion: catalogVersionSchema,
+    knowledge: z.array(knowledgeChunkSchema),
+});
+
+export const executeRequestSchema = z.object({
+    input: z.record(z.string(), z.unknown()).default({}),
+    context: z
+        .object({
+            threadId: z.string().max(128).optional(),
+            userId: z.string().max(128).optional(),
+            locale: localeSchema.optional(),
+        })
+        .optional(),
+});
+
+export const executeResponseSchema = z.object({
+    toolId: z.uuid(),
+    name: z.string(),
+    version: z.number().int().positive(),
+    output: z.unknown(),
+    meta: z.object({
+        upstreamStatus: z.number().int().min(100).max(599),
+        durationMs: z.number().int().min(0),
+        replayed: z.boolean(),
+        truncated: z.boolean(),
+        truncatedPaths: z.array(z.string()),
+        drift: z.array(
+            z.object({
+                path: z.string(),
+                kind: z.enum(JSON_SCHEMA_ISSUE_KINDS),
+            }),
+        ),
+    }),
+});
+
+const runtimeErrorKindSchema = z.enum(RUNTIME_ERROR_KINDS);
+export type RuntimeErrorKind = z.infer<typeof runtimeErrorKindSchema>;
+
+export const runtimeErrorSchema = z.object({
+    error: z.object({
+        kind: runtimeErrorKindSchema,
+        detail: z.string().max(512),
+        retryable: z.boolean(),
+        retryAfterSeconds: z.number().int().positive().optional(),
+        upstreamStatus: z.number().int().min(100).max(599).optional(),
+    }),
+});
+
+export type RuntimeAgentConfig = z.infer<typeof runtimeAgentConfigSchema>;
+export type ResolveRequest = z.input<typeof resolveRequestSchema>;
+export type ResolveResponse = z.infer<typeof resolveResponseSchema>;
+export type SearchRequest = z.input<typeof searchRequestSchema>;
+export type ExecuteRequest = z.input<typeof executeRequestSchema>;

package/src/contracts/wire.ts

@@ -0,0 +1,143 @@
+/**
+ * The wire contract — every shape that crosses the HTTP/WebSocket boundary
+ * between `@m6d/cortex-server` and the client SDKs (`@m6d/cortex-angular`,
+ * `@m6d/cortex-react`).
+ *
+ * Nothing here has a runtime dependency, and nothing here may grow one: this
+ * file is compiled into an Angular library, a React library and a Bun server
+ * alike.
+ */
+
+export const ATTACHMENT_MIME_TYPES = [
+    "image/png",
+    "image/jpeg",
+    "image/webp",
+    "application/pdf",
+] as const;
+
+export const ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024;
+
+export const MAX_ATTACHMENTS_PER_MESSAGE = 5;
+
+export const ATTACHMENT_STATUSES = ["pending", "described", "failed", "skipped"] as const;
+
+export function checkAttachmentPolicy(contentType: string, sizeBytes: number) {
+    if (!ATTACHMENT_MIME_TYPES.some((type) => type === contentType)) return "type";
+    if (sizeBytes > ATTACHMENT_MAX_BYTES) return "size";
+    return "ok";
+}
+
+export type AttachmentStatus = (typeof ATTACHMENT_STATUSES)[number];
+
+export type AttachmentSummary = {
+    id: string;
+    filename: string;
+    contentType: string;
+    sizeBytes: number;
+    status: AttachmentStatus;
+    description?: string;
+};
+
+export type ThreadSummary = {
+    id: string;
+    title?: string;
+    createdAt: string;
+    updatedAt: string;
+    isRunning: boolean;
+};
+
+/**
+ * Response of `POST /chat/:chatId/abort`. `aborted: false` means there was no
+ * live run to abort — the turn had already committed — so the caller must not
+ * present the turn as aborted and should read the settled state back instead.
+ */
+export type AbortRunResult = {
+    aborted: boolean;
+};
+
+export type TokenUsage = {
+    input: {
+        noCache: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+    output: {
+        reasoning: number;
+        text: number;
+        total: number;
+    };
+    total: number;
+};
+
+export type MessageMetadata = {
+    modelId?: string;
+    providerMetadata?: unknown;
+    isAborted?: boolean;
+    tokenUsage?: TokenUsage;
+    attachments?: AttachmentSummary[];
+};
+
+/**
+ * A stored message as it is persisted and served. TanStack AI's `UIMessage`
+ * has no metadata field, so cortex owns the envelope: the SDK's parts plus the
+ * server-derived metadata the UI renders on settled messages.
+ *
+ * `TPart` stays generic so this file keeps its zero dependencies — both
+ * sides substitute the SDK's `MessagePart`.
+ */
+export type CortexMessage<TPart = unknown> = {
+    id: string;
+    role: "system" | "user" | "assistant";
+    parts: TPart[];
+    metadata?: MessageMetadata;
+};
+
+export type ThreadCreatedEvent = {
+    type: "thread:created";
+    payload: { thread: ThreadSummary };
+};
+
+export type ThreadDeletedEvent = {
+    type: "thread:deleted";
+    payload: { threadId: string };
+};
+
+export type ThreadTitleUpdatedEvent = {
+    type: "thread:title-updated";
+    payload: { thread: ThreadSummary };
+};
+
+export type ThreadRunStartedEvent = {
+    type: "thread:run-started";
+    payload: { thread: ThreadSummary };
+};
+
+export type ThreadRunFinishedEvent = {
+    type: "thread:run-finished";
+    payload: { thread: ThreadSummary };
+};
+
+export type ThreadMessagesUpdatedEvent = {
+    type: "thread:messages-updated";
+    payload: { threadId: string; thread: ThreadSummary };
+};
+
+export type ToolProgressEvent = {
+    type: "thread:tool-progress";
+    payload: {
+        threadId: string;
+        toolCallId: string;
+        toolName: string;
+        status: "started" | "finished";
+    };
+};
+
+export type WsEvent =
+    | ThreadCreatedEvent
+    | ThreadDeletedEvent
+    | ThreadTitleUpdatedEvent
+    | ThreadRunStartedEvent
+    | ThreadRunFinishedEvent
+    | ThreadMessagesUpdatedEvent
+    | ToolProgressEvent;

package/src/graph/expand-domains.ts

@@ -0,0 +1,288 @@
+import type {
+    ConceptDef,
+    DomainDef,
+    EndpointDef,
+    RuleDef,
+    ServiceDef,
+} from "@cortex/contracts/graph";
+
+type DomainCollections = {
+    concepts: ConceptDef[];
+    endpoints: EndpointDef[];
+    services: ServiceDef[];
+    rules: RuleDef[];
+};
+
+type OwnershipMaps = {
+    concepts: WeakMap<ConceptDef, string>;
+    endpoints: WeakMap<EndpointDef, string>;
+    services: WeakMap<ServiceDef, string>;
+    rules: WeakMap<RuleDef, string>;
+};
+
+export function expandDomains(domains: Record<string, DomainDef>) {
+    const ownership = createOwnershipMaps(domains);
+    const expanded: Record<string, DomainDef> = {};
+
+    for (const [domainKey, domain] of Object.entries(domains)) {
+        const collections = cloneCollections(domain);
+        const pendingConcepts = [...collections.concepts];
+        const pendingEndpoints = [...collections.endpoints];
+        const pendingServices = [...collections.services];
+
+        while (
+            pendingConcepts.length > 0 ||
+            pendingEndpoints.length > 0 ||
+            pendingServices.length > 0
+        ) {
+            const concept = pendingConcepts.pop();
+            if (concept) {
+                includeConcept({
+                    domainKey,
+                    concept,
+                    ownership,
+                    collections,
+                    pendingConcepts,
+                    pendingEndpoints,
+                });
+            }
+
+            const endpoint = pendingEndpoints.pop();
+            if (endpoint) {
+                includeEndpoint({
+                    domainKey,
+                    endpoint,
+                    ownership,
+                    collections,
+                    pendingConcepts,
+                    pendingEndpoints,
+                });
+            }
+
+            const service = pendingServices.pop();
+            if (service) {
+                includeService({
+                    domainKey,
+                    service,
+                    ownership,
+                    collections,
+                    pendingConcepts,
+                });
+            }
+        }
+
+        expanded[domainKey] = {
+            ...domain,
+            concepts: collections.concepts,
+            endpoints: collections.endpoints,
+            services: collections.services,
+            rules: collections.rules,
+        };
+    }
+
+    return expanded;
+}
+
+function createOwnershipMaps(domains: Record<string, DomainDef>) {
+    const ownership: OwnershipMaps = {
+        concepts: new WeakMap<ConceptDef, string>(),
+        endpoints: new WeakMap<EndpointDef, string>(),
+        services: new WeakMap<ServiceDef, string>(),
+        rules: new WeakMap<RuleDef, string>(),
+    };
+
+    for (const [domainKey, domain] of Object.entries(domains)) {
+        for (const concept of domain.concepts ?? []) {
+            assignOwner(ownership.concepts, concept, domainKey);
+        }
+
+        for (const endpoint of domain.endpoints ?? []) {
+            assignOwner(ownership.endpoints, endpoint, domainKey);
+        }
+
+        for (const service of domain.services ?? []) {
+            assignOwner(ownership.services, service, domainKey);
+        }
+
+        for (const rule of domain.rules ?? []) {
+            assignOwner(ownership.rules, rule, domainKey);
+        }
+    }
+
+    return ownership;
+}
+
+function assignOwner<T extends object>(owners: WeakMap<T, string>, value: T, domainKey: string) {
+    if (!owners.has(value)) {
+        owners.set(value, domainKey);
+    }
+}
+
+function cloneCollections(domain: DomainDef) {
+    return {
+        concepts: [...(domain.concepts ?? [])],
+        endpoints: [...(domain.endpoints ?? [])],
+        services: [...(domain.services ?? [])],
+        rules: [...(domain.rules ?? [])],
+    } satisfies DomainCollections;
+}
+
+function includeConcept(options: {
+    domainKey: string;
+    concept: ConceptDef;
+    ownership: OwnershipMaps;
+    collections: DomainCollections;
+    pendingConcepts: ConceptDef[];
+    pendingEndpoints: EndpointDef[];
+}) {
+    const { domainKey, concept, ownership, collections, pendingConcepts, pendingEndpoints } =
+        options;
+
+    includeRule(domainKey, concept.governedBy ?? [], ownership, collections);
+
+    if (shouldAttach(ownership.concepts, concept, domainKey)) {
+        pushUnique(collections.concepts, concept);
+    }
+
+    if (
+        concept.parentConcept &&
+        shouldAttach(ownership.concepts, concept.parentConcept, domainKey)
+    ) {
+        if (pushUnique(collections.concepts, concept.parentConcept)) {
+            pendingConcepts.push(concept.parentConcept);
+        }
+    }
+
+    for (const endpoint of collections.endpoints) {
+        if (referencesConcept(endpoint, concept)) {
+            includeEndpoint({
+                domainKey,
+                endpoint,
+                ownership,
+                collections,
+                pendingConcepts,
+                pendingEndpoints,
+            });
+        }
+    }
+}
+
+function includeEndpoint(options: {
+    domainKey: string;
+    endpoint: EndpointDef;
+    ownership: OwnershipMaps;
+    collections: DomainCollections;
+    pendingConcepts: ConceptDef[];
+    pendingEndpoints: EndpointDef[];
+}) {
+    const { domainKey, endpoint, ownership, collections, pendingConcepts, pendingEndpoints } =
+        options;
+
+    if (shouldAttach(ownership.endpoints, endpoint, domainKey)) {
+        pushUnique(collections.endpoints, endpoint);
+    }
+
+    includeRule(domainKey, endpoint.governedBy ?? [], ownership, collections);
+
+    // An endpoint reaches concepts three ways and other endpoints one way, but the
+    // handling is identical: take what this domain owns, and queue whatever is new.
+    collectOwned({
+        items: [
+            ...(endpoint.queries ?? []),
+            ...(endpoint.mutates ?? []),
+            ...(endpoint.returns ?? []).map((returned) => returned.concept),
+        ],
+        owners: ownership.concepts,
+        collection: collections.concepts,
+        pending: pendingConcepts,
+        domainKey,
+    });
+
+    collectOwned({
+        items: (endpoint.dependsOn ?? []).map((dependency) => dependency.endpoint),
+        owners: ownership.endpoints,
+        collection: collections.endpoints,
+        pending: pendingEndpoints,
+        domainKey,
+    });
+}
+
+/**
+ * Only what this domain owns is attached, and only the first sighting is queued —
+ * re-queueing something already collected would walk the graph forever.
+ */
+function collectOwned<T extends object>(options: {
+    items: T[];
+    owners: WeakMap<T, string>;
+    collection: T[];
+    pending: T[];
+    domainKey: string;
+}) {
+    const { items, owners, collection, pending, domainKey } = options;
+
+    for (const item of items) {
+        if (shouldAttach(owners, item, domainKey) && pushUnique(collection, item)) {
+            pending.push(item);
+        }
+    }
+}
+
+function includeService(options: {
+    domainKey: string;
+    service: ServiceDef;
+    ownership: OwnershipMaps;
+    collections: DomainCollections;
+    pendingConcepts: ConceptDef[];
+}) {
+    const { domainKey, service, ownership, collections, pendingConcepts } = options;
+
+    if (shouldAttach(ownership.services, service, domainKey)) {
+        pushUnique(collections.services, service);
+    }
+
+    includeRule(domainKey, service.governedBy ?? [], ownership, collections);
+
+    if (
+        shouldAttach(ownership.concepts, service.belongsTo, domainKey) &&
+        pushUnique(collections.concepts, service.belongsTo)
+    ) {
+        pendingConcepts.push(service.belongsTo);
+    }
+}
+
+function includeRule(
+    domainKey: string,
+    rules: readonly RuleDef[],
+    ownership: OwnershipMaps,
+    collections: DomainCollections,
+) {
+    for (const rule of rules) {
+        if (shouldAttach(ownership.rules, rule, domainKey)) {
+            pushUnique(collections.rules, rule);
+        }
+    }
+}
+
+function shouldAttach<T extends object>(owners: WeakMap<T, string>, value: T, domainKey: string) {
+    const owner = owners.get(value);
+    return owner == null || owner === domainKey;
+}
+
+function pushUnique<T extends object>(values: T[], value: T) {
+    if (values.includes(value)) {
+        return false;
+    }
+
+    values.push(value);
+    return true;
+}
+
+function referencesConcept(endpoint: EndpointDef, concept: ConceptDef) {
+    return (
+        endpoint.queries?.includes(concept) ||
+        endpoint.mutates?.includes(concept) ||
+        endpoint.returns?.some(function (returned) {
+            return returned.concept === concept;
+        })
+    );
+}