@m6d/cortex-cli 1.8.0 → 1.10.0

package/package.json

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

package/src/contracts/runtime/index.ts

@@ -13,42 +13,22 @@ export const AGENT_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
 /** 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;
-
 /**
- * One entry per prompt variable, driving editor autocomplete, validation, and
- * runtime substitution alike. Adding a variable = extending the tuple above
- * plus one entry here (the compiler enforces the pair); the consumer embedding
- * the agent supplies the value in its session/request context under the same
- * key. Descriptions are plain English on purpose: variables are code-like
- * identifiers shown in an LTR suggestion list, not localized UI copy.
+ * 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.
  */
-export const PROMPT_VARIABLE_DEFINITIONS = {
-    userName: {
-        description: "Display name of the signed-in user",
-        example: "Sara",
-    },
-    channel: {
-        description: "Channel the conversation arrived on",
-        example: "web",
-    },
-    locale: {
-        description: "Resolved locale of the session",
-        example: "ar",
-    },
-    // The server computes utcTime per request (a consumer-supplied value
-    // still wins); timezone has no server default — only the consumer knows
-    // the session's zone, so it must arrive via session/request context or
-    // the placeholder stays literal.
-    utcTime: {
-        description: "Current time in UTC (ISO 8601)",
-        example: "2026-08-16T09:30:00Z",
-    },
-    timezone: {
-        description: "IANA time zone of the session",
-        example: "Asia/Dubai",
-    },
-} satisfies Record<(typeof PROMPT_VARIABLES)[number], { description: string; example: string }>;
+export const variableDeclarationSchema = z.object({
+    name: z
+        .string()
+        .regex(/^[A-Za-z_$][A-Za-z0-9_$]*$/)
+        .max(64),
+    description: z.string().max(500),
+    example: z.string().max(200),
+    /** Computed by the SDK per request (`utcTime`, `locale`); no session value can set it. */
+    computed: z.boolean().default(false),
+});
 
 export const RUNTIME_ERROR_KINDS = [
     "timeout",
@@ -68,6 +48,29 @@ 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>;
 export const catalogVersionSchema = z.string().regex(/^[0-9a-f]{16}$/);
 
 export const sharedShapeSchema = z.object({
@@ -101,6 +104,13 @@ export const toolEmbedSchema = z.object({
     embedOrigin: z.url(),
 });
 
+/**
+ * Variables a tool's input reads (`x-source` of kind `variable` on an input
+ * property). The server fills those fields from the agent's declared
+ * variables at execute time and the model never sees them.
+ */
+const boundVariablesSchema = z.array(variableDeclarationSchema.shape.name);
+
 export const toolSignatureSchema = z.object({
     toolId: z.uuid(),
     name: z.string().regex(TOOL_NAME_PATTERN),
@@ -110,6 +120,7 @@ export const toolSignatureSchema = z.object({
     signature: z.string(),
     score: z.number().nullable(),
     pinned: z.boolean(),
+    variables: boundVariablesSchema,
     embed: toolEmbedSchema.optional(),
     /** Client tools only: the published input JSON Schema, verbatim.
      * Client-executed declarations need a real schema — the rendered
@@ -159,11 +170,22 @@ export const agentRefSchema = z.string().max(128);
  */
 export const AGENT_REF_HEADER = "X-CC-Agent-Ref";
 
+/**
+ * The playground operator's stand-in for a test thread's session: a
+ * URI-encoded JSON object of declared variable values, sent by cc's
+ * playground beside `X-Cortex-Playground` and honoured only when that header
+ * verifies. The server stores it as the thread's session on creation, so the
+ * customer's `loadSessionData` (which never sees cc-minted tokens) is not
+ * needed for prompts and tool sources to have values.
+ */
+export const PLAYGROUND_SESSION_HEADER = "X-Cortex-Playground-Session";
+
 /** A sandbox binding a piece of rich text mentions, so the turn can register it before the model reads the text. */
 export const mentionedToolSchema = z.object({
     toolId: z.uuid(),
     name: z.string().regex(TOOL_NAME_PATTERN),
     readOnly: z.boolean(),
+    variables: boundVariablesSchema,
 });
 
 export const skillBodyResponseSchema = z.object({
@@ -252,6 +274,22 @@ export const triggerDeclarationSchema = z.object({
     secretHash: sha256HexSchema,
 });
 
+/**
+ * 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.
+ */
+export const agentDeclarationSchema = z.object({
+    slug: agentSlugSchema,
+    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", [
     z.object({
         firingId: z.uuid(),
@@ -308,7 +346,10 @@ export const triggerAuthResponseSchema = z.discriminatedUnion("ok", [
 ]);
 
 export const runtimeAgentConfigSchema = z.object({
+    /** The slug the request used: the agent's own or one of the server's aliases. */
     agentId: agentSlugSchema,
+    /** The agent's own slug, the key of its `agents` entry in server code. Equals `agentId` unless an alias was used. */
+    slug: agentSlugSchema,
     /**
      * End-user JWT verification for this agent, managed by the agent's owner.
      * Tokens must be asymmetrically signed (the JWKS URI serves the public
@@ -326,7 +367,8 @@ export const runtimeAgentConfigSchema = z.object({
         })
         .optional(),
     systemPrompt: z.string(),
-    promptVariables: z.array(z.enum(PROMPT_VARIABLES)),
+    /** 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
@@ -351,6 +393,8 @@ 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,
     /** Absent from older Control Centers; reports then carry only the slug. */
     agentRef: agentRefSchema.optional(),
     catalogVersion: catalogVersionSchema,
@@ -425,6 +469,8 @@ export const executeRequestSchema = z.object({
             threadId: z.string().max(128).optional(),
             userId: z.string().max(128).optional(),
             locale: localeSchema.optional(),
+            /** Values of the variables the tool's input reads; only those names travel. */
+            variables: z.record(z.string(), z.unknown()).optional(),
         })
         .optional(),
 });
@@ -561,17 +607,13 @@ export const syncEventSchema = z.discriminatedUnion("type", [
         createdAt: z.iso.datetime(),
         finishedAt: z.iso.datetime().nullable(),
     }),
-    // Every code trigger the server declares, sent whole at boot so cc can
-    // list them read-only beside its own. Replaces the server's previous
-    // declaration, so an agent removed from code takes its triggers with it.
+    // 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.
     z.object({
-        type: z.literal("trigger.declare"),
+        type: z.literal("agent.declare"),
         id: z.uuid(),
-        triggers: z.array(
-            triggerDeclarationSchema
-                .pick({ name: true, description: true, input: true, thread: true })
-                .extend({ agentSlug: agentSlugSchema }),
-        ),
+        agents: z.array(agentDeclarationSchema),
         createdAt: z.iso.datetime(),
     }),
 ]);
@@ -612,6 +654,8 @@ 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 VariableDeclaration = z.infer<typeof variableDeclarationSchema>;
 export type TriggerThreadPolicy = z.infer<typeof triggerThreadPolicySchema>;
 export type TriggerOutcome = (typeof TRIGGER_OUTCOMES)[number];
 export type TriggerDropReason = (typeof TRIGGER_DROP_REASONS)[number];

package/src/contracts/wire/index.ts

@@ -21,6 +21,9 @@ export const MAX_ATTACHMENTS_PER_MESSAGE = 5;
 
 export const ATTACHMENT_STATUSES = ["pending", "described", "failed", "skipped"] as const;
 
+/** Who put the file in the thread: the user through the composer, or a tool mid-turn. */
+export const ATTACHMENT_ORIGINS = ["upload", "tool"] as const;
+
 export function checkAttachmentPolicy(contentType: string, sizeBytes: number) {
     if (!ATTACHMENT_MIME_TYPES.some((type) => type === contentType)) return "type";
     if (sizeBytes > ATTACHMENT_MAX_BYTES) return "size";
@@ -29,12 +32,15 @@ export function checkAttachmentPolicy(contentType: string, sizeBytes: number) {
 
 export type AttachmentStatus = (typeof ATTACHMENT_STATUSES)[number];
 
+export type AttachmentOrigin = (typeof ATTACHMENT_ORIGINS)[number];
+
 export type AttachmentSummary = {
     id: string;
     filename: string;
     contentType: string;
     sizeBytes: number;
     status: AttachmentStatus;
+    origin: AttachmentOrigin;
     description?: string;
 };
 
@@ -81,6 +87,8 @@ export type ClientToolBinding = {
     toolId: string;
     surface: "inline" | "modal";
     embedOrigin: string;
+    /** Variables the initiate call's input reads. */
+    variables: string[];
 };
 
 /**
@@ -91,6 +99,8 @@ 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[]>;
 };
 
 export type MessageMetadata = {