@m6d/cortex-cli 0.8.0 → 0.9.0

package/README.md

@@ -44,8 +44,8 @@ hard error rather than a hang.
 | `--control-center` / `--no-control-center` | off        | `controlCenter`                                                           |
 | `--yes`                                    |            | Accept the defaults instead of asking                                     |
 
-Unselected features are still written to `cortex.config.ts`, commented out, alongside `fastModel`,
-`reranker`, and `context` — the generated config documents what else exists. Every credential and
+Unselected features are still written to `cortex.config.ts`, commented out, alongside `reranker`
+and `context` — the generated config documents what else exists. Every credential and
 URL is a placeholder in `.env`; none of them is prompted for.
 
 ## `cortex swagger sync` / `check`

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@m6d/cortex-cli",
-    "version": "0.8.0",
+    "version": "0.9.0",
     "description": "Scaffold and operate Cortex servers",
     "license": "MIT",
     "type": "module",

package/src/contracts/charts/chart-spec.ts

@@ -1,6 +1,6 @@
 /*
  * The boundary on a Vega-Lite spec the model wrote, shared by the widget
- * (which draws it live) and, as needed, the server:
+ * (which draws it live) and the server (which describes it to the model):
  * inline data only, no fetches, no interactivity, bounded work.
  */
 
@@ -18,6 +18,9 @@ const EXPANDING_TRANSFORMS = new Set([
     "sample",
 ]);
 
+/** The boundary as the model reads it in its system prompt, so it writes specs this file accepts. */
+export const CHART_SPEC_GUIDE = `Use Vega-Lite JSON with inline \`data.values\` only, at most ${MAX_CHART_ROWS} rows, and no \`url\` anywhere. Compute folds, trend lines and densities yourself. For several series, write one row per series and x value, or keep one row per x value and draw a layer per series (color by \`datum\`) when that would exceed the row limit. These keys are refused anywhere in the spec: ${[...EXPANDING_TRANSFORMS, "params", "selection"].join(", ")}. Expressions in \`calculate\`, \`filter\` and \`labelExpr\` may use only datum fields, literals, operators and simple math or date-part functions (no format or timeFormat), so put formatted values in the rows or use an axis \`format\`.`;
+
 /** What a single key or value in a chart spec may not be; undefined when it is fine on its own. */
 function chartNodeViolation(key: string, value: unknown) {
     if (key === "url") return "Charts may only use inline data and no URLs.";

package/src/contracts/charts/index.ts

@@ -1,4 +1,5 @@
 export {
+    CHART_SPEC_GUIDE,
     chartSpecViolation,
     externalResourceIn,
     IMAGE_FUNCTION,

package/src/contracts/runtime/api.ts

@@ -14,6 +14,7 @@ import {
     variableDeclarationSchema,
 } from "./grammar";
 import { publishedAuthSchema } from "./auth";
+import { runtimeModelsSchema } from "./models";
 import { triggerDeclarationSchema } from "./triggers";
 import { datasetHostDeclarationSchema, datasetIdentifierSchema } from "./datasets";
 
@@ -216,6 +217,12 @@ export const runtimeAgentConfigSchema = z.object({
     suggestions: suggestionsSchema,
     /** Operational like `suggestions`. */
     greeting: greetingSchema,
+    /**
+     * The model picks of the agent's server and of the agent, with the
+     * providers they and the agent's triggers name. Operational like
+     * `greeting`: edited without republishing.
+     */
+    models: runtimeModelsSchema,
     /** 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,

package/src/contracts/runtime/index.ts

@@ -7,6 +7,7 @@ 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";

package/src/contracts/runtime/models.ts

@@ -0,0 +1,50 @@
+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/triggers.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { datasetIdentifierSchema } from "./datasets";
+import { modelChoiceSchema } from "./models";
 import {
     agentRefSchema,
     agentSlugSchema,
@@ -20,6 +21,9 @@ import {
 
 export const MESSAGE_TRIGGER_NAME = "message";
 
+/** The tool a trigger run with an output schema answers through; no other tool may take its name. */
+export const TRIGGER_ANSWER_TOOL_NAME = "submitAnswer";
+
 /**
  * The first characters of a fire bearer say what it is: the secret callers
  * hold, or a one-shot test token the console minted. A test token is a JWT
@@ -98,9 +102,10 @@ export const triggerDeclarationSchema = z.object({
     input: z.record(z.string(), z.unknown()),
     /**
      * JSON Schema the run's answer must match, or null for a free-text run.
-     * The server asks the model for that shape, validates what comes back,
-     * and stores it as the firing's `output`; a run whose answer does not
-     * parse fails with reason `invalid_output`.
+     * The run submits it through an answer tool whose input is this schema,
+     * and the server stores it as the firing's `output`; a run that never
+     * submits fails with `no_output`, one whose answers the schema refused
+     * with `invalid_output`.
      */
     output: z.record(z.string(), z.unknown()).nullable(),
     /**
@@ -118,6 +123,8 @@ export const triggerDeclarationSchema = z.object({
     /** Consecutive failed or rejected firings before the trigger disables itself. */
     disableAfterFailures: z.number().int().positive(),
     hasCredential: z.boolean(),
+    /** What runs of this trigger talk to, over the agent's pick; read live like the credential. */
+    modelChoice: modelChoiceSchema,
     /**
      * sha256 of the fire secret, so a server checks a presented bearer in
      * process; the Control Center hears only about console test secrets,

package/src/scaffold/files.ts

@@ -27,7 +27,7 @@ export type Database = "postgres" | "mssql";
 // sync (scripts/sync-package-versions.ts) restamps it and files.test.ts holds
 // them to that.
 export const DEPENDENCIES = {
-    "@m6d/cortex-server": "~0.8.0",
+    "@m6d/cortex-server": "~0.9.0",
     "@tanstack/ai": "^0.55.0",
     "@tanstack/ai-openai": "^0.22.8",
     hono: "^4.12.3",
@@ -86,18 +86,10 @@ function packageJson(name: string) {
 
 /**
  * Never toggled, so they only ever appear commented out: `context` is fully
- * defaulted, and the other two are what you reach for once a real problem shows
- * up — noisy graph retrieval, a cheap-model path — not on day one.
+ * defaulted, and `reranker` is what you reach for once graph retrieval comes
+ * back noisy, not on day one.
  */
 const NEVER_SCAFFOLDED = [
-    [
-        "A cheaper, faster model for auxiliary passes. Same shape as `model`.",
-        `fastModel: {
-    baseURL: process.env["CORTEX_FAST_MODEL_URL"]!,
-    apiKey: process.env["CORTEX_FAST_MODEL_KEY"]!,
-    modelName: process.env["CORTEX_FAST_MODEL_NAME"]!,
-},`,
-    ],
     [
         "Re-ranks knowledge-graph retrieval when it comes back noisy.",
         `reranker: {