@m6d/cortex-cli 1.7.0 → 1.8.0

package/package.json

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

package/src/contracts/rich-text/index.ts

@@ -1,47 +1,82 @@
 /*
  * The grammar and rendering pipeline for user-authored rich text that reaches
- * the LLM (agent prompts, service descriptions). Both sides of the wire share
- * it: the console edits and validates these strings, the console's runtime API
- * pre-renders them (mentions + heading demotion), and `@m6d/cortex-server`
- * applies per-request variable values. Two token grammars live here:
+ * the LLM (agent prompts, service descriptions, skill bodies). Both sides of
+ * the wire share it: the console edits and validates these strings, the
+ * console's runtime API pre-renders them (mentions + heading demotion), and
+ * `@m6d/cortex-server` applies per-request variable values. Three token
+ * grammars live here:
  *
- * - Tool mentions `@[name](uuid)` — the uuid is authoritative; the inline name
- *   is only a display cache refreshed on save ({@link normalizeMentions}) and
- *   resolved live when text is rendered for the LLM ({@link renderMentions}).
+ * - Tool mentions `@[name](uuid)` and skill mentions `/[name](uuid)` — the
+ *   uuid is authoritative; the inline name is only a display cache refreshed
+ *   on save ({@link normalizeMentions}) and resolved live when text is
+ *   rendered for the LLM ({@link renderMentions}).
  * - Variables `{{name}}` — validated against a known list at authoring time
  *   ({@link analyzeVariables}) and substituted per request on the server
  *   ({@link substituteVariables}).
  */
 
-/** One mention token, unanchored and flagless — the editor's tokenizer anchors it, the helpers below add `g`. */
-export const MENTION_PATTERN_SOURCE = String.raw`@\[([^\]\n]*)\]\(([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\)`;
+const UUID = String.raw`[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}`;
+
+/** One tool mention token, unanchored and flagless — the editor's tokenizer anchors it, the helpers below add `g`. */
+export const MENTION_PATTERN_SOURCE = String.raw`@\[([^\]\n]*)\]\((${UUID})\)`;
+/** One skill mention token; `/` is the slash-command convention skills already carry elsewhere. */
+export const SKILL_MENTION_PATTERN_SOURCE = String.raw`/\[([^\]\n]*)\]\((${UUID})\)`;
 
 const MENTION_PATTERN = new RegExp(MENTION_PATTERN_SOURCE, "g");
+const SKILL_MENTION_PATTERN = new RegExp(SKILL_MENTION_PATTERN_SOURCE, "g");
 
 const VARIABLE_PATTERN = /{{\s*([^{}]*?)\s*}}/g;
 
-export function extractMentionedToolIds(text: string) {
+/** Entity names by id for the two mention grammars; a missing map leaves that grammar's cached names in place. */
+export type MentionNames = {
+    tools?: ReadonlyMap<string, string>;
+    skills?: ReadonlyMap<string, string>;
+};
+
+const NO_NAMES: ReadonlyMap<string, string> = new Map();
+
+function extractIds(text: string, pattern: RegExp) {
     const ids: string[] = [];
-    for (const match of text.matchAll(MENTION_PATTERN)) {
+    for (const match of text.matchAll(pattern)) {
         const id = match[2];
         if (id && !ids.includes(id)) ids.push(id);
     }
     return ids;
 }
 
-/** Replaces each mention token with the tool's current name (falling back to the cached inline name). */
-export function renderMentions(text: string, toolNameById: ReadonlyMap<string, string>) {
-    return text.replace(MENTION_PATTERN, (_, cachedName: string, toolId: string) => {
-        return toolNameById.get(toolId) ?? cachedName;
-    });
+export function extractMentionedToolIds(text: string) {
+    return extractIds(text, MENTION_PATTERN);
+}
+
+export function extractMentionedSkillIds(text: string) {
+    return extractIds(text, SKILL_MENTION_PATTERN);
+}
+
+/** Replaces each mention token with the entity's current name (falling back to the cached inline name). */
+export function renderMentions(text: string, names: MentionNames) {
+    const tools = names.tools ?? NO_NAMES;
+    const skills = names.skills ?? NO_NAMES;
+    return text
+        .replace(MENTION_PATTERN, (_, cached: string, id: string) => tools.get(id) ?? cached)
+        .replace(
+            SKILL_MENTION_PATTERN,
+            (_, cached: string, id: string) => skills.get(id) ?? cached,
+        );
 }
 
 /** Refreshes stale display names inside stored text, keeping the tokens intact. */
-export function normalizeMentions(text: string, toolNameById: ReadonlyMap<string, string>) {
-    return text.replace(MENTION_PATTERN, (token, _cachedName: string, toolId: string) => {
-        const name = toolNameById.get(toolId);
-        return name === undefined ? token : `@[${name}](${toolId})`;
-    });
+export function normalizeMentions(text: string, names: MentionNames) {
+    const tools = names.tools ?? NO_NAMES;
+    const skills = names.skills ?? NO_NAMES;
+    return text
+        .replace(MENTION_PATTERN, (token, _cached: string, id: string) => {
+            const name = tools.get(id);
+            return name === undefined ? token : `@[${name}](${id})`;
+        })
+        .replace(SKILL_MENTION_PATTERN, (token, _cached: string, id: string) => {
+            const name = skills.get(id);
+            return name === undefined ? token : `/[${name}](${id})`;
+        });
 }
 
 /** Splits the `{{variables}}` referenced in a text into known and unknown ones. */
@@ -65,7 +100,7 @@ export function analyzeVariables<Variable extends string>(
 
 /** Fills `{{variables}}` with per-request values; unknown names stay verbatim. */
 export function substituteVariables(text: string, values: Record<string, string>) {
-    return text.replace(/\{\{(\w+)\}\}/g, (match, name: string) => values[name] ?? match);
+    return text.replace(VARIABLE_PATTERN, (match, name: string) => values[name] ?? match);
 }
 
 /**
@@ -164,23 +199,21 @@ export function demoteHeadings(text: string) {
 }
 
 /** The one render step for LLM-bound rich text: resolve mentions, then demote headings. */
-export function renderRichText(text: string, toolNameById: ReadonlyMap<string, string>) {
-    return demoteHeadings(renderMentions(text, toolNameById));
+export function renderRichText(text: string, names: MentionNames) {
+    return demoteHeadings(renderMentions(text, names));
 }
 
 /**
- * Reduces rich text to plain prose for embeddings: mentions become tool names
- * (cached inline names when no map is given) and markdown syntax is dropped.
+ * Reduces rich text to plain prose for embeddings: mentions become entity
+ * names (cached inline names when no map is given) and markdown syntax is
+ * dropped.
  * ponytail: a regex stripper, not a markdown parser — nested emphasis or exotic
  * constructs may leave residue; swap in a real parser if retrieval quality
  * ever shows it.
  */
-export function stripToPlaintext(
-    text: string,
-    toolNameById: ReadonlyMap<string, string> = new Map(),
-) {
+export function stripToPlaintext(text: string, names: MentionNames = {}) {
     const lineState = fenceTracker();
-    return renderMentions(text, toolNameById)
+    return renderMentions(text, names)
         .split("\n")
         .filter((line) => {
             const state = lineState(line);

package/src/contracts/runtime/index.ts

@@ -117,17 +117,196 @@ export const toolSignatureSchema = z.object({
     inputSchema: z.record(z.string(), z.unknown()).optional(),
 });
 
+/** Consumer-facing slugs: service keys and skill names share it, the model types both. */
+export const SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+/**
+ * One always-listed skill line. The description is the whole trigger: the
+ * model reads it every turn and calls `loadSkill` when it matches the task.
+ */
+export const skillLineSchema = z.object({
+    name: z.string().regex(SLUG_PATTERN).max(64),
+    description: z.string().max(500),
+});
+
 export const serviceCardSchema = z.object({
     serviceId: z.uuid(),
-    key: z
-        .string()
-        .regex(/^[a-z0-9]+(-[a-z0-9]+)*$/)
-        .max(64),
+    key: z.string().regex(SLUG_PATTERN).max(64),
     name: z.string(),
     card: z.string(),
     score: z.number(),
+    /** Skills scoped to this service; listed only while the card is in context. Defaulted so an older Control Center still parses. */
+    skills: z.array(skillLineSchema).default([]),
+});
+
+/**
+ * A skill body served on `loadSkill`: mentions rendered to current names and
+ * headings demoted by the console, `{{variables}}` left for the server to
+ * fill per request. `mentionedTools` are the sandbox bindings the body
+ * refers to, so the turn can register them before the model acts on it.
+ */
+/**
+ * Opaque handle the Control Center assigns a resolved agent. Servers echo it
+ * on reports about that agent so they attach to it even if the slug or alias
+ * they used later moves.
+ */
+export const agentRefSchema = z.string().max(128);
+
+/**
+ * Response header carrying the resolved agent's ref on every agent-scoped
+ * runtime answer, errors included, so a server can attribute a request even
+ * when the body is an error envelope. Absent only when no agent resolved.
+ */
+export const AGENT_REF_HEADER = "X-CC-Agent-Ref";
+
+/** 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(),
+});
+
+export const skillBodyResponseSchema = z.object({
+    name: z.string(),
+    body: z.string(),
+    mentionedTools: z.array(mentionedToolSchema),
+    catalogVersion: catalogVersionSchema,
+});
+
+/*
+ * Triggers: named entry points on an agent. A firing is one invocation with a
+ * payload and starts at most one run. The end user's message is the built-in
+ * `message` trigger; every other trigger is fired by an external caller over
+ * `POST /agents/:agentId/triggers/:name` with the trigger's own secret.
+ */
+
+export const MESSAGE_TRIGGER_NAME = "message";
+
+/**
+ * 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
+ * the Control Center signed, so a server verifies it against the Control
+ * Center's JWKS before saying a word to it, and the Control Center then
+ * consumes it so it fires once.
+ */
+export const TRIGGER_SECRET_PREFIXES = { live: "tr_live_", test: "tr_test_" } as const;
+export const TRIGGER_TEST_TOKEN_AUDIENCE = "cortex:trigger-test";
+
+/** The claims a test token carries beside the standard ones; the server checks them against the route it arrived on. */
+export const triggerTestTokenClaimsSchema = z.object({
+    agent: agentSlugSchema,
+    trigger: z.string().regex(SLUG_PATTERN).max(64),
+});
+
+const sha256HexSchema = z.string().regex(/^[0-9a-f]{64}$/);
+
+export const TRIGGER_OUTCOMES = [
+    "started",
+    "completed",
+    "failed",
+    "rejected",
+    "dropped",
+    "disabled",
+] as const;
+
+/** Why a firing was dropped: the thread was busy, or the daily budget was spent. */
+export const TRIGGER_DROP_REASONS = ["busy", "budget"] as const;
+
+export const TRIGGER_SOURCES = ["code", "cc"] as const;
+
+/**
+ * Which thread a firing lands in. `single`: one thread for the trigger.
+ * `per-firing`: a fresh thread every time. `keyed`: one thread per distinct
+ * value at a JSON pointer into the payload (e.g. `/pull_request/number`).
+ */
+export const triggerThreadPolicySchema = z.discriminatedUnion("policy", [
+    z.object({ policy: z.literal("single") }),
+    z.object({ policy: z.literal("per-firing") }),
+    z.object({ policy: z.literal("keyed"), key: z.string().regex(/^\//).max(256) }),
+]);
+
+/** A trigger as both sides describe it. Secrets and credentials never cross this contract. */
+export const triggerDeclarationSchema = z.object({
+    name: z.string().regex(SLUG_PATTERN).max(64),
+    description: z.string().max(500),
+    /** JSON Schema for the payload; cc triggers are validated from it on the server. */
+    input: z.record(z.string(), z.unknown()),
+    /**
+     * The prompt the run starts from, mentions already rendered to names by
+     * the console; `{{variables}}` and `{{/json/pointer}}` payload fields
+     * are the server's to fill per firing.
+     */
+    instructions: z.string().max(20_000),
+    /** Tools the instructions mention, registered as sandbox bindings for the run. Defaulted so an older Control Center still parses. */
+    mentionedTools: z.array(mentionedToolSchema).default([]),
+    thread: triggerThreadPolicySchema.default({ policy: "single" }),
+    budgetPerDay: z.number().int().positive().nullable().default(null),
+    /** Consecutive failed or rejected firings before the trigger disables itself. */
+    disableAfterFailures: z.number().int().positive().default(5),
+    hasCredential: z.boolean().default(false),
+    /**
+     * sha256 of the fire secret, so a server checks a presented bearer in
+     * process; the Control Center hears only about console test secrets,
+     * which it alone can consume.
+     */
+    secretHash: sha256HexSchema,
+});
+
+export const triggerFiringResponseSchema = z.discriminatedUnion("outcome", [
+    z.object({
+        firingId: z.uuid(),
+        outcome: z.literal("started"),
+        threadId: z.uuid(),
+        runId: z.string(),
+    }),
+    z.object({
+        firingId: z.uuid(),
+        outcome: z.literal("dropped"),
+        reason: z.enum(TRIGGER_DROP_REASONS),
+        threadId: z.uuid().nullable(),
+    }),
+    z.object({ firingId: z.uuid(), outcome: z.literal("disabled") }),
+    z.object({
+        firingId: z.uuid(),
+        outcome: z.literal("rejected"),
+        issues: z.array(z.object({ path: z.string(), message: z.string() })),
+    }),
+]);
+
+export const triggerFiringSchema = z.object({
+    id: z.uuid(),
+    triggerName: z.string(),
+    threadId: z.uuid().nullable(),
+    runId: z.string().nullable(),
+    outcome: z.enum(TRIGGER_OUTCOMES),
+    reason: z.string().nullable(),
+    createdAt: z.iso.datetime(),
+    finishedAt: z.iso.datetime().nullable(),
+});
+
+export const triggerFiringListResponseSchema = z.object({
+    firings: z.array(triggerFiringSchema),
+});
+
+/**
+ * `POST /api/runtime/agents/:id/triggers/:name/auth`: a server holding a
+ * bearer for a cc trigger asks cc whether it is the trigger's secret. Only the
+ * hash travels; a positive answer carries the trigger's credential, if any.
+ */
+export const triggerAuthRequestSchema = z.object({
+    secretHash: sha256HexSchema,
 });
 
+export const triggerAuthResponseSchema = z.discriminatedUnion("ok", [
+    z.object({
+        ok: z.literal(true),
+        credential: z.string().nullable(),
+        /** The bearer was a single-use test secret, now spent: the server must not cache this verdict. */
+        oneShot: z.boolean().optional(),
+    }),
+    z.object({ ok: z.literal(false) }),
+]);
+
 export const runtimeAgentConfigSchema = z.object({
     agentId: agentSlugSchema,
     /**
@@ -166,6 +345,14 @@ export const runtimeAgentConfigSchema = z.object({
         executeTimeoutMs: z.number().int().positive(),
         maxResponseBytes: z.number().int().positive(),
     }),
+    /** Unscoped published skills; service-scoped ones travel on their card. Defaulted so an older Control Center still parses. */
+    skills: z.array(skillLineSchema).default([]),
+    /** Published triggers. Defaulted so an older Control Center still parses. */
+    triggers: z.array(triggerDeclarationSchema).default([]),
+    /** Whether end users may message this agent; false makes it headless. */
+    messageTrigger: z.boolean().default(true),
+    /** Absent from older Control Centers; reports then carry only the slug. */
+    agentRef: agentRefSchema.optional(),
     catalogVersion: catalogVersionSchema,
     publishedAt: z.iso.datetime(),
 });
@@ -299,7 +486,8 @@ export const tokenUsageSchema = z.object({
     total: tokenCountSchema,
 });
 
-export const MESSAGE_ROLES = ["system", "user", "assistant", "tool"] as const;
+/** `trigger` rows hold a firing's rendered instructions; the model sees them as `user` turns. */
+export const MESSAGE_ROLES = ["system", "user", "assistant", "tool", "trigger"] as const;
 
 export const syncEventSchema = z.discriminatedUnion("type", [
     z.object({
@@ -309,6 +497,9 @@ export const syncEventSchema = z.discriminatedUnion("type", [
         userId: z.string().max(255),
         title: z.string().max(256).nullable(),
         isTest: z.boolean(),
+        /** Set on headless threads a trigger owns; `userId` is then a sentinel. */
+        triggerName: z.string().max(64).nullable().default(null),
+        triggerKey: z.string().max(256).nullable().default(null),
         createdAt: z.iso.datetime(),
         updatedAt: z.iso.datetime(),
     }),
@@ -337,6 +528,52 @@ export const syncEventSchema = z.discriminatedUnion("type", [
         // column, but the mirror needs one for time-bucketed usage stats.
         createdAt: z.iso.datetime(),
     }),
+    // One loadSkill call, hit or miss, from either skill source. Bounded by
+    // construction (no body travels), so it can never trip the size cap.
+    z.object({
+        type: z.literal("skill.load"),
+        id: z.uuid(),
+        threadId: z.uuid(),
+        agentSlug: agentSlugSchema,
+        /** The ref cc issued for the agent that answered; a code-only agent or a miss has none. */
+        agentRef: agentRefSchema.optional(),
+        /** As the model asked for it, even when nothing answered. */
+        skillName: z.string().max(64),
+        source: z.enum(["code", "cc"]).nullable(),
+        hit: z.boolean(),
+        /** The user message this turn answers; the mirror joins it for the drill-down. */
+        messageId: z.string().max(128),
+        createdAt: z.iso.datetime(),
+    }),
+    // One firing, upserted on start and again on its terminal outcome; the
+    // firing id is the event id so both land on one mirror row.
+    z.object({
+        type: z.literal("trigger.firing"),
+        id: z.uuid(),
+        agentSlug: agentSlugSchema,
+        agentRef: agentRefSchema.optional(),
+        triggerName: z.string().max(64),
+        source: z.enum(TRIGGER_SOURCES),
+        threadId: z.uuid().nullable(),
+        runId: z.string().max(64).nullable(),
+        outcome: z.enum(TRIGGER_OUTCOMES),
+        reason: z.string().max(64).nullable(),
+        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.
+    z.object({
+        type: z.literal("trigger.declare"),
+        id: z.uuid(),
+        triggers: z.array(
+            triggerDeclarationSchema
+                .pick({ name: true, description: true, input: true, thread: true })
+                .extend({ agentSlug: agentSlugSchema }),
+        ),
+        createdAt: z.iso.datetime(),
+    }),
 ]);
 
 /*
@@ -372,6 +609,18 @@ 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 SkillLine = z.infer<typeof skillLineSchema>;
+export type SkillBodyResponse = z.infer<typeof skillBodyResponseSchema>;
+export type TriggerDeclaration = z.infer<typeof triggerDeclarationSchema>;
+export type TriggerThreadPolicy = z.infer<typeof triggerThreadPolicySchema>;
+export type TriggerOutcome = (typeof TRIGGER_OUTCOMES)[number];
+export type TriggerDropReason = (typeof TRIGGER_DROP_REASONS)[number];
+export type TriggerSource = (typeof TRIGGER_SOURCES)[number];
+export type TriggerFiringResponse = z.infer<typeof triggerFiringResponseSchema>;
+export type TriggerFiring = z.infer<typeof triggerFiringSchema>;
+export type TriggerFiringListResponse = z.infer<typeof triggerFiringListResponseSchema>;
+export type TriggerAuthRequest = z.infer<typeof triggerAuthRequestSchema>;
+export type TriggerAuthResponse = z.infer<typeof triggerAuthResponseSchema>;
 export type SearchRequest = z.input<typeof searchRequestSchema>;
 export type ExecuteRequest = z.input<typeof executeRequestSchema>;
 export type SyncEvent = z.infer<typeof syncEventSchema>;

package/src/contracts/wire/index.ts

@@ -44,6 +44,8 @@ export type ThreadSummary = {
     createdAt: string;
     updatedAt: string;
     isRunning: boolean;
+    /** Present on a headless thread a trigger owns. Widgets never list these. */
+    trigger?: { name: string };
 };
 
 /**
@@ -87,6 +89,8 @@ export type ClientToolBinding = {
  */
 export type AgentCapabilities = {
     attachments: boolean;
+    /** False when the agent's `message` trigger is off: the widget hides its composer. */
+    messages: boolean;
 };
 
 export type MessageMetadata = {
@@ -96,6 +100,15 @@ export type MessageMetadata = {
     tokenUsage?: TokenUsage;
     attachments?: AttachmentSummary[];
     clientTools?: Record<string, ClientToolBinding>;
+    /** Set on `trigger` messages: the firing that wrote them. */
+    trigger?: TriggerFiringSummary;
+};
+
+export type TriggerFiringSummary = {
+    name: string;
+    firingId: string;
+    firedAt: string;
+    payload: unknown;
 };
 
 /**
@@ -108,7 +121,8 @@ export type MessageMetadata = {
  */
 export type CortexMessage<TPart = unknown> = {
     id: string;
-    role: "system" | "user" | "assistant";
+    /** `trigger` rows carry a firing's instructions; the UIs render them as an event, not a bubble. */
+    role: "system" | "user" | "assistant" | "trigger";
     parts: TPart[];
     metadata?: MessageMetadata;
 };