@m6d/cortex-cli 0.1.0

package/src/contracts/runtime/api.ts

@@ -0,0 +1,328 @@
+import { z } from "zod";
+import {
+    agentRefSchema,
+    boundVariablesSchema,
+    catalogVersionSchema,
+    greetingSchema,
+    localeSchema,
+    localizedTextSchema,
+    mentionedToolSchema,
+    slugSchema,
+    suggestionsSchema,
+    TOOL_NAME_PATTERN,
+    toolSurfaceSchema,
+    variableDeclarationSchema,
+} from "./grammar";
+import { publishedAuthSchema } from "./auth";
+import { triggerDeclarationSchema } from "./triggers";
+import { datasetHostDeclarationSchema, datasetIdentifierSchema } from "./datasets";
+
+/*
+ * The cc runtime API (`/api/runtime/agents/:agentSlug/*`): the console
+ * 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.
+ */
+
+export const RUNTIME_ERROR_KINDS = [
+    "timeout",
+    "upstream_4xx",
+    "upstream_5xx",
+    "schema_mismatch",
+    "rate_limited",
+    "not_found",
+    "unauthorized",
+    "invalid_request",
+    "egress_blocked",
+    "internal",
+] as const;
+export const runtimeErrorKindSchema = z.enum(RUNTIME_ERROR_KINDS);
+export type RuntimeErrorKind = z.infer<typeof runtimeErrorKindSchema>;
+
+/** The HTTP status and default detail each error kind ships with; both sides rely on these exact values. */
+export const RUNTIME_ERRORS = {
+    invalid_request: { status: 400, detail: "invalid request", retryable: false },
+    unauthorized: { status: 401, detail: "unauthorized", retryable: false },
+    egress_blocked: { status: 422, detail: "egress blocked", retryable: false },
+    not_found: { status: 404, detail: "not found", retryable: false },
+    rate_limited: { status: 429, detail: "rate limited", retryable: true },
+    internal: { status: 500, detail: "internal error", retryable: true },
+    upstream_4xx: { status: 502, detail: "upstream request failed", retryable: false },
+    upstream_5xx: { status: 502, detail: "upstream request failed", retryable: true },
+    schema_mismatch: {
+        status: 502,
+        detail: "upstream response did not match the schema",
+        retryable: false,
+    },
+    timeout: { status: 504, detail: "request timed out", retryable: true },
+} as const satisfies Record<
+    RuntimeErrorKind,
+    { status: number; detail: string; retryable: boolean }
+>;
+
+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(),
+    }),
+});
+
+/** 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 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(),
+    }),
+});
+
+/**
+ * Present on signatures of `embedded` 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); the result the page reports
+ * back is relayed as-is, verifying it is the integrating backend's job.
+ */
+export const toolEmbedSchema = z.object({
+    surface: toolSurfaceSchema,
+    embedOrigin: z.url(),
+});
+export type ToolEmbed = z.infer<typeof toolEmbedSchema>;
+
+const toolSignatureBaseSchema = z.object({
+    toolId: z.uuid(),
+    name: z.string().regex(TOOL_NAME_PATTERN),
+    version: z.number().int().positive(),
+    readOnly: z.boolean(),
+    /**
+     * The call parks the run until the end user approves it. Declared to the
+     * model as a function call like an embedded tool, never as a sandbox
+     * binding, so the schema travels with it.
+     */
+    requiresApproval: z.boolean(),
+    /** The question the widget asks before an approval-gated call runs; only such tools carry one. */
+    approvalMessage: localizedTextSchema.optional(),
+    tags: z.array(z.string()),
+    signature: z.string(),
+    score: z.number().nullable(),
+    pinned: z.boolean(),
+    /** Variables the tool's input reads (`x-source` of kind `variable`); filled server-side, never seen by the model. */
+    variables: boundVariablesSchema,
+});
+
+/**
+ * A sandbox tool is described to the model by its rendered `signature`; a
+ * client tool is declared to the model as a function call, which needs the
+ * published input JSON Schema verbatim.
+ */
+export const toolSignatureSchema = z.union([
+    toolSignatureBaseSchema.extend({
+        embed: z.undefined().optional(),
+        inputSchema: z.record(z.string(), z.unknown()).optional(),
+    }),
+    toolSignatureBaseSchema.extend({
+        embed: toolEmbedSchema,
+        inputSchema: z.record(z.string(), z.unknown()),
+    }),
+]);
+export type ToolSignature = z.infer<typeof toolSignatureSchema>;
+
+/**
+ * One always-listed skill line. The description is the whole trigger: the
+ * model reads it every turn and calls `loadSkill` when it matches the task.
+ */
+export const skillLineSchema = z.object({
+    name: slugSchema,
+    description: z.string().max(500),
+});
+export type SkillLine = z.infer<typeof skillLineSchema>;
+
+export const serviceCardSchema = z.object({
+    serviceId: z.uuid(),
+    key: slugSchema,
+    name: z.string(),
+    card: z.string(),
+    score: z.number(),
+    /** Skills scoped to this service; listed only while the card is in context. */
+    skills: z.array(skillLineSchema),
+});
+
+/**
+ * A skill body served on `loadSkill`: mentions rendered to current names and
+ * headings demoted by the console, `{{variables}}` left for the server to
+ * fill per request. `mentionedTools` are the sandbox bindings the body
+ * refers to, so the turn can register them before the model acts on it.
+ */
+export const skillBodyResponseSchema = z.object({
+    name: z.string(),
+    body: z.string(),
+    mentionedTools: z.array(mentionedToolSchema),
+    /** Datasets the body mentions; the server lists them under the body so the model can query them at once. */
+    mentionedDatasets: z.array(datasetIdentifierSchema),
+    catalogVersion: catalogVersionSchema,
+});
+export type SkillBodyResponse = z.infer<typeof skillBodyResponseSchema>;
+
+export const runtimeAgentConfigSchema = z.object({
+    /**
+     * End-user token verification for this agent, managed by the agent's
+     * owner. Absent = the server's own auth default applies.
+     */
+    auth: publishedAuthSchema.optional(),
+    systemPrompt: z.string(),
+    /** Every declared variable the published prompt, skills, or triggers reference. */
+    promptVariables: z.array(variableDeclarationSchema.shape.name),
+    defaultLocale: localeSchema,
+    /**
+     * Whether end users may upload files to this agent. Operational config
+     * like `auth`: read from the agent row, so toggling applies without
+     * republishing. The runtime rejects new uploads when false; existing
+     * attachments stay downloadable and deletable.
+     */
+    attachmentsEnabled: z.boolean(),
+    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(),
+    }),
+    /** Unscoped published skills; service-scoped ones travel on their card. */
+    skills: z.array(skillLineSchema),
+    triggers: z.array(triggerDeclarationSchema),
+    /** Published dataset hosts with the exposed definitions as of their pinned manifest version. */
+    datasetHosts: z.array(datasetHostDeclarationSchema),
+    /** Whether end users may message this agent; false makes it headless. */
+    messageTrigger: z.boolean(),
+    /** Operational like `messageTrigger`: edited on the agent row without republishing. */
+    suggestions: suggestionsSchema,
+    /** Operational like `suggestions`. */
+    greeting: greetingSchema,
+    /** The resolved agent's id; reports about it carry this so they attach to it whatever the slug or alias later means. */
+    agentRef: agentRefSchema,
+    catalogVersion: catalogVersionSchema,
+    publishedAt: z.iso.datetime(),
+});
+export type RuntimeAgentConfig = z.infer<typeof runtimeAgentConfigSchema>;
+
+const retrievalQuerySchema = z.string().trim().min(1).max(4000);
+const threadIdSchema = z.string().max(128);
+
+export const resolveRequestSchema = z.object({
+    query: retrievalQuerySchema,
+    threadId: threadIdSchema,
+    /** Sandbox tools the thread called recently; resolve ranks them ahead of cold ones. */
+    recentToolNames: z.array(z.string()).max(20),
+    limits: z
+        .object({
+            knowledge: z.number().int().min(0).max(20),
+            tools: z.number().int().min(0).max(20),
+            services: z.number().int().min(0).max(20),
+            datasets: z.number().int().min(0).max(20).default(6),
+        })
+        .prefault({ knowledge: 6, tools: 8, services: 5, datasets: 6 }),
+});
+export type ResolveRequest = z.input<typeof resolveRequestSchema>;
+
+/** A dataset the turn should list: ranked in by the question, or pinned by the author. */
+export const resolvedDatasetSchema = z.object({
+    name: datasetIdentifierSchema,
+    score: z.number().nullable(),
+    pinned: z.boolean(),
+});
+
+export type ResolvedDataset = z.infer<typeof resolvedDatasetSchema>;
+
+export const resolveResponseSchema = z.object({
+    resolveId: z.uuid(),
+    catalogVersion: catalogVersionSchema,
+    locale: localeSchema,
+    knowledge: z.array(knowledgeChunkSchema),
+    tools: z.array(toolSignatureSchema),
+    services: z.array(serviceCardSchema),
+    /** One line each in the turn context; the definitions come from the config's dataset hosts. */
+    datasets: z.array(resolvedDatasetSchema),
+    sharedShapes: z.array(sharedShapeSchema),
+    budget: z.object({
+        requested: z.number().int(),
+        used: z.number().int(),
+        truncated: z.boolean(),
+    }),
+});
+export type ResolveResponse = z.infer<typeof resolveResponseSchema>;
+
+export const searchRequestSchema = z.object({
+    query: retrievalQuerySchema,
+    limit: z.number().int().min(1).max(20).default(5),
+    locale: localeSchema.optional(),
+    threadId: threadIdSchema.optional(),
+    service: slugSchema.optional(),
+});
+export type SearchRequest = z.input<typeof searchRequestSchema>;
+
+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()),
+    context: z.object({
+        threadId: threadIdSchema,
+        userId: z.string().max(128),
+        /** Values of the variables the tool's input reads; only those names travel. */
+        variables: z.record(z.string(), z.unknown()),
+    }),
+});
+export type ExecuteRequest = z.input<typeof executeRequestSchema>;
+
+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),
+            }),
+        ),
+    }),
+});

package/src/contracts/runtime/auth.ts

@@ -0,0 +1,41 @@
+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/dataset-sql-guide.ts

@@ -0,0 +1,67 @@
+/*
+ * What the model reads about the SQL subset: the grammar in one list, then
+ * statements it can copy, each over the shapes datasets commonly have. One
+ * text for the system prompt, the tool descriptions and the sandbox, so the
+ * three never disagree.
+ */
+
+/** Every statement in the guide, with the intent it answers; tests parse each one. */
+export const DATASET_SQL_EXAMPLES = [
+    {
+        intent: "share of a total per group, as a ratio of two aggregates",
+        sql: "SELECT pets.species, COUNT(*) AS orderCount, COUNT(*) FILTER (WHERE orders.status = 'cancelled') * 1.0 / COUNT(*) AS cancelledShare FROM orders LEFT JOIN pets ON orders.petId = pets.id GROUP BY pets.species ORDER BY cancelledShare DESC",
+    },
+    {
+        intent: "this year against last year in one row",
+        sql: "SELECT SUM(total) FILTER (WHERE EXTRACT(YEAR FROM placedAt) = EXTRACT(YEAR FROM CURRENT_DATE)) AS thisYear, SUM(total) FILTER (WHERE EXTRACT(YEAR FROM placedAt) = EXTRACT(YEAR FROM CURRENT_DATE) - 1) AS lastYear, thisYear / lastYear - 1 AS growth FROM orders",
+    },
+    {
+        intent: "the last 30 days",
+        sql: "SELECT COUNT(*) AS orderCount, SUM(total) AS revenue FROM orders WHERE placedAt >= CURRENT_DATE - INTERVAL '30 days'",
+    },
+    {
+        intent: "a monthly trend",
+        sql: "SELECT DATE_TRUNC('month', placedAt) AS month, COUNT(*) AS orderCount, SUM(total) AS revenue FROM orders GROUP BY month ORDER BY month",
+    },
+    {
+        intent: "the top 3 of each group",
+        sql: "SELECT customers.name, orders.total, orders.placedAt FROM orders LEFT JOIN customers ON orders.customerId = customers.id QUALIFY RANK() OVER (PARTITION BY orders.customerId ORDER BY orders.total DESC) <= 3",
+    },
+    {
+        intent: "value bands",
+        sql: "SELECT CASE WHEN total < 100 THEN 'small' WHEN total < 500 THEN 'mid' ELSE 'large' END AS band, COUNT(*) AS orderCount FROM orders GROUP BY band",
+    },
+    {
+        intent: "a match regardless of case",
+        sql: "SELECT id, name FROM customers WHERE LOWER(name) = 'alice'",
+    },
+    {
+        intent: "groups filtered and ordered by a computed share, rounded",
+        sql: "SELECT customerId, COUNT(*) AS orderCount, ROUND(COUNT(*) FILTER (WHERE status = 'cancelled') * 100.0 / COUNT(*), 1) AS cancelledPct FROM orders GROUP BY customerId HAVING cancelledPct > 20 ORDER BY cancelledPct DESC LIMIT 10",
+    },
+    {
+        intent: "each group's share of the total",
+        sql: "SELECT pets.species, COUNT(*) AS orderCount, COUNT(*) * 100.0 / SUM(COUNT(*)) OVER () AS sharePct FROM orders LEFT JOIN pets ON orders.petId = pets.id GROUP BY pets.species",
+    },
+    {
+        intent: "rows above their group's average",
+        sql: "SELECT id, customerId, total, AVG(total) OVER (PARTITION BY customerId) AS customerAvg FROM orders QUALIFY total > customerAvg",
+    },
+] as const;
+
+/** The grammar in one paragraph, as the tool descriptions and the prompt state it. */
+export const DATASET_SQL_GRAMMAR =
+    "One SELECT over one dataset. LEFT JOIN related datasets exactly as the dataset's description lists them (LEFT JOIN keeps rows without a match; JOIN or INNER JOIN drops them); reference dataset.column. " +
+    "SELECT: columns, DATE_TRUNC('unit', column), EXTRACT(part FROM column), CASE WHEN ... END, LOWER/UPPER/TRIM/LENGTH/ABS/ROUND/COALESCE, COUNT/SUM/AVG/MIN/MAX over a column or arithmetic each with an optional FILTER (WHERE ...), and named arithmetic between aggregates (SUM(a) / COUNT(*) AS avg). " +
+    "WHERE and HAVING: AND, OR, NOT, parentheses, comparisons with literals or other columns, IN, BETWEEN, LIKE, IS NULL; CURRENT_DATE and INTERVAL arithmetic on it. " +
+    "GROUP BY columns or select aliases. An aggregate with OVER () or OVER (PARTITION BY ...) is a window: that aggregate over the rows sharing the partition, on every row (SUM(COUNT(*)) OVER () is the grand total); name it AS, use it in arithmetic, and QUALIFY filters the finished rows. " +
+    "QUALIFY RANK() OVER (PARTITION BY ... ORDER BY ...) <= n for the top n per group (rows tied on every ORDER BY key share a rank and all stay); ORDER BY; LIMIT; OFFSET. " +
+    "Rows nest qualified columns under the qualifier as written (pets.name comes back as row.pets.name); aliases and aggregates are top-level.";
+
+/** The guide as the model reads it: the grammar, then the examples. */
+export function datasetSqlGuide() {
+    const examples = DATASET_SQL_EXAMPLES.map(
+        (example) => `-- ${example.intent}\n${example.sql}`,
+    ).join("\n");
+    return `${DATASET_SQL_GRAMMAR}\n\nExamples over three sample datasets (orders, pets, customers); query the datasets listed under Datasets:\n${examples}`;
+}