@m6d/cortex-cli 0.12.1 → 0.14.0

package/src/contracts/runtime/auth.ts

@@ -1,41 +0,0 @@
-import { z } from "zod";
-
-/*
- * How a server, or one agent on it, verifies the end user's token. One union
- * for every reader: a code config, an agent the Control Center created, and
- * the runtime config cc publishes. A `custom` verifier exists in code only,
- * so it is not part of this contract.
- */
-
-export const AUTH_JWT_SECRET_ALGORITHMS = ["HS256", "HS384", "HS512"] as const;
-
-const issuerSchema = z.string().trim().min(1).max(2048);
-/** When set, the token's `aud` must contain it, so a token minted for another audience under the same issuer cannot be replayed here. */
-const audienceSchema = z.string().trim().min(1).max(2048).optional();
-
-/** Asymmetric tokens: the issuer publishes its public keys at the JWKS URI. */
-export const jwksAuthSchema = z.object({
-    kind: z.literal("jwks"),
-    jwksUri: z.url(),
-    issuer: issuerSchema,
-    audience: audienceSchema,
-});
-
-/**
- * Symmetric tokens: the issuer and this server share the secret. At least
- * 32 characters, the JOSE minimum for HMAC keys; the algorithms are pinned
- * so a token signed another way is refused before the key is tried.
- */
-export const jwtSecretAuthSchema = z.object({
-    kind: z.literal("jwt-secret"),
-    secret: z.string().min(32),
-    algorithms: z.array(z.enum(AUTH_JWT_SECRET_ALGORITHMS)).min(1),
-    issuer: issuerSchema,
-    audience: audienceSchema,
-});
-
-export const publishedAuthSchema = z.discriminatedUnion("kind", [
-    jwksAuthSchema,
-    jwtSecretAuthSchema,
-]);
-export type PublishedAuth = z.infer<typeof publishedAuthSchema>;

package/src/contracts/runtime/grammar.ts

@@ -1,169 +0,0 @@
-import { z } from "zod";
-import {
-    LOCALES,
-    MEDIA_FORMS,
-    TOOL_SURFACES,
-    type Greeting,
-    type Suggestions,
-} from "../wire/index";
-
-/*
- * The grammar both sides of the runtime API share: identifier patterns, the
- * closed sets, and the small schemas every request and response is built from.
- */
-
-/** The agent slug path param, validated on both sides of the wire. */
-export const AGENT_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
-export const agentSlugSchema = z.string().regex(AGENT_SLUG_PATTERN);
-
-/**
- * An ASCII JavaScript identifier: what a tool name (a `tools.<name>()` sandbox
- * binding on the server) and a variable name must be, and what a rendered
- * signature prints bare rather than quoted.
- */
-export const IDENTIFIER_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
-
-/** Consumer-facing slugs: service keys, skill names, and trigger names share it. */
-export const SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
-export const slugSchema = z.string().regex(SLUG_PATTERN).max(64);
-
-export const localeSchema = z.enum(LOCALES);
-export const toolSurfaceSchema = z.enum(TOOL_SURFACES);
-export const mediaFormSchema = z.enum(MEDIA_FORMS);
-export const catalogVersionSchema = z.string().regex(/^[0-9a-f]{16}$/);
-export const sha256HexSchema = z.string().regex(/^[0-9a-f]{64}$/);
-
-/**
- * A variable the server fills per request: a session value, a request-context
- * value, or one the SDK computes. Declared once per server so the console
- * offers exactly what that server provides to the agents created on it, in
- * prompts and as tool input sources alike.
- */
-export const variableDeclarationSchema = z.object({
-    name: z.string().regex(IDENTIFIER_PATTERN).max(64),
-    description: z.string().max(500),
-    example: z.string().max(200),
-    /** Computed by the SDK per request (`utcTime`, `locale`); no session value can set it. */
-    computed: z.boolean(),
-});
-export type VariableDeclaration = z.infer<typeof variableDeclarationSchema>;
-
-/** Variable names a tool input or prompt reads. */
-export const boundVariablesSchema = z.array(variableDeclarationSchema.shape.name);
-
-/** A sandbox binding a piece of rich text mentions, so the turn can register it before the model reads the text. */
-export const mentionedToolSchema = z.object({
-    toolId: z.uuid(),
-    name: z.string().regex(IDENTIFIER_PATTERN),
-    readOnly: z.boolean(),
-    /** A tool that parks for approval is never a sandbox binding, mentioned or not. */
-    requiresApproval: z.boolean(),
-    variables: boundVariablesSchema,
-});
-
-/**
- * Variables the SDK itself fills for every agent, listed first in a server's
- * declaration so the console offers them like any consumer-declared one.
- */
-export const SDK_VARIABLES = [
-    {
-        name: "utcTime",
-        description: "Current time in UTC (ISO 8601)",
-        example: "2026-09-12T08:30:00Z",
-        computed: true,
-    },
-    {
-        name: "locale",
-        description: "Resolved locale of the session",
-        example: "ar",
-        computed: true,
-    },
-    {
-        name: "timezone",
-        description: "The user's IANA time zone, as the widget reports it",
-        example: "Asia/Riyadh",
-        computed: true,
-    },
-] as const satisfies ReadonlyArray<VariableDeclaration>;
-
-/**
- * The widget's landing-page prompt chips, per locale: a short title the chip
- * shows and the prompt it sends when clicked. Every source of them
- * (the Control Center agent row, a server-code override, the capabilities
- * handshake) stores this exact shape, so the widget never sees a blank or
- * unbounded chip whichever source won. Pure validation, no transforms: a
- * value that passes is served verbatim, so each source trims before it
- * stores.
- */
-export const SUGGESTION_LIMITS = { perLocale: 6, titleLength: 120, promptLength: 2000 } as const;
-const trimmedText = (max: number) =>
-    z
-        .string()
-        .min(1)
-        .max(max)
-        .refine((text) => text === text.trim(), "text has surrounding whitespace");
-export const suggestionsSchema = z.record(
-    localeSchema,
-    z
-        .array(
-            z.object({
-                title: trimmedText(SUGGESTION_LIMITS.titleLength),
-                prompt: trimmedText(SUGGESTION_LIMITS.promptLength),
-            }),
-        )
-        .max(SUGGESTION_LIMITS.perLocale),
-) satisfies z.ZodType<Suggestions>;
-
-/** One string per locale, at most 500 characters each; author copy the widget shows as is. */
-export const localizedTextSchema = z.record(localeSchema, z.string().max(500));
-
-export const GREETING_MAX_LENGTH = 200;
-/**
- * The blank-chat landing's headline per locale. Empty means the widget's
- * built-in default for that locale; like suggestions, served verbatim.
- */
-export const greetingSchema = z.record(
-    localeSchema,
-    z
-        .string()
-        .max(GREETING_MAX_LENGTH)
-        .refine((text) => text === text.trim(), "greeting has surrounding whitespace"),
-) satisfies z.ZodType<Greeting>;
-
-/**
- * The Control Center's id for a resolved agent. Servers echo it on reports
- * about that agent so they attach to it even if the slug or alias they used
- * later moves.
- */
-export const agentRefSchema = z.uuid();
-
-/**
- * Response header carrying the resolved agent's ref on every agent-scoped
- * runtime answer, errors included, so a server can attribute a request even
- * when the body is an error envelope. Absent only when no agent resolved.
- */
-export const AGENT_REF_HEADER = "X-CC-Agent-Ref";
-
-/**
- * The playground operator's stand-in for a test thread's session: a
- * URI-encoded JSON object of declared variable values, sent by cc's
- * playground beside `X-Cortex-Playground` and honoured only when that header
- * verifies. The server stores it as the thread's session on creation, so the
- * customer's `loadSessionData` (which never sees cc-minted tokens) is not
- * needed for prompts and tool sources to have values.
- */
-export const PLAYGROUND_SESSION_HEADER = "X-Cortex-Playground-Session";
-
-/** Sent by cc's playground; a server verifies it against cc's JWKS before honouring it. */
-export const PLAYGROUND_HEADER = "X-Cortex-Playground";
-
-/** The end user's bearer, forwarded verbatim by the server to cc and by cc to the tool's backend. */
-export const END_USER_TOKEN_HEADER = "X-End-User-Token";
-
-/** Execute idempotency: a server-minted key the runtime replays within its window. */
-export const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
-export const IDEMPOTENCY_KEY_PATTERN = /^[A-Za-z0-9._:-]{1,200}$/;
-
-/** Correlation id echoed on every runtime response. */
-export const REQUEST_ID_HEADER = "X-Request-Id";
-export const REQUEST_ID_MAX_LENGTH = 128;

package/src/contracts/runtime/index.ts

@@ -1,15 +0,0 @@
-/*
- * The contract between the cortex-cc console and `@m6d/cortex-server`:
- * the grammar they share, the runtime API cc serves, triggers in both
- * directions, and the fleet sync the server pushes.
- */
-export * from "./grammar";
-export * from "./auth";
-export * from "./api";
-export * from "./triggers";
-export * from "./models";
-export * from "./datasets";
-export * from "./dataset-sql";
-export * from "./dataset-sql-guide";
-export * from "./sync";
-export * from "./signature";

package/src/contracts/runtime/models.ts

@@ -1,50 +0,0 @@
-import { z } from "zod";
-
-/**
- * One level's pick of what a run talks to: a model a Control Center
- * provider lists, the reasoning effort sent with it, both, or neither. An
- * unset part inherits from the level above (trigger, then agent, then
- * server, then the server's code config). An effort carries down only as
- * far as the level that picked the model, and is sent only when that
- * model's provider lists it.
- */
-export const modelChoiceSchema = z
-    .object({
-        provider: z.string().min(1).nullable(),
-        model: z.string().min(1).nullable(),
-        effort: z.string().min(1).nullable(),
-    })
-    .refine((choice) => (choice.provider === null) === (choice.model === null), {
-        error: "A provider and its model are picked together.",
-    });
-export type ModelChoice = z.infer<typeof modelChoiceSchema>;
-
-/** A pick that inherits everything. */
-export const INHERIT_MODEL = {
-    provider: null,
-    model: null,
-    effort: null,
-} satisfies ModelChoice;
-
-/**
- * An OpenAI-compatible endpoint as a server calls it: cc resolves the key
- * from the provider's secret, and `efforts` are the values it accepts as
- * `reasoning_effort`.
- */
-export const modelProviderEndpointSchema = z.object({
-    baseURL: z.url(),
-    apiKey: z.string().min(1),
-    efforts: z.array(z.string().min(1)),
-});
-
-/**
- * The model picks a server needs to run one agent: its server's and the
- * agent's own (each trigger carries its own on its declaration), plus every
- * provider any of them names.
- */
-export const runtimeModelsSchema = z.object({
-    providers: z.record(z.string(), modelProviderEndpointSchema),
-    server: modelChoiceSchema,
-    agent: modelChoiceSchema,
-});
-export type RuntimeModels = z.infer<typeof runtimeModelsSchema>;

package/src/contracts/runtime/signature.ts

@@ -1,255 +0,0 @@
-import { isRecord } from "../json";
-import { IDENTIFIER_PATTERN } from "./grammar";
-
-/*
- * The one rendering of a dynamic tool the model sees, whichever side
- * produced it: Control Center renders its registry tools at resolve time,
- * `@m6d/cortex-server` renders an MCP server's tools at turn time, and both
- * land in the same "Dynamic Tools" prompt section. A TypeScript-like
- * signature over the tool's JSON Schema: the input typed field by field with
- * its description as a trailing comment, the response as the names of the
- * fields it carries (what a script reads off the result), never their types.
- */
-
-/** Past this nesting an object prints as `object`: deeper detail costs more prompt than it earns. */
-const MAX_DEPTH = 3;
-
-function propertyName(name: string) {
-    return IDENTIFIER_PATTERN.test(name) ? name : JSON.stringify(name);
-}
-
-function compactLine(value: string) {
-    return value.replace(/\s+/g, " ").trim();
-}
-
-function fieldComment(value: unknown) {
-    if (typeof value !== "string") return "";
-    return Array.from(compactLine(value)).slice(0, 80).join("");
-}
-
-/** The `required` names of an object schema, or none when it declares none. */
-export function requiredProperties(schema: unknown) {
-    return isRecord(schema) && Array.isArray(schema.required)
-        ? schema.required.filter((name): name is string => typeof name === "string")
-        : [];
-}
-
-/** Property names in the schema's `x-order` first, then the rest as declared. */
-export function orderedPropertyNames(schema: Record<string, unknown>) {
-    const properties = isRecord(schema.properties) ? schema.properties : {};
-    const order = Array.isArray(schema["x-order"])
-        ? schema["x-order"].filter(
-              (name): name is string => typeof name === "string" && name in properties,
-          )
-        : [];
-    return [...order, ...Object.keys(properties).filter((name) => !order.includes(name))];
-}
-
-const SCALAR_TYPES = new Set(["boolean", "number", "string"]);
-
-/**
- * Follows a local `$ref` (`#`, `#/$defs/x`, or `#/definitions/x`) to its
- * definition in the root document, keeping the keywords beside the ref (a
- * description, say), so a shared shape a converter hoisted (a tool's schema
- * rows) renders as its fields rather than `unknown`. A described ref comes out
- * of zod as a one-entry `allOf`, which reads the same. A recursive shape ends
- * where `MAX_DEPTH` ends it.
- */
-function resolver(root: unknown) {
-    function definition(pointer: string) {
-        if (pointer === "#") return root;
-        const parts = pointer.split("/");
-        const [, section, name] = parts;
-        const definitions =
-            isRecord(root) && (section === "$defs" || section === "definitions")
-                ? root[section]
-                : undefined;
-        return parts.length === 3 && isRecord(definitions) && name !== undefined
-            ? definitions[name]
-            : undefined;
-    }
-    return function resolve(schema: unknown): unknown {
-        if (!isRecord(schema)) return schema;
-        const { $ref, allOf, ...rest } = schema;
-        if (typeof $ref === "string") {
-            const target = definition($ref);
-            return isRecord(target) ? { ...target, ...rest } : target;
-        }
-        if (Array.isArray(allOf) && allOf.length === 1) {
-            const target = resolve(allOf[0]);
-            return isRecord(target) ? { ...target, ...rest } : target;
-        }
-        return schema;
-    };
-}
-
-type Resolve = ReturnType<typeof resolver>;
-
-function literalUnion(values: unknown[]) {
-    return values
-        .filter((value) => value === null || SCALAR_TYPES.has(typeof value))
-        .map((value) => JSON.stringify(value))
-        .join(" | ");
-}
-
-/** An object's fields one per line, each typed, marked optional, and commented from its description. */
-function inputObject(
-    schema: Record<string, unknown>,
-    resolve: Resolve,
-    depth: number,
-    indent: number,
-) {
-    if (depth >= MAX_DEPTH) return "object";
-    const properties = isRecord(schema.properties) ? schema.properties : {};
-    const required = new Set(requiredProperties(schema));
-    const fields = orderedPropertyNames(schema).map((name) => {
-        const child = resolve(properties[name]);
-        const comment = isRecord(child) ? fieldComment(child.description) : "";
-        return `${" ".repeat(indent + 2)}${propertyName(name)}${required.has(name) ? "" : "?"}: ${inputType(child, resolve, depth + 1, indent + 2)},${comment ? ` // ${comment}` : ""}`;
-    });
-    return fields.length > 0 ? `{\n${fields.join("\n")}\n${" ".repeat(indent)}}` : "{}";
-}
-
-function inputType(schema: unknown, resolve: Resolve, depth = 0, indent = 0): string {
-    schema = resolve(schema);
-    if (!isRecord(schema)) return "unknown";
-    if ("const" in schema && SCALAR_TYPES.has(typeof schema.const)) {
-        return JSON.stringify(schema.const);
-    }
-    if (Array.isArray(schema.enum) && schema.enum.length > 0) return literalUnion(schema.enum);
-    const variants = variantsOf(schema);
-    if (variants) {
-        const rendered = variants.map((variant) => inputType(variant, resolve, depth, indent));
-        return [...new Set(rendered)].join(" | ");
-    }
-    const type = primaryType(schema.type);
-    const nullable = allowsNull(schema.type) ? " | null" : "";
-    if (type === "null") return "null";
-    if (type === "array") {
-        const item = inputType(schema.items, resolve, depth + 1, indent);
-        // A union item type binds looser than `[]`, so it is parenthesized.
-        return `${item.includes(" | ") ? `(${item})` : item}[]${nullable}`;
-    }
-    if (type === "object" || isRecord(schema.properties)) {
-        return inputObject(schema, resolve, depth, indent) + nullable;
-    }
-    if (type === "integer") return `number${nullable}`;
-    return SCALAR_TYPES.has(String(type)) ? `${String(type)}${nullable}` : "unknown";
-}
-
-/** The non-null member of a JSON Schema `type`, so `["string", "null"]` reads as `string`. */
-function primaryType(type: unknown) {
-    if (!Array.isArray(type)) return type;
-    const members: unknown[] = type;
-    return members.find((member) => member !== "null");
-}
-
-function allowsNull(type: unknown) {
-    if (!Array.isArray(type)) return false;
-    const members: unknown[] = type;
-    return members.includes("null");
-}
-
-/** The branches of a union schema, under whichever keyword carries them. */
-function variantsOf(schema: Record<string, unknown>) {
-    const variants = [schema.oneOf, schema.anyOf].find(Array.isArray);
-    return variants && variants.length > 0 ? variants : undefined;
-}
-
-function isObjectSchema(schema: unknown): schema is Record<string, unknown> {
-    return (
-        isRecord(schema) && (primaryType(schema.type) === "object" || isRecord(schema.properties))
-    );
-}
-
-/**
- * A response schema as one shape: a union's object branches merged into the
- * fields any of them may carry, a `null` branch dropped. A script reads a
- * field off whichever branch came back, so the names are what matter.
- */
-function responseUnion(schema: unknown, resolve: Resolve): unknown {
-    const resolved = resolve(schema);
-    if (!isRecord(resolved)) return resolved;
-    const variants = variantsOf(resolved);
-    if (!variants) return resolved;
-    const branches = variants
-        .map((variant) => responseUnion(variant, resolve))
-        .filter(
-            (variant): variant is Record<string, unknown> =>
-                isRecord(variant) && variant.type !== "null",
-        );
-    const objects = branches.filter(isObjectSchema);
-    if (objects.length === 0) return branches[0];
-    const properties: Record<string, unknown> = {};
-    for (const object of objects) {
-        if (isRecord(object.properties)) Object.assign(properties, object.properties);
-    }
-    return { type: "object", properties };
-}
-
-function responseObject(schema: Record<string, unknown>, resolve: Resolve, depth = 0): string {
-    const properties = isRecord(schema.properties) ? schema.properties : {};
-    const fields = orderedPropertyNames(schema).map((name) => {
-        const child = responseUnion(properties[name], resolve);
-        if (!isRecord(child) || depth >= MAX_DEPTH) return propertyName(name);
-        if (primaryType(child.type) === "array") {
-            const items = responseUnion(child.items, resolve);
-            return isObjectSchema(items)
-                ? `${propertyName(name)}[].${responseObject(items, resolve, depth + 1)}`
-                : propertyName(name);
-        }
-        return isObjectSchema(child)
-            ? `${propertyName(name)}.${responseObject(child, resolve, depth + 1)}`
-            : propertyName(name);
-    });
-    return fields.length > 0 ? `{ ${fields.join(", ")} }` : "{}";
-}
-
-/**
- * The names a result carries, as a script would read them: `{ id, items[].{ name } }`.
- * A schema that describes no fields is `{}`, which is also what a tool that
- * declares no response gets; a caller that knows nothing passes `undefined`
- * and gets `unknown`, so the model does not mistake silence for emptiness.
- */
-export function responseShape(schema: unknown) {
-    if (schema === undefined) return "unknown";
-    const resolve = resolver(schema);
-    const root = responseUnion(schema, resolve);
-    if (!isRecord(root)) return "{}";
-    if (primaryType(root.type) === "array") {
-        const items = responseUnion(root.items, resolve);
-        return isObjectSchema(items) ? `[]${responseObject(items, resolve)}` : "[]";
-    }
-    return responseObject(root, resolve);
-}
-
-/** One line, no comment terminator, and always a sentence, so it can sit in the doc comment. */
-function summarize(description: string) {
-    const text = compactLine(description).replaceAll("*/", "* /");
-    if (!text) return "";
-    return /[.!?]$/.test(text) ? text : `${text}.`;
-}
-
-export type ToolSignatureInput = {
-    /** As the script calls it: a name dot access cannot reach renders as the index call `tools["a-b"]`. */
-    name: string;
-    description: string;
-    /** JSON Schema of the input object as the model should see it. */
-    inputSchema: unknown;
-    /** Already rendered (a shared-shape ref like `$R1`), or the JSON Schema to render, or undefined for "unknown". */
-    returns: string | { schema: unknown };
-    /** Appended to the summary; the caller knows what else the model should be told (idempotency, embedded flows). */
-    notes?: ReadonlyArray<string>;
-};
-
-/** `/** summary *\/\nname(input: {...}): { fields }`. */
-export function renderToolSignature(tool: ToolSignatureInput) {
-    const summary = [summarize(tool.description), ...(tool.notes ?? [])].filter(Boolean).join(" ");
-    const callee = IDENTIFIER_PATTERN.test(tool.name)
-        ? tool.name
-        : `tools[${JSON.stringify(tool.name)}]`;
-    const returns =
-        typeof tool.returns === "string" ? tool.returns : responseShape(tool.returns.schema);
-    const input = inputType(tool.inputSchema, resolver(tool.inputSchema));
-    return `${summary ? `/** ${summary} */\n` : ""}${callee}(input: ${input}): ${returns}`;
-}