@m6d/cortex-cli 0.3.0 → 0.4.0

package/src/contracts/runtime/dataset-sql.ts

@@ -1,3 +1,4 @@
+import { isRecord } from "../json";
 import type {
     DatasetAggregate,
     DatasetArithmeticOp,
@@ -443,10 +444,10 @@ class Parser {
         const from = this.identifier("FROM needs a dataset name.");
         const alias = this.optionalAlias();
         const joins = this.joins();
-        const filter = this.peekWord("WHERE") ? (this.take(), this.predicates()) : [];
+        const filter = this.optionalWord("WHERE") ? this.predicates() : [];
         const groupBy = this.groupBy();
-        const having = this.peekWord("HAVING") ? (this.take(), this.predicates()) : [];
-        const qualify = this.peekWord("QUALIFY") ? (this.take(), this.predicates()) : [];
+        const having = this.optionalWord("HAVING") ? this.predicates() : [];
+        const qualify = this.optionalWord("QUALIFY") ? this.predicates() : [];
         return {
             from,
             aliases: alias === undefined ? [] : [alias],
@@ -564,14 +565,11 @@ class Parser {
         const joins: JoinClause[] = [];
         for (;;) {
             const inner = !this.peekWord("LEFT");
-            if (this.peekWord("INNER") || this.peekWord("LEFT")) {
-                this.take();
-                if (this.peekWord("OUTER")) this.take();
+            if (this.optionalWord("INNER") || this.optionalWord("LEFT")) {
+                this.optionalWord("OUTER");
                 this.expectWord("JOIN", "INNER and LEFT are followed by JOIN.");
-            } else if (!this.peekWord("JOIN")) {
+            } else if (!this.optionalWord("JOIN")) {
                 return joins;
-            } else {
-                this.take();
             }
             const dataset = this.identifier("JOIN needs a dataset name.");
             const alias = this.optionalAlias();
@@ -602,8 +600,7 @@ class Parser {
         this.take();
         this.expectPunct("(", "OVER is followed by () or (PARTITION BY ...).");
         let partitionBy: Term[] = [];
-        if (this.peekWord("PARTITION")) {
-            this.take();
+        if (this.optionalWord("PARTITION")) {
             this.expectWord("BY", "PARTITION is followed by BY.");
             partitionBy = this.termList("PARTITION BY takes column names or aliases.");
         }
@@ -619,7 +616,7 @@ class Parser {
             }
             return { fn: base, term: undefined, filter: [] as Predicate[] };
         }
-        const distinct = this.peekWord("DISTINCT") ? (this.take(), true) : false;
+        const distinct = this.optionalWord("DISTINCT");
         if (distinct && base !== "count") {
             throw new DatasetSqlError(
                 `DISTINCT is only valid inside COUNT; ${word}(DISTINCT ...) is not.`,
@@ -636,8 +633,7 @@ class Parser {
     }
 
     private filterClause() {
-        if (!this.peekWord("FILTER")) return [] as Predicate[];
-        this.take();
+        if (!this.optionalWord("FILTER")) return [] as Predicate[];
         this.expectPunct("(", "FILTER is written FILTER (WHERE condition).");
         this.expectWord("WHERE", "FILTER is written FILTER (WHERE condition).");
         const filter = this.predicates();
@@ -760,16 +756,18 @@ class Parser {
         } satisfies Term;
     }
 
-    /** `CASE WHEN p THEN v [WHEN ...] [ELSE v] END`; ELSE NULL is the same as no ELSE. */
-    /** `CASE WHEN p THEN v ... END`, or the simple form `CASE x WHEN v THEN r ... END` where each WHEN compares x with a value. */
+    /**
+     * `CASE WHEN p THEN v [WHEN ...] [ELSE v] END`, or the simple form
+     * `CASE x WHEN v THEN r ... END` where each WHEN compares x with a value.
+     * ELSE NULL is the same as no ELSE.
+     */
     private caseTerm() {
         this.take();
         const subject = this.peekWord("WHEN")
             ? undefined
             : this.term("CASE is followed by WHEN, or by a value to compare.");
         const branches: { when: Predicate[]; then: Term }[] = [];
-        while (this.peekWord("WHEN")) {
-            this.take();
+        while (this.optionalWord("WHEN")) {
             const when = subject ? [this.simpleCaseMatch(subject)] : this.predicates();
             this.expectWord("THEN", "CASE WHEN condition needs THEN value.");
             if (this.peekWord("NULL")) {
@@ -788,10 +786,8 @@ class Parser {
             );
         }
         let otherwise: Term | undefined;
-        if (this.peekWord("ELSE")) {
-            this.take();
-            if (this.peekWord("NULL")) this.take();
-            else otherwise = this.term("ELSE takes a column, a literal or arithmetic.");
+        if (this.optionalWord("ELSE") && !this.optionalWord("NULL")) {
+            otherwise = this.term("ELSE takes a column, a literal or arithmetic.");
         }
         this.expectWord("END", "CASE ... needs END.");
         return {
@@ -802,31 +798,24 @@ class Parser {
     }
 
     /** `a AND b OR c AND (d OR e)`: AND binds tighter than OR; the result is an AND list whose OR parts are `any` groups. */
-    // eslint-disable-next-line m6d/no-explicit-return-type -- mutually recursive with predicate through parenthesized groups
-    private predicates(): Predicate[] {
+    private predicates() {
         const branches = [this.conjunction()];
-        while (this.peekWord("OR")) {
-            this.take();
-            branches.push(this.conjunction());
-        }
+        while (this.optionalWord("OR")) branches.push(this.conjunction());
         if (branches.length === 1) return branches[0]!;
-        return [{ kind: "any", of: branches.map((branch) => grouped(branch)) }];
+        return [{ kind: "any", of: branches.map((branch) => grouped(branch)) } satisfies Predicate];
     }
 
     private conjunction() {
         const predicates: Predicate[] = [];
         do {
             predicates.push(this.predicate());
-        } while (this.peekWord("AND") && this.take());
+        } while (this.optionalWord("AND"));
         return predicates;
     }
 
     /** `NOT p`, `(p AND q)`, `RANK() OVER (...) <= n` or a condition. */
     private predicate(): Predicate {
-        if (this.peekWord("NOT")) {
-            this.take();
-            return { kind: "not", of: this.predicate() };
-        }
+        if (this.optionalWord("NOT")) return { kind: "not", of: this.predicate() };
         if (this.peekRank()) {
             const window = this.rankWindow(WINDOW_PLACE);
             return { kind: "rank", ...window, limit: this.rankLimit("RANK()") };
@@ -858,7 +847,7 @@ class Parser {
         const left = this.term("A condition starts with a column name.");
         const shown = describeTerm(left);
         if (this.peekWord("IS")) return this.nullCheck(left);
-        const negated = this.peekWord("NOT") ? (this.take(), true) : false;
+        const negated = this.optionalWord("NOT");
         if (this.peekWord("IN")) return this.inList(left, negated);
         let condition: Predicate;
         if (this.peekWord("BETWEEN")) condition = this.between(left);
@@ -910,7 +899,7 @@ class Parser {
 
     private nullCheck(left: Term) {
         this.take();
-        const negated = this.peekWord("NOT") ? (this.take(), true) : false;
+        const negated = this.optionalWord("NOT");
         this.expectWord("NULL", "IS is followed by NULL or NOT NULL.");
         return { kind: "cond", left, op: negated ? "isNotNull" : "isNull" } satisfies Predicate;
     }
@@ -954,10 +943,7 @@ class Parser {
             return { kind: "cond", left, op: "=", value: true } satisfies Predicate;
         }
         const operator = this.take();
-        if (
-            operator.kind !== "punct" ||
-            !["=", "!=", "<>", "<", "<=", ">", ">="].includes(operator.value)
-        ) {
+        if (operator.kind !== "punct" || !COMPARISONS.includes(operator.value)) {
             throw new DatasetSqlError(
                 `"${shown}" needs a comparison: = != < <= > >= IN BETWEEN LIKE IS NULL.`,
             );
@@ -1099,7 +1085,7 @@ class Parser {
             );
         }
         if (RANK_WORDS.includes(upper)) throw new DatasetSqlError(WINDOW_PLACE);
-        if (word.upper === "NULLIF") {
+        if (upper === "NULLIF") {
             throw new DatasetSqlError(
                 "NULLIF() is not needed: a division by zero is already null, so write a / b.",
             );
@@ -1108,8 +1094,7 @@ class Parser {
     }
 
     private groupBy() {
-        if (!this.peekWord("GROUP")) return [] as Term[];
-        this.take();
+        if (!this.optionalWord("GROUP")) return [] as Term[];
         this.expectWord("BY", "GROUP is followed by BY.");
         const items: Term[] = [];
         do {
@@ -1125,8 +1110,7 @@ class Parser {
     }
 
     private orderBy() {
-        if (!this.peekWord("ORDER")) return [] as SortList;
-        this.take();
+        if (!this.optionalWord("ORDER")) return [] as SortList;
         this.expectWord("BY", "ORDER is followed by BY.");
         return this.sortList();
     }
@@ -1138,17 +1122,15 @@ class Parser {
             if (term.kind === "num") {
                 throw new DatasetSqlError("ORDER BY names columns or aliases, not positions.");
             }
-            const dir = this.peekWord("DESC")
-                ? (this.take(), "desc" as const)
-                : (this.peekWord("ASC") && this.take(), "asc" as const);
-            items.push({ term, dir });
+            const descending = this.optionalWord("DESC");
+            if (!descending) this.optionalWord("ASC");
+            items.push({ term, dir: descending ? "desc" : "asc" });
         } while (this.optionalPunct(","));
         return items;
     }
 
     private limit() {
-        if (!this.peekWord("LIMIT")) return undefined;
-        this.take();
+        if (!this.optionalWord("LIMIT")) return undefined;
         const count = this.take();
         if (count.kind !== "number" || !Number.isInteger(count.value) || count.value < 1) {
             throw new DatasetSqlError("LIMIT takes a positive whole number.");
@@ -1157,8 +1139,7 @@ class Parser {
     }
 
     private offset(sorted: boolean) {
-        if (!this.peekWord("OFFSET")) return undefined;
-        this.take();
+        if (!this.optionalWord("OFFSET")) return undefined;
         const count = this.take();
         if (count.kind !== "number" || !Number.isInteger(count.value) || count.value < 0) {
             throw new DatasetSqlError("OFFSET takes a whole number.");
@@ -1177,8 +1158,7 @@ class Parser {
         if (!isName(token)) throw new DatasetSqlError(message);
         this.take();
         let ref = token.value;
-        while (this.peekPunct(".")) {
-            this.take();
+        while (this.optionalPunct(".")) {
             const next = this.take();
             if (next.kind !== "word")
                 throw new DatasetSqlError(`"${ref}." needs a column name after the dot.`);
@@ -1221,10 +1201,7 @@ class Parser {
     }
 
     private optionalAlias() {
-        if (this.peekWord("AS")) {
-            this.take();
-            return this.identifier("AS needs a name.");
-        }
+        if (this.optionalWord("AS")) return this.identifier("AS needs a name.");
         const token = this.peek();
         if (!isName(token)) return undefined;
         this.take();
@@ -1253,6 +1230,11 @@ class Parser {
         const token = this.peek();
         return token.kind === "word" && token.upper === upper;
     }
+    private optionalWord(upper: string) {
+        if (!this.peekWord(upper)) return false;
+        this.take();
+        return true;
+    }
     private peekPunct(value: string, offset = 0) {
         const token = this.peek(offset);
         return token.kind === "punct" && token.value === value;
@@ -1263,16 +1245,12 @@ class Parser {
         return true;
     }
     private expectWord(upper: string, message: string) {
-        if (!this.peekWord(upper)) {
-            const token = this.peek();
-            if (token.kind === "word" && token.upper in REFUSED_CLAUSES) {
-                throw new DatasetSqlError(
-                    REFUSED_CLAUSES[token.upper as keyof typeof REFUSED_CLAUSES],
-                );
-            }
-            throw new DatasetSqlError(message);
+        if (this.optionalWord(upper)) return;
+        const token = this.peek();
+        if (token.kind === "word" && token.upper in REFUSED_CLAUSES) {
+            throw new DatasetSqlError(REFUSED_CLAUSES[token.upper as keyof typeof REFUSED_CLAUSES]);
         }
-        this.take();
+        throw new DatasetSqlError(message);
     }
     private expectPunct(value: string, message: string) {
         if (!this.optionalPunct(value)) throw new DatasetSqlError(message);
@@ -1298,13 +1276,13 @@ function likeFilter(shown: string, pattern: string) {
 const COMPARISONS = ["=", "!=", "<>", "<", "<=", ">", ">="];
 const CONDITION_WORDS = ["AND", "OR", "NOT", "IN", "IS", "LIKE", "BETWEEN"];
 
-/** A token that can only appear inside a condition, never inside a value. */
 /** +1 on the opener, -1 on the closer, 0 otherwise; punctuation and words alike. */
 function nesting(token: Token, open: string, close: string) {
     const text = token.kind === "word" ? token.upper : token.kind === "punct" ? token.value : "";
     return text === open ? 1 : text === close ? -1 : 0;
 }
 
+/** A token that can only appear inside a condition, never inside a value. */
 function isConditionWord(token: Token) {
     if (token.kind === "punct") return COMPARISONS.includes(token.value);
     return token.kind === "word" && CONDITION_WORDS.includes(token.upper);
@@ -1425,7 +1403,7 @@ function predicateRefs(predicate: Predicate): string[] {
 function isTermValue(
     value: Extract<Predicate, { kind: "cond" }>["value"],
 ): value is { term: Term } {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
+    return isRecord(value);
 }
 
 /** Whether the term, or any value inside it (a window's operand and conditions included), passes `test`. */
@@ -1517,6 +1495,7 @@ function describeTerm(term: Term): string {
             return "CASE ... END";
     }
 }
+
 /**
  * The JOIN clause(s) that reach a relation, as `describeDataset` prints them
  * and refusals suggest them. Hosts always join left, so that is what is

package/src/contracts/runtime/datasets.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { isRecord } from "../json";
 
 /*
  * Datasets: governed tabular reads over a host's own data. A dataset host
@@ -170,11 +171,15 @@ export const datasetNamedOperandSchema = z.object({
     as: datasetIdentifierSchema,
 });
 export type DatasetNamedOperand = z.infer<typeof datasetNamedOperandSchema>;
-/** The left side of a condition: a column or arithmetic, never a bare number. */
+/**
+ * The left side of a condition: a column or arithmetic, never a bare number.
+ * Zod's refinement does not narrow the type, so the cast narrows it to what the
+ * refinement checks.
+ */
 const datasetConditionLeftSchema = datasetOperandSchema.refine(
     (operand) => typeof operand !== "number",
     "a condition starts with a column",
-);
+) as z.ZodType<DatasetCondition["col"], DatasetCondition["col"]>;
 
 export type DatasetCondition = {
     col: Exclude<DatasetOperand, number>;
@@ -183,10 +188,7 @@ export type DatasetCondition = {
     value?: string | number | boolean | (string | number | boolean)[] | { col: DatasetOperand };
 };
 export const datasetConditionSchema: z.ZodType<DatasetCondition, DatasetCondition> = z.object({
-    col: datasetConditionLeftSchema as z.ZodType<
-        Exclude<DatasetOperand, number>,
-        Exclude<DatasetOperand, number>
-    >,
+    col: datasetConditionLeftSchema,
     op: z.enum(DATASET_FILTER_OPS),
     value: z
         .union([
@@ -227,12 +229,7 @@ const datasetSortSchema = z.object({
 export const datasetAggregateSchema = z.object({
     fn: z.enum(DATASET_AGGREGATES),
     /** The column or arithmetic aggregated; `count` may omit it to count rows. */
-    col: (
-        datasetConditionLeftSchema as z.ZodType<
-            Exclude<DatasetOperand, number>,
-            Exclude<DatasetOperand, number>
-        >
-    )
+    col: datasetConditionLeftSchema
         .optional()
         .describe("The column or arithmetic to aggregate; omit for count."),
     as: datasetIdentifierSchema.describe(
@@ -480,25 +477,23 @@ function normalizeDatasetQuery(catalog: DatasetCatalog, query: DatasetQuery) {
         ...entry,
         expr: mapOperandRefs(entry.expr, strip),
     });
-    const groupBy = query.groupBy.map((group) =>
-        typeof group === "string" ? strip(group) : stripNamed(group),
-    );
-    const aggregate = query.aggregate.map((entry) => ({
+    // A window is an aggregate plus its partition, so both strip the same way.
+    const stripAggregate = (entry: DatasetQuery["aggregate"][number]) => ({
         ...entry,
         ...(entry.col === undefined
             ? {}
             : { col: mapOperandRefs(entry.col, strip) as DatasetCondition["col"] }),
         filter: entry.filter.map(stripFilter),
-    }));
+    });
+    const groupBy = query.groupBy.map((group) =>
+        typeof group === "string" ? strip(group) : stripNamed(group),
+    );
+    const aggregate = query.aggregate.map(stripAggregate);
     const filter = query.filter.map(stripFilter);
     const having = query.having.map(stripFilter);
     const compute = query.compute.map(stripNamed);
     const window = query.window.map((entry) => ({
-        ...entry,
-        ...(entry.col === undefined
-            ? {}
-            : { col: mapOperandRefs(entry.col, strip) as DatasetCondition["col"] }),
-        filter: entry.filter.map(stripFilter),
+        ...stripAggregate(entry),
         partitionBy: entry.partitionBy.map(strip),
     }));
     const qualify = query.qualify.map(stripFilter);
@@ -593,10 +588,9 @@ function mapFilterRefs(filter: DatasetFilter, fn: (ref: string) => string): Data
     if ("any" in filter) return { any: filter.any.map((entry) => mapFilterRefs(entry, fn)) };
     if ("all" in filter) return { all: filter.all.map((entry) => mapFilterRefs(entry, fn)) };
     if ("not" in filter) return { not: mapFilterRefs(filter.not, fn) };
-    const value =
-        typeof filter.value === "object" && filter.value !== null && !Array.isArray(filter.value)
-            ? { col: mapOperandRefs(filter.value.col, fn) }
-            : filter.value;
+    const value = isColumnValue(filter.value)
+        ? { col: mapOperandRefs(filter.value.col, fn) }
+        : filter.value;
     return {
         col: mapOperandRefs(filter.col, fn) as DatasetCondition["col"],
         op: filter.op,
@@ -605,7 +599,7 @@ function mapFilterRefs(filter: DatasetFilter, fn: (ref: string) => string): Data
 }
 
 /** Every column reference an operand names. */
-export function operandRefs(operand: DatasetOperand): string[] {
+function operandRefs(operand: DatasetOperand): string[] {
     if (typeof operand === "string") return [operand];
     if (typeof operand === "number" || "value" in operand) return [];
     if ("op" in operand) return [...operandRefs(operand.left), ...operandRefs(operand.right)];
@@ -633,7 +627,7 @@ export function filterRefs(filter: DatasetFilter): string[] {
 
 /** A condition's right side that names a column or arithmetic rather than a literal. */
 export function isColumnValue(value: DatasetCondition["value"]): value is { col: DatasetOperand } {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
+    return isRecord(value);
 }
 
 /**
@@ -1099,6 +1093,13 @@ export function describeOperand(operand: DatasetOperand): string {
     return `${operand.fn}(${operand.unit}, ${describeOperand(operand.of)})`;
 }
 
+/** `optional` counts the trailing arguments a call may leave out. */
+type FunctionSignature = {
+    args: readonly DatasetColumnType[];
+    optional?: number;
+    answers: DatasetColumnType | undefined;
+};
+
 /** What each scalar function takes and answers; `coalesce` answers its arguments' shared type. */
 export const FUNCTION_SIGNATURES = {
     lower: { args: ["string"], answers: "string" },
@@ -1108,14 +1109,7 @@ export const FUNCTION_SIGNATURES = {
     abs: { args: ["number"], answers: "number" },
     round: { args: ["number", "number"], optional: 1, answers: "number" },
     coalesce: { args: [], answers: undefined },
-} as const satisfies Record<
-    DatasetFunction,
-    {
-        args: readonly DatasetColumnType[];
-        optional?: number;
-        answers: DatasetColumnType | undefined;
-    }
->;
+} as const satisfies Record<DatasetFunction, FunctionSignature>;
 
 /**
  * The type an operand yields: the column's own, number for a literal number
@@ -1192,11 +1186,7 @@ function functionType(
     shown: string,
     expect: (side: DatasetOperand, wanted: DatasetColumnType, what: string) => boolean,
 ) {
-    const signature: {
-        args: readonly DatasetColumnType[];
-        optional?: number;
-        answers: DatasetColumnType | undefined;
-    } = FUNCTION_SIGNATURES[operand.fn];
+    const signature: FunctionSignature = FUNCTION_SIGNATURES[operand.fn];
     if (operand.fn === "coalesce") {
         if (operand.args.length < 2) {
             check.issue(refError(kind, shown, "coalesce takes two or more values"));
@@ -1224,7 +1214,7 @@ function functionType(
     return fine.every(Boolean) ? signature.answers : undefined;
 }
 
-const COLUMN_COMPARISONS: readonly DatasetFilterOp[] = ["=", "!=", "<", "<=", ">", ">="];
+const COLUMN_COMPARISONS = new Set<DatasetFilterOp>(["=", "!=", "<", "<=", ">", ">="]);
 
 function checkFilter(check: QueryCheck, filter: DatasetFilter, kind = "filter") {
     if ("not" in filter) {
@@ -1272,7 +1262,7 @@ function columnValueIssue(
     op: DatasetFilterOp,
     right: DatasetOperand,
 ) {
-    if (!COLUMN_COMPARISONS.includes(op)) return `${op} takes a literal, not a column`;
+    if (!COLUMN_COMPARISONS.has(op)) return `${op} takes a literal, not a column`;
     const rightType = operandType(check, kind, right);
     return rightType && rightType !== type ? `compares a ${type} with a ${rightType}` : undefined;
 }

package/src/contracts/runtime/grammar.ts

@@ -10,8 +10,12 @@ import { LOCALES, TOOL_SURFACES, type Greeting, type Suggestions } from "../wire
 export const AGENT_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
 export const agentSlugSchema = z.string().regex(AGENT_SLUG_PATTERN);
 
-/** Tool names become `tools.<name>()` sandbox bindings on the server. */
-export const TOOL_NAME_PATTERN = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+/**
+ * An ASCII JavaScript identifier: what a tool name (a `tools.<name>()` sandbox
+ * binding on the server) and a variable name must be, and what a rendered
+ * signature prints bare rather than quoted.
+ */
+export const IDENTIFIER_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 
 /** Consumer-facing slugs: service keys, skill names, and trigger names share it. */
 export const SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
@@ -29,10 +33,7 @@ export const sha256HexSchema = z.string().regex(/^[0-9a-f]{64}$/);
  * prompts and as tool input sources alike.
  */
 export const variableDeclarationSchema = z.object({
-    name: z
-        .string()
-        .regex(/^[A-Za-z_$][A-Za-z0-9_$]*$/)
-        .max(64),
+    name: z.string().regex(IDENTIFIER_PATTERN).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. */
@@ -46,7 +47,7 @@ export const boundVariablesSchema = z.array(variableDeclarationSchema.shape.name
 /** 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),
+    name: z.string().regex(IDENTIFIER_PATTERN),
     readOnly: z.boolean(),
     /** A tool that parks for approval is never a sandbox binding, mentioned or not. */
     requiresApproval: z.boolean(),
@@ -106,14 +107,14 @@ export const suggestionsSchema = z.record(
         .max(SUGGESTION_LIMITS.perLocale),
 ) satisfies z.ZodType<Suggestions>;
 
+/** One string per locale, at most 500 characters each; author copy the widget shows as is. */
+export const localizedTextSchema = z.record(localeSchema, z.string().max(500));
+
+export const GREETING_MAX_LENGTH = 200;
 /**
  * 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;
-/** One string per locale, at most 500 characters each; author copy the widget shows as is. */
-export const localizedTextSchema = z.record(localeSchema, z.string().max(500));
-
 export const greetingSchema = z.record(
     localeSchema,
     z

package/src/contracts/runtime/signature.ts

@@ -1,3 +1,6 @@
+import { isRecord } from "../json";
+import { IDENTIFIER_PATTERN } from "./grammar";
+
 /*
  * The one rendering of a dynamic tool the model sees, whichever side
  * produced it: Control Center renders its registry tools at resolve time,
@@ -11,14 +14,8 @@
 /** Past this nesting an object prints as `object`: deeper detail costs more prompt than it earns. */
 const MAX_DEPTH = 3;
 
-const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function propertyName(name: string) {
-    return IDENTIFIER.test(name) ? name : JSON.stringify(name);
+    return IDENTIFIER_PATTERN.test(name) ? name : JSON.stringify(name);
 }
 
 function compactLine(value: string) {
@@ -248,7 +245,9 @@ export type ToolSignatureInput = {
 /** `/** summary *\/\nname(input: {...}): { fields }`. */
 export function renderToolSignature(tool: ToolSignatureInput) {
     const summary = [summarize(tool.description), ...(tool.notes ?? [])].filter(Boolean).join(" ");
-    const callee = IDENTIFIER.test(tool.name) ? tool.name : `tools[${JSON.stringify(tool.name)}]`;
+    const callee = IDENTIFIER_PATTERN.test(tool.name)
+        ? tool.name
+        : `tools[${JSON.stringify(tool.name)}]`;
     const returns =
         typeof tool.returns === "string" ? tool.returns : responseShape(tool.returns.schema);
     const input = inputType(tool.inputSchema, resolver(tool.inputSchema));

package/src/contracts/wire/index.ts

@@ -32,9 +32,11 @@ export const ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024;
 export const MAX_ATTACHMENTS_PER_MESSAGE = 5;
 
 export const ATTACHMENT_STATUSES = ["pending", "described", "failed", "skipped"] as const;
+export type AttachmentStatus = (typeof ATTACHMENT_STATUSES)[number];
 
 /** 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 type AttachmentOrigin = (typeof ATTACHMENT_ORIGINS)[number];
 
 export function checkAttachmentPolicy(contentType: string, sizeBytes: number) {
     if (!ATTACHMENT_MIME_TYPES.some((type) => type === contentType)) return "type";
@@ -42,10 +44,6 @@ export function checkAttachmentPolicy(contentType: string, sizeBytes: number) {
     return "ok";
 }
 
-export type AttachmentStatus = (typeof ATTACHMENT_STATUSES)[number];
-
-export type AttachmentOrigin = (typeof ATTACHMENT_ORIGINS)[number];
-
 export type AttachmentSummary = {
     id: string;
     filename: string;
@@ -190,7 +188,7 @@ export function toUiMessage<TPart>(message: CortexMessage<TPart>) {
  * parked client tool calls on a continuation request. The server owns the
  * transcript (a continuation sends `messages: []`), so the answered assistant
  * message itself never crosses the wire — the SDK's park-boundary snapshot
- * does not preserve its id, and round-tripping it duplicated the stored
+ * does not preserve its id, and round-tripping it would duplicate the stored
  * message.
  */
 export const CLIENT_TOOL_ANSWERS_KEY = "clientToolAnswers";
@@ -206,6 +204,15 @@ export type ClientToolAnswer = {
     state: "complete" | "error" | "approved" | "denied";
 };
 
+/**
+ * The id a parked tool call's decision is filed under: the one on its
+ * approval record, or `approval_<toolCallId>`, which is how the SDK names
+ * every approval it requests, for a part that carries no record.
+ */
+export function approvalIdOf(part: { id: string; approval?: { id: string } }) {
+    return part.approval?.id ?? `approval_${part.id}`;
+}
+
 /**
  * Response of `POST /chat/:threadId/tools/:toolCallId/initiate`. `embed:
  * false` means the pending call is not a CC client tool — the widget