@m6d/cortex-cli 1.7.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@m6d/cortex-cli",
-    "version": "1.7.0",
+    "version": "1.9.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

@@ -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",
@@ -101,6 +81,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 +97,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
@@ -117,19 +105,228 @@ 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";
+
+/**
+ * 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({
+    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,
+});
+
+/**
+ * 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(),
+        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({
+    /** 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
@@ -147,7 +344,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
@@ -166,6 +364,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(),
 });
@@ -238,6 +444,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(),
 });
@@ -299,7 +507,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 +518,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 +549,48 @@ 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(),
+    }),
+    // 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("agent.declare"),
+        id: z.uuid(),
+        agents: z.array(agentDeclarationSchema),
+        createdAt: z.iso.datetime(),
+    }),
 ]);
 
 /*
@@ -372,6 +626,20 @@ 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 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];
+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

@@ -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;
 };
 
@@ -44,6 +50,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 };
 };
 
 /**
@@ -79,6 +87,8 @@ export type ClientToolBinding = {
     toolId: string;
     surface: "inline" | "modal";
     embedOrigin: string;
+    /** Variables the initiate call's input reads. */
+    variables: string[];
 };
 
 /**
@@ -87,6 +97,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 +108,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 +129,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;
 };