@m6d/cortex-cli 1.4.0 → 1.5.0

package/package.json

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

package/src/cli.ts

@@ -6,7 +6,7 @@ import { registerNew } from "@/commands/new";
 import { registerSwagger } from "@/commands/swagger";
 import * as report from "@/ui/report";
 
-// Discovery is this exact name in the cwd, with no upward walk (design spec §6.2),
+// Discovery is this exact name in the cwd, with no upward walk,
 // so the flag's default *is* the discovery rule. The second argument is what help
 // prints — without it commander would JSON.stringify the path and show quotes.
 const DEFAULT_CONFIG = "./cortex.config.ts";
@@ -28,7 +28,7 @@ const program = new Command()
     .helpCommand(false)
     // Commander appends ` [options]` to any command that has some. Left in, the
     // first command to grow a flag widens the whole list and the two-group screen
-    // in cli-output.md §1 stops matching. `cortex <command> --help` lists them.
+    // stops matching. `cortex <command> --help` lists them.
     .configureHelp({
         subcommandTerm: function (cmd) {
             return new Help().subcommandTerm(cmd).replace(" [options]", "");

package/src/commands/new.ts

@@ -68,7 +68,7 @@ type Options = {
 async function scaffold(name: string | undefined, options: Options) {
     const { verbose, databasePassed } = options;
 
-    // No TTY ⇒ never prompt and behave as `--yes` (design spec §5.3). On Bun a
+    // No TTY ⇒ never prompt and behave as `--yes`. On Bun a
     // piped stdin reports `undefined` rather than `false`, which is why this
     // compares against `true`.
     const interactive = process.stdin.isTTY === true && options.yes !== true;
@@ -229,7 +229,7 @@ async function install(cwd: string) {
 }
 
 function step(command: string, annotation?: string) {
-    // 27 puts the annotation column where cli-output.md §3 has it.
+    // 27 aligns the annotation column across all report rows.
     return annotation ? `  ${command.padEnd(27)}${annotation}\n` : `  ${command}\n`;
 }
 
@@ -294,7 +294,7 @@ function isInsideWorkTree(target: string) {
 
 function missingName(): never {
     // No TTY ⇒ never prompt, so a missing required argument is a hard error
-    // (design spec §5.3). With a TTY this branch is only reached under `--yes`,
+    // With a TTY this branch is only reached under `--yes`,
     // which answers every question including the one that has no default.
     report.fail({
         what:

package/src/commands/swagger.ts

@@ -8,7 +8,7 @@ import { validateConfig } from "@/config/validate";
 import { extractEndpoints } from "@/swagger/extract-endpoints";
 import * as report from "@/ui/report";
 
-/** A convention, not config: `KnowledgeConfig` has no `domainsDir` (design spec §5.5). */
+/** A convention, not config: `KnowledgeConfig` has no `domainsDir`. */
 const DEFAULT_DOMAINS_DIR = "src/domains";
 
 /** Only the parts of a loaded config `swagger` reads to report its inputs. */

package/src/config/load.ts

@@ -1,5 +1,5 @@
 /**
- * Config discovery and loading (design spec §6.2). Env needs no step of its own:
+ * Config discovery and loading. Env needs no step of its own:
  * discovery is cwd-only and Bun's `.env` auto-load is cwd-relative, so the two
  * are always colocated and `process.env` is populated before the config
  * evaluates.

package/src/config/validate.ts

@@ -1,5 +1,5 @@
 /**
- * One generic rule (design spec §6.3): a key present with an `undefined` value
+ * One generic rule: a key present with an `undefined` value
  * is a failure, listed by full path. It is essentially always the
  * `process.env["X"]!` pattern, where `!` silences the type error and `undefined`
  * flows on to fail far from its cause. Absent keys are fine — that is how

package/src/contracts/runtime/index.ts

@@ -7,10 +7,10 @@ import { z } from "zod";
  * payloads the runtime's parser then fills defaults into.
  */
 
-/** Runtime contract §1.1: the `:id` path param, validated on both sides of the wire. */
+/** 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. */
+/** Tool names become `tools.<name>()` sandbox bindings on the server. */
 export const TOOL_NAME_PATTERN = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
 
 export const PROMPT_VARIABLES = ["userName", "channel", "locale", "utcTime", "timezone"] as const;
@@ -90,7 +90,7 @@ export const knowledgeChunkSchema = z.object({
 });
 
 /**
- * Runtime contract §5.4: present on signatures of `embedded` tools — flows
+ * 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
@@ -252,9 +252,105 @@ export const runtimeErrorSchema = z.object({
     }),
 });
 
+/*
+ * Fleet sync: `@m6d/cortex-server` mirrors thread/message/usage activity into
+ * cc via `POST /api/runtime/sync` batches. Upserts are idempotent on
+ * (serverId, id); an empty batch is the heartbeat.
+ */
+
+const tokenCountSchema = z.number().int().nonnegative();
+
+/** Mirrors the zero-dep `TokenUsage` shape in `wire/index.ts` (wire must stay import-free). */
+export const tokenUsageSchema = z.object({
+    input: z.object({
+        noCache: tokenCountSchema,
+        cacheRead: tokenCountSchema,
+        cacheWrite: tokenCountSchema,
+        total: tokenCountSchema,
+    }),
+    output: z.object({
+        reasoning: tokenCountSchema,
+        text: tokenCountSchema,
+        total: tokenCountSchema,
+    }),
+    total: tokenCountSchema,
+});
+
+export const MESSAGE_ROLES = ["system", "user", "assistant", "tool"] as const;
+
+export const syncEventSchema = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("thread.upsert"),
+        id: z.uuid(),
+        agentSlug: agentSlugSchema,
+        userId: z.string().max(255),
+        title: z.string().max(256).nullable(),
+        isTest: z.boolean(),
+        createdAt: z.iso.datetime(),
+        updatedAt: z.iso.datetime(),
+    }),
+    z.object({
+        type: z.literal("thread.delete"),
+        id: z.uuid(),
+    }),
+    z.object({
+        type: z.literal("message.upsert"),
+        id: z.string().max(128),
+        threadId: z.uuid(),
+        role: z.enum(MESSAGE_ROLES),
+        text: z.string().nullable(),
+        ordinal: z.number().int(),
+        content: z.looseObject({}),
+        createdAt: z.iso.datetime(),
+    }),
+    z.object({
+        type: z.literal("usage.record"),
+        id: z.uuid(),
+        messageId: z.string().max(128),
+        threadId: z.uuid(),
+        stepNumber: z.number().int(),
+        tokenUsage: tokenUsageSchema,
+        // Stamped by the event constructor: llm_requests has no timestamp
+        // column, but the mirror needs one for time-bucketed usage stats.
+        createdAt: z.iso.datetime(),
+    }),
+]);
+
+/*
+ * `epoch` identifies the sending database's generation (a UUIDv7 minted into
+ * the server DB's `sync_meta` row): a recreated database gets a new epoch, so
+ * cc can tell a legitimately restarted outbox sequence from a stale batch.
+ * v7 uuids are time-ordered, so cc also rejects batches from a superseded
+ * (lexicographically lower) epoch outright.
+ * `seq` is the batch's highest outbox row id; batches are contiguous
+ * id-ordered outbox prefixes, so within one epoch cc keeps a per-server
+ * high-water mark and discards batches at or below it — a stale in-flight
+ * batch (an expired flusher lease, a replay after a lost ack) can never
+ * overwrite newer mirrored state. Heartbeats carry no events and nothing to
+ * fence, so `seq` exists only on the non-empty branch.
+ */
+export const syncRequestSchema = z.union([
+    z.object({
+        events: z.array(syncEventSchema).min(1).max(500),
+        epoch: z.uuid(),
+        seq: z.number().int().positive(),
+    }),
+    z.object({
+        events: z.array(syncEventSchema).length(0),
+        epoch: z.uuid(),
+    }),
+]);
+
+export const syncResponseSchema = z.object({
+    accepted: z.number().int(),
+});
+
 export type ToolEmbed = z.infer<typeof toolEmbedSchema>;
 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>;
+export type SyncEvent = z.infer<typeof syncEventSchema>;
+export type SyncRequest = z.input<typeof syncRequestSchema>;
+export type SyncResponse = z.infer<typeof syncResponseSchema>;

package/src/scaffold/features.ts

@@ -1,5 +1,5 @@
 /**
- * The five features `cortex new` toggles (design spec §7.1). A feature is not a
+ * The five features `cortex new` toggles. A feature is not a
  * config key: it is a bundle of a `cortex.config.ts` fragment, a block of env
  * keys, and sometimes a compose service. Fragments concatenate — there is no
  * merge engine — so every field here is plain text that gets joined.

package/src/scaffold/files.ts

@@ -2,8 +2,7 @@
  * Every file `cortex new` writes, as one pure function. 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. See
- * docs/design/cortex-cli.md §7.5-§7.6.
+ * through this workspace, and a standalone scaffold has no workspace.
  */
 
 import { FEATURE_NAMES, FEATURES, type Feature } from "@/scaffold/features";

package/src/ui/report.ts

@@ -1,6 +1,6 @@
 /**
  * The output grammar, shared by every command that runs against a project.
- * Layout is fixed by `docs/prototypes/cli-output.md`; this file is the only
+ * The report layout is deliberately frozen; this file is the only
  * place that knows the box characters.
  */