@m6d/cortex-cli 1.9.0 → 1.11.0

package/package.json

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

package/src/contracts/runtime/index.ts

@@ -15,9 +15,9 @@ export const TOOL_NAME_PATTERN = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
 
 /**
  * A variable the server fills per request: a session value, a request-context
- * value, or one the SDK computes. Declared per agent so the console offers
- * exactly what that agent's server provides, in prompts and as tool input
- * sources alike.
+ * 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
@@ -30,6 +30,25 @@ export const variableDeclarationSchema = z.object({
     computed: z.boolean().default(false),
 });
 
+/**
+ * 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,
+    },
+] as const satisfies ReadonlyArray<z.infer<typeof variableDeclarationSchema>>;
+
 export const RUNTIME_ERROR_KINDS = [
     "timeout",
     "upstream_4xx",
@@ -48,6 +67,43 @@ export const JSON_SCHEMA_ISSUE_KINDS = ["missing", "unexpected", "type_mismatch"
 
 export const agentSlugSchema = z.string().regex(AGENT_SLUG_PATTERN);
 export const localeSchema = z.enum(["en", "ar"]);
+
+/**
+ * The widget's landing-page prompt chips, per locale. 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, chipLength: 200 } as const;
+export const suggestionsSchema = z.record(
+    localeSchema,
+    z
+        .array(
+            z
+                .string()
+                .min(1)
+                .max(SUGGESTION_LIMITS.chipLength)
+                .refine((chip) => chip === chip.trim(), "chip has surrounding whitespace"),
+        )
+        .max(SUGGESTION_LIMITS.perLocale),
+);
+export type Suggestions = z.infer<typeof suggestionsSchema>;
+
+/**
+ * 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 GREETING_MAX_LENGTH = 200;
+export const greetingSchema = z.record(
+    localeSchema,
+    z
+        .string()
+        .max(GREETING_MAX_LENGTH)
+        .refine((text) => text === text.trim(), "greeting has surrounding whitespace"),
+);
+export type Greeting = z.infer<typeof greetingSchema>;
 export const catalogVersionSchema = z.string().regex(/^[0-9a-f]{16}$/);
 
 export const sharedShapeSchema = z.object({
@@ -252,19 +308,13 @@ export const triggerDeclarationSchema = z.object({
 });
 
 /**
- * What a server runs for one agent, sent whole at boot in `agent.declare`. An
- * agent exists in the Control Center only through a declaration, and only
- * its declaring server may serve it. Everything the console validates
- * against (variables, code skills, code triggers) is here rather than
- * assumed.
+ * What a server offers every agent the Control Center creates for it, sent
+ * whole at boot in `server.declare`: the `{{variables}}` its session loader
+ * and request context fill, SDK ones included. Agents in the server's own
+ * code never appear here; the Control Center is blind to them.
  */
-export const agentDeclarationSchema = z.object({
-    slug: agentSlugSchema,
+export const serverDeclarationSchema = z.object({
     variables: z.array(variableDeclarationSchema),
-    skills: z.array(skillLineSchema),
-    triggers: z.array(
-        triggerDeclarationSchema.pick({ name: true, description: true, input: true, thread: true }),
-    ),
 });
 
 export const triggerFiringResponseSchema = z.discriminatedUnion("outcome", [
@@ -370,6 +420,10 @@ export const runtimeAgentConfigSchema = z.object({
     triggers: z.array(triggerDeclarationSchema).default([]),
     /** Whether end users may message this agent; false makes it headless. */
     messageTrigger: z.boolean().default(true),
+    /** Operational like `messageTrigger`: edited on the agent row without republishing. */
+    suggestions: suggestionsSchema,
+    /** Operational like `suggestions`. */
+    greeting: greetingSchema,
     /** Absent from older Control Centers; reports then carry only the slug. */
     agentRef: agentRefSchema.optional(),
     catalogVersion: catalogVersionSchema,
@@ -582,13 +636,12 @@ export const syncEventSchema = z.discriminatedUnion("type", [
         createdAt: z.iso.datetime(),
         finishedAt: z.iso.datetime().nullable(),
     }),
-    // Everything the server runs, sent whole at boot. Replaces the server's
-    // previous declaration, so an agent removed from code leaves cc with its
-    // skills and triggers.
+    // What the server offers console-created agents, sent whole at boot and
+    // replacing the previous declaration.
     z.object({
-        type: z.literal("agent.declare"),
+        type: z.literal("server.declare"),
         id: z.uuid(),
-        agents: z.array(agentDeclarationSchema),
+        ...serverDeclarationSchema.shape,
         createdAt: z.iso.datetime(),
     }),
 ]);
@@ -629,7 +682,7 @@ export type ResolveResponse = z.infer<typeof resolveResponseSchema>;
 export type SkillLine = z.infer<typeof skillLineSchema>;
 export type SkillBodyResponse = z.infer<typeof skillBodyResponseSchema>;
 export type TriggerDeclaration = z.infer<typeof triggerDeclarationSchema>;
-export type AgentDeclaration = z.infer<typeof agentDeclarationSchema>;
+export type ServerDeclaration = z.infer<typeof serverDeclarationSchema>;
 export type VariableDeclaration = z.infer<typeof variableDeclarationSchema>;
 export type TriggerThreadPolicy = z.infer<typeof triggerThreadPolicySchema>;
 export type TriggerOutcome = (typeof TRIGGER_OUTCOMES)[number];

package/src/contracts/wire/index.ts

@@ -99,6 +99,10 @@ export type AgentCapabilities = {
     attachments: boolean;
     /** False when the agent's `message` trigger is off: the widget hides its composer. */
     messages: boolean;
+    /** Prompt chips on the blank-chat landing per locale, the runtime contract's `suggestionsSchema` shape; clicking one sends it as the first message. */
+    suggestions: Record<"en" | "ar", string[]>;
+    /** Headline of the blank-chat landing per locale; "" falls back to the widget's built-in copy. */
+    greeting: Record<"en" | "ar", string>;
 };
 
 export type MessageMetadata = {