@m6d/cortex-cli 0.18.0 → 0.20.0

package/src/contracts/manifest/index.ts

@@ -1476,22 +1476,6 @@ export const agentSettingsSchema = z.strictObject({
     /** Off, end users cannot message the agent: only its triggers reach it. */
     messageTrigger: z.boolean().default(true),
     defaultLocale: localeSchema.default(BASE_LOCALE),
-    rateLimits: z
-        .strictObject({
-            allUsers: z
-                .strictObject({
-                    messagesPerMinute: rateLimit(agentRateLimits.messagesPerMinute, "allUsers"),
-                    tokensPerDay: rateLimit(agentRateLimits.tokensPerDay, "allUsers"),
-                })
-                .prefault({}),
-            perUser: z
-                .strictObject({
-                    messagesPerMinute: rateLimit(agentRateLimits.messagesPerMinute, "perUser"),
-                    tokensPerDay: rateLimit(agentRateLimits.tokensPerDay, "perUser"),
-                })
-                .prefault({}),
-        })
-        .prefault({}),
     context: z
         .strictObject({
             maxContextTokens: setting(agentContext.maxContextTokens),
@@ -1516,30 +1500,77 @@ export const agentSettingsSchema = z.strictObject({
 /** An agent's name in characters. The console caps its editor at the same. */
 export const AGENT_LIMITS = { nameLength: 120 } as const;
 
-const manifestAgentSchema = z.strictObject({
-    slug: agentSlugSchema,
-    name: z.string().trim().min(1).max(AGENT_LIMITS.nameLength),
-    /** The server it belongs to, by name; a manifest never creates one. */
-    server: nameSchema,
-    /** Rich text: it may mention tools and skills, and read `{{variables}}`. */
-    prompt: z.string().trim().min(1),
-    auth: agentAuthSchema,
-    /**
-     * `chat` left out runs on the server's pick; `vision` and
-     * `summarization` left out use none of their own.
-     */
-    models: z
-        .strictObject({
-            chat: modelSchema.optional(),
-            vision: modelSchema.omit({ effort: true }).optional(),
-            summarization: modelSchema.omit({ effort: true }).optional(),
-        })
-        .default({}),
-    settings: agentSettingsSchema.prefault({}),
-    suggestions: suggestionsSchema.default(() => byLocale(() => [])),
-    greeting: greetingSchema.default(() => byLocale(() => "")),
-    overridable: overridable(["name", "prompt", "models", "settings", "suggestions", "greeting"]),
-});
+const manifestAgentSchema = z
+    .strictObject({
+        slug: agentSlugSchema,
+        name: z.string().trim().min(1).max(AGENT_LIMITS.nameLength),
+        /**
+         * The server it belongs to, by name; a manifest never creates one. Left
+         * out, the agent has no server: no native tools, no server variables,
+         * no `server` auth, and no model to inherit, so it names its own `chat`.
+         */
+        server: nameSchema.optional(),
+        /** Rich text: it may mention tools and skills, and read `{{variables}}`. */
+        prompt: z.string().trim().min(1),
+        auth: agentAuthSchema,
+        /**
+         * `chat` left out runs on the server's pick; `vision` and
+         * `summarization` left out use none of their own.
+         */
+        models: z
+            .strictObject({
+                chat: modelSchema.optional(),
+                vision: modelSchema.omit({ effort: true }).optional(),
+                summarization: modelSchema.omit({ effort: true }).optional(),
+            })
+            .default({}),
+        settings: agentSettingsSchema.prefault({}),
+        /** Messages a minute and model tokens a UTC day, for all users together and for each; null, no limit. */
+        rateLimits: z
+            .strictObject({
+                allUsers: z
+                    .strictObject({
+                        messagesPerMinute: rateLimit(agentRateLimits.messagesPerMinute, "allUsers"),
+                        tokensPerDay: rateLimit(agentRateLimits.tokensPerDay, "allUsers"),
+                    })
+                    .prefault({}),
+                perUser: z
+                    .strictObject({
+                        messagesPerMinute: rateLimit(agentRateLimits.messagesPerMinute, "perUser"),
+                        tokensPerDay: rateLimit(agentRateLimits.tokensPerDay, "perUser"),
+                    })
+                    .prefault({}),
+            })
+            .prefault({}),
+        suggestions: suggestionsSchema.default(() => byLocale(() => [])),
+        greeting: greetingSchema.default(() => byLocale(() => "")),
+        overridable: overridable([
+            "name",
+            "prompt",
+            "models",
+            "settings",
+            "rateLimits",
+            "suggestions",
+            "greeting",
+        ]),
+    })
+    .superRefine((agent, context) => {
+        if (agent.server !== undefined) return;
+        if (agent.auth.kind === "server") {
+            context.addIssue({
+                code: "custom",
+                path: ["auth"],
+                message: "server auth needs a server",
+            });
+        }
+        if (agent.models.chat === undefined) {
+            context.addIssue({
+                code: "custom",
+                path: ["models", "chat"],
+                message: "an agent with no server names its own chat model",
+            });
+        }
+    });
 export type ManifestAgent = z.input<typeof manifestAgentSchema>;
 
 /**

package/src/management/client.ts

@@ -2,7 +2,8 @@ import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
-import { isRecord } from "@cortex/contracts/json";
+import { createManagementClient, MANAGEMENT_BASE_PATH } from "@cortex/contracts/management";
+import type { ManagementTarget } from "@cortex/contracts/management";
 import { z } from "zod";
 
 import { profilesPath } from "./profiles";
@@ -109,7 +110,7 @@ export async function loadOpenApi(url: string) {
     const path = cachePath(url);
     const cached = readCache(path);
     try {
-        const response = await fetch(`${url}/api/management/openapi.json`, {
+        const response = await fetch(`${url}${MANAGEMENT_BASE_PATH}/openapi.json`, {
             headers: cached ? { "If-None-Match": cached.etag } : {},
         });
         if (response.status === 304 && cached)
@@ -159,71 +160,30 @@ export function inputSchemaOf(operation: OpenApiOperation) {
 }
 
 /**
- * One management call. A query's input object is spread over the query
- * string, one parameter per field, with a scalar written plainly and
- * anything else JSON-encoded, which is how the document declares it. A
- * mutation posts its input as the JSON body. A refusal throws
- * `ManagementError` with the error body's code, message, detail and sentence.
+ * Where `profile`'s management calls go; a Cortex that does not answer at
+ * all rejects as `UnreachableError`, apart from one that refused.
  */
-export async function callManagement(
-    profile: { url: string; key: string },
-    method: "get" | "post",
-    path: string,
-    input: unknown,
-) {
-    const base = `${profile.url}/api/management${path}`;
-    const url = method === "get" && isRecord(input) ? `${base}${queryString(input)}` : base;
-    const response = await fetch(url, {
-        method: method.toUpperCase(),
-        headers: {
-            Authorization: `Bearer ${profile.key}`,
-            ...(method === "post" ? { "Content-Type": "application/json" } : {}),
-        },
-        body: method === "post" && input !== undefined ? JSON.stringify(input) : undefined,
-    }).catch((error: unknown) => {
-        throw new UnreachableError(error);
-    });
-    const body: unknown = await response.json().catch(() => null);
-    if (!response.ok) {
-        const { code, message, refusal, cause } = (body ?? {}) as {
-            code?: string;
-            message?: string;
-            refusal?: string;
-            cause?: unknown;
-        };
-        throw new ManagementError(
-            response.status,
-            code ?? "error",
-            message ?? response.statusText,
-            isRecord(cause) ? cause : undefined,
-            refusal,
-        );
-    }
-    return body;
-}
-
-function isScalar(value: unknown): value is string | number | boolean | null {
-    return value === null || ["string", "number", "boolean"].includes(typeof value);
+export function managementTarget(profile: { url: string; key: string }) {
+    return {
+        ...profile,
+        // Every day range a command takes is this machine's days.
+        timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+        fetch: (url: string, init: RequestInit) =>
+            fetch(url, init).catch((error: unknown) => {
+                throw new UnreachableError(error);
+            }),
+    } satisfies ManagementTarget;
 }
 
-/** A scalar as itself, an array of scalars as a repeated parameter, anything else as JSON, matching what the document declares. */
-function queryString(input: Record<string, unknown>) {
-    const params = new URLSearchParams();
-    for (const [name, value] of Object.entries(input)) {
-        if (value === undefined) continue;
-        if (isScalar(value)) params.set(name, String(value));
-        else if (Array.isArray(value) && value.length > 0 && value.every(isScalar)) {
-            for (const item of value) params.append(name, String(item));
-        } else params.set(name, JSON.stringify(value));
-    }
-    const encoded = params.toString();
-    return encoded === "" ? "" : `?${encoded}`;
+/** The typed client for the calls the CLI makes by name, over `managementTarget`. */
+export function managementClient(profile: { url: string; key: string }) {
+    return createManagementClient(managementTarget(profile));
 }
 
 /**
  * Cortex did not answer at all: refused, reset, unresolvable. `fetch` rejects
  * only for these, with whatever its runtime throws (Bun's is a plain `Error`
- * with a `code`), so `callManagement` names them once here.
+ * with a `code`), so `managementTarget` names them once here.
  */
 export class UnreachableError extends Error {
     public constructor(cause: unknown) {
@@ -231,21 +191,3 @@ export class UnreachableError extends Error {
         this.name = "UnreachableError";
     }
 }
-
-/**
- * A refusal; `detail` is what the refusal names, when it names something (an
- * entry, the row holding a name), and `refusal` the sentence Cortex words it
- * in, when it has one.
- */
-export class ManagementError extends Error {
-    public constructor(
-        public readonly status: number,
-        public readonly code: string,
-        message: string,
-        public readonly detail?: Record<string, unknown>,
-        public readonly refusal?: string,
-    ) {
-        super(message);
-        this.name = "ManagementError";
-    }
-}

package/src/scaffold/files.ts

@@ -2,9 +2,10 @@
  * Every file `cortex new` writes, as one pure function. Files with nothing to
  * fill in are verbatim text under templates/; the ones that vary with the
  * project are assembled here. The tooling configs are inlined rather than
- * pulled from `@m6d/eslint-config`, `@m6d/prettier-config` and `@m6d/tsconfig`:
- * those are `private: true` at `0.0.0` and resolvable only through this
- * workspace, and a standalone scaffold has no workspace.
+ * pulled from `@m6d/prettier-config`, `@m6d/tsconfig` and the root
+ * `.oxlintrc.json`: those are `private: true` at `0.0.0` (the lint config
+ * loads `@m6d/oxlint-plugin`) and resolvable only through this workspace, and
+ * a standalone scaffold has no workspace.
  */
 
 import { NAME_MAX_LENGTH } from "@cortex/contracts/manifest";
@@ -16,11 +17,11 @@ import datasetsTs from "@/scaffold/templates/datasets.ts.txt";
 import tsconfigJson from "@/scaffold/templates/tsconfig.json.txt";
 import gitignoreText from "@/scaffold/templates/gitignore.txt";
 import dockerignoreText from "@/scaffold/templates/dockerignore.txt";
-import eslintConfig from "@/scaffold/templates/eslint.config.mjs.txt";
+import oxlintrc from "@/scaffold/templates/oxlintrc.json.txt";
 import prettierConfig from "@/scaffold/templates/prettier.config.mjs.txt";
 import fallowrc from "@/scaffold/templates/fallowrc.jsonc.txt";
-// Project jargon is the project's to add. Only `mprocs`, which its own
-// package.json names, is seeded: a stranger's vocabulary is noise in a repo.
+// Project jargon is the project's to add. Only the tool names its own
+// package.json carries are seeded: a stranger's vocabulary is noise in a repo.
 import cspellJson from "@/scaffold/templates/cspell.json.txt";
 import { applyPorts, type Ports } from "@/scaffold/ports";
 
@@ -29,7 +30,7 @@ import { applyPorts, type Ports } from "@/scaffold/ports";
  * `@m6d/cortex` range below are stamped by scripts/sync-package-versions.ts
  * before the CLI publishes, so a scaffold pins what was current then.
  */
-const CORTEX_VERSION = "0.17.0";
+const CORTEX_VERSION = "0.19.0";
 
 /** This machine as Cortex's containers name it: the one private host the stack's egress policy admits. */
 export const DOCKER_HOST = "host.docker.internal";
@@ -54,18 +55,16 @@ export const EMBEDDING = { model: "text-embedding-3-small", dimension: 768 } as
 const DEV_DEPENDENCIES = {
     // `cortex apply`, `cortex setup` and the management commands, at the release that wrote the project.
     "@m6d/cortex-cli": `~${pkg.version}`,
-    "@types/bun": "1.3.14",
+    "@types/bun": "1.4.4",
     // The two runners of `bun run dev` and `bun run dev:agent`.
     concurrently: "^10.0.6",
     cspell: "^9.6.4",
-    eslint: "^9",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.5",
     fallow: "^3.9.1",
     mprocs: "^0.9.6",
+    oxlint: "^1.90.0",
+    "oxlint-tsgolint": "^7.0.2005",
     prettier: "^3.8.1",
-    typescript: "~6.0.3",
-    "typescript-eslint": "^8.65.0",
+    typescript: "^7.0.2",
 };
 
 /**
@@ -145,12 +144,12 @@ function packageJson({ name, datasets, setup }: Project) {
                 postinstall: "bun run --if-present setup.ts",
                 format: "prettier --write .",
                 "format:check": "prettier --check .",
-                lint: "eslint",
+                lint: "oxlint",
                 spellcheck: 'cspell "**/*.{ts,mjs,json,md}"',
                 verify: "bun run format:check && bun run lint && bun run spellcheck && bun run check && bun run audit",
             },
             dependencies: {
-                "@m6d/cortex": "~0.5.0",
+                "@m6d/cortex": "~0.7.0",
                 // drizzle 1.0 is in beta; this is the build `@m6d/cortex/drizzle` is tested against.
                 ...(datasets ? { "drizzle-orm": "1.0.0-beta.15-859cf75" } : {}),
                 hono: "^4.12.3",
@@ -249,9 +248,11 @@ COMPOSE_PROJECT_NAME=
 DEFAULT_ADMIN_EMAIL=admin@example.com
 DEFAULT_ADMIN_PASSWORD=
 BOOTSTRAP_MANAGEMENT_KEY=
-# Session signing, and the key the secrets store is encrypted with.
+# Session signing, the key the secrets store is encrypted with, and object
+# storage's password (storage is published on this machine for uploads).
 BETTER_AUTH_SECRET=
 SECRETS_MASTER_KEY=
+S3_SECRET_ACCESS_KEY=
 # Any OpenAI-compatible embeddings endpoint and model. Tool search and
 # knowledge collections embed with it, and stay off while the key is blank.
 EMBEDDING_BASE_URL=https://api.openai.com/v1
@@ -288,17 +289,14 @@ MODEL_PROVIDER_MODEL=
 function dockerCompose() {
     return `# Cortex, for this project's agents to run on: the console at
 # http://localhost:{{port.cortex}}, the engine widgets and trigger callers reach at
-# http://localhost:{{port.engine}}, and the stores they keep state in. \`bun run dev\`
-# starts it; .env holds its secrets.
+# http://localhost:{{port.engine}}, storage the console uploads to at
+# http://localhost:{{port.storage}}, and the stores they keep state in.
+# \`bun run dev\` starts it; .env holds its secrets.
 #
 # The host ports were picked at scaffold time from what was free on this
 # machine. Move one and the URLs that name it here, in .env and in README.md
 # follow.
 # CORTEX_VERSION, set in the shell, runs another release of the image.
-#
-# The console's browser uploads (knowledge documents) go straight to
-# S3_ENDPOINT, which only this stack resolves. Point it at storage the
-# browser reaches too before relying on them.
 
 # The stack runs as .env's COMPOSE_PROJECT_NAME, drawn for each checkout by
 # setup.ts, so no two checkouts share containers or volumes, whatever their
@@ -316,9 +314,13 @@ x-cortex: &cortex
         DATABASE_URL: postgres://postgres:postgres@postgres:5432/cortex
         REDIS_URL: redis://redis:6379
         S3_ENDPOINT: http://minio:9000
+        # The console's uploads go straight to storage, from the browser.
+        S3_PUBLIC_ENDPOINT: http://localhost:{{port.storage}}
         S3_REGION: us-east-1
         S3_ACCESS_KEY_ID: minio
-        S3_SECRET_ACCESS_KEY: minio-secret-key
+        # Interpolated like storage's own, so both read the one value even when the
+        # shell exports another.
+        S3_SECRET_ACCESS_KEY: \${S3_SECRET_ACCESS_KEY:?run bun install to generate .env}
         S3_BUCKET: cortex
         BETTER_AUTH_ALLOWED_HOSTS: localhost:{{port.cortex}},127.0.0.1:{{port.cortex}}
         # The dimension the image's migrations give the vector columns.
@@ -366,9 +368,13 @@ services:
         command: server /data
         environment:
             MINIO_ROOT_USER: minio
-            MINIO_ROOT_PASSWORD: minio-secret-key
+            MINIO_ROOT_PASSWORD: \${S3_SECRET_ACCESS_KEY:?run bun install to generate .env}
+            # The console's uploads come from its origin alone.
+            MINIO_API_CORS_ALLOW_ORIGIN: http://localhost:{{port.cortex}},http://127.0.0.1:{{port.cortex}}
         volumes:
             - minio-data:/data
+        ports:
+            - "127.0.0.1:{{port.storage}}:9000"
         healthcheck:
             test: ["CMD", "bash", "-c", "</dev/tcp/127.0.0.1/9000"]
             interval: 5s
@@ -381,7 +387,7 @@ services:
             minio:
                 condition: service_healthy
         environment:
-            MC_HOST_local: http://minio:minio-secret-key@minio:9000
+            MC_HOST_local: http://minio:\${S3_SECRET_ACCESS_KEY:?run bun install to generate .env}@minio:9000
         command: ["mb", "--ignore-existing", "local/cortex"]
 
     # One-shot: migrate the database, then create the first admin and its key.
@@ -547,7 +553,7 @@ export function scaffoldFiles(input: Input) {
         ".gitignore": gitignoreText,
         ".dockerignore": dockerignoreText,
         "README.md": readme(project),
-        "eslint.config.mjs": eslintConfig,
+        ".oxlintrc.json": oxlintrc,
         "prettier.config.mjs": prettierConfig,
         "cspell.json": cspellJson,
         ".fallowrc.jsonc": fallowrc,

package/src/scaffold/ports.ts

@@ -2,9 +2,10 @@
  * Host ports for the Cortex stack a generated project runs, chosen once at
  * scaffold time.
  *
- * Only the app and the engine are published: the browser and this
- * project's callers reach them, and nothing outside the stack reaches its
- * databases. The backend listens on the third. Fixed ports would collide with
+ * The app, the engine and storage are published: the browser and this
+ * project's callers reach them (storage through the upload links Cortex
+ * signs), and nothing outside the stack reaches its databases. The backend
+ * listens on the fourth. Fixed ports would collide with
  * the next project scaffolded on the same machine, so each project draws its
  * own. Container ports stay canonical.
  *
@@ -60,7 +61,7 @@ export function allocatePorts() {
         return port;
     }
 
-    return { cortex: next(), engine: next(), server: next() };
+    return { cortex: next(), engine: next(), storage: next(), server: next() };
 }
 
 export type Ports = ReturnType<typeof allocatePorts>;

package/src/scaffold/templates/cspell.json.txt

@@ -1,7 +1,7 @@
 {
     "version": "0.2",
     "language": "en",
-    "words": ["mprocs"],
+    "words": ["mprocs", "oxlint", "tsgolint"],
     "ignorePaths": [
         "node_modules/**",
         "out/**",

package/src/scaffold/templates/oxlintrc.json.txt

@@ -0,0 +1,67 @@
+{
+    "$schema": "./node_modules/oxlint/configuration_schema.json",
+    // typescript-eslint's recommended type-checked set; nothing else runs.
+    "categories": {
+        "correctness": "off"
+    },
+    "options": {
+        "typeAware": true,
+        "reportUnusedDisableDirectives": "warn"
+    },
+    "ignorePatterns": ["**/node_modules/**", "**/dist/**", "**/.fallow/**"],
+    "overrides": [
+        {
+            "files": ["**/*.ts"],
+            "plugins": ["typescript"],
+            "rules": {
+                "no-var": "error",
+                "prefer-const": "error",
+                "prefer-rest-params": "error",
+                "prefer-spread": "error",
+                "no-array-constructor": "error",
+                "no-unused-expressions": "error",
+                "no-unused-vars": "error",
+                "typescript/await-thenable": "error",
+                "typescript/ban-ts-comment": "error",
+                "typescript/no-array-delete": "error",
+                "typescript/no-base-to-string": "error",
+                "typescript/no-duplicate-enum-values": "error",
+                "typescript/no-duplicate-type-constituents": "error",
+                "typescript/no-empty-object-type": "error",
+                "typescript/no-explicit-any": "error",
+                "typescript/no-extra-non-null-assertion": "error",
+                "typescript/no-floating-promises": "error",
+                "typescript/no-for-in-array": "error",
+                "typescript/no-implied-eval": "error",
+                "typescript/no-misused-new": "error",
+                "typescript/no-misused-promises": "error",
+                "typescript/no-namespace": "error",
+                "typescript/no-non-null-asserted-optional-chain": "error",
+                "typescript/no-redundant-type-constituents": "error",
+                "typescript/no-require-imports": "error",
+                "typescript/no-this-alias": "error",
+                "typescript/no-unnecessary-type-assertion": "error",
+                "typescript/no-unnecessary-type-constraint": "error",
+                "typescript/no-unsafe-argument": "error",
+                "typescript/no-unsafe-assignment": "error",
+                "typescript/no-unsafe-call": "error",
+                "typescript/no-unsafe-declaration-merging": "error",
+                "typescript/no-unsafe-enum-comparison": "error",
+                "typescript/no-unsafe-function-type": "error",
+                "typescript/no-unsafe-member-access": "error",
+                "typescript/no-unsafe-return": "error",
+                "typescript/no-unsafe-unary-minus": "error",
+                "typescript/no-wrapper-object-types": "error",
+                "typescript/only-throw-error": "error",
+                "typescript/prefer-as-const": "error",
+                "typescript/prefer-namespace-keyword": "error",
+                "typescript/prefer-promise-reject-errors": "error",
+                "typescript/require-await": "error",
+                "typescript/restrict-plus-operands": "error",
+                "typescript/restrict-template-expressions": "error",
+                "typescript/triple-slash-reference": "error",
+                "typescript/unbound-method": "error"
+            }
+        }
+    ]
+}

package/src/scaffold/templates/setup.ts.txt

@@ -30,6 +30,7 @@ const GENERATED = [
     ["BOOTSTRAP_MANAGEMENT_KEY", () => `cortex_mgmt_${token()}`],
     ["BETTER_AUTH_SECRET", key],
     ["SECRETS_MASTER_KEY", key],
+    ["S3_SECRET_ACCESS_KEY", token],
 ] as const;
 
 const source = existsSync(".env") ? ".env" : ".env.example";

package/src/scaffold/templates/eslint.config.mjs.txt

@@ -1,20 +0,0 @@
-import { defineConfig, globalIgnores } from "eslint/config";
-import prettierConfig from "eslint-config-prettier";
-import prettierPlugin from "eslint-plugin-prettier";
-import tseslint from "typescript-eslint";
-
-export default defineConfig([
-    globalIgnores(["**/node_modules/**", "**/dist/**", "**/.fallow/**"]),
-    prettierConfig,
-    {
-        plugins: { prettier: prettierPlugin },
-        rules: { "prettier/prettier": "error" },
-    },
-    {
-        files: ["**/*.ts"],
-        extends: [tseslint.configs.recommendedTypeChecked],
-        languageOptions: {
-            parserOptions: { projectService: true, tsconfigRootDir: import.meta.dirname },
-        },
-    },
-]);