glirastes 0.3.2 → 0.5.0

package/dist/cjs/contracts/chat-interactions.js

@@ -0,0 +1,439 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatInteractionsError = exports.CHAT_ENTITY_TYPE_PATTERN = exports.CHAT_INTERACTION_LIMITS = void 0;
+exports.isChatArgumentPath = isChatArgumentPath;
+exports.chatText = chatText;
+exports.parseChatInteractions = parseChatInteractions;
+exports.parseChatInteractionOverrides = parseChatInteractionOverrides;
+exports.mergeChatInteractions = mergeChatInteractions;
+/**
+ * Declarative chat interactions: `@` entities and `/` commands a target app
+ * offers in its chat. `glirastes tools refresh` derives them from the code
+ * (`chatInteractions` in the generated module), `.glirastes/chat-interactions.json`
+ * or app code override them, and React and `<glirastes-chat>` turn them into
+ * completion providers. Plain JSON, dependency-free and bounded: the same
+ * data travels from the generator through the chat handler to the browser.
+ */
+const chat_command_js_1 = require("./chat-command.js");
+exports.CHAT_INTERACTION_LIMITS = Object.freeze({
+    entities: 50,
+    commands: 300,
+    actionsPerEntity: 20,
+    args: 12,
+    options: 50,
+    keywords: 20,
+    labelLength: 200,
+    descriptionLength: 500,
+    promptLength: 2_000,
+});
+exports.CHAT_ENTITY_TYPE_PATTERN = /^[a-z][a-z0-9_-]{0,39}$/;
+const FIELD = /^[A-Za-z_][\w-]{0,63}$/;
+const ARG_SEGMENT = /^[A-Za-z_$][\w$-]{0,63}$/;
+const ICON = /^[a-z0-9][a-z0-9-]{0,39}$/;
+const FORBIDDEN_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
+class ChatInteractionsError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Invalid chat interactions: ${issues.slice(0, 5).join('; ')}`);
+        this.issues = issues;
+        this.name = 'ChatInteractionsError';
+    }
+}
+exports.ChatInteractionsError = ChatInteractionsError;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** True for a dotted argument path that can never reach an object prototype. */
+function isChatArgumentPath(name) {
+    if (typeof name !== 'string' || name.length > 200)
+        return false;
+    const segments = name.split('.');
+    return segments.length <= 4
+        && segments.every((segment) => ARG_SEGMENT.test(segment) && !FORBIDDEN_SEGMENTS.has(segment));
+}
+/** The text in `locale`, falling back to English, then German. */
+function chatText(text, locale = 'en') {
+    if (text === undefined)
+        return '';
+    if (typeof text === 'string')
+        return text;
+    return text[locale] ?? text.en ?? text.de ?? '';
+}
+function fail(issues, path, message) {
+    issues.push(`${path}: ${message}`);
+    return undefined;
+}
+function checkKeys(value, allowed, path, issues) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key))
+            issues.push(`${path}.${key}: unknown field`);
+    }
+}
+function boundedString(value, max, path, issues) {
+    if (typeof value !== 'string' || !value.trim() || value.length > max || /[\u0000-\u0008\u000B-\u001F]/.test(value)) {
+        return fail(issues, path, `a non-blank string of at most ${max} characters`);
+    }
+    return value;
+}
+function text(value, max, path, issues) {
+    if (typeof value === 'string')
+        return boundedString(value, max, path, issues);
+    if (!isRecord(value))
+        return fail(issues, path, 'a string or { de, en }');
+    checkKeys(value, ['de', 'en'], path, issues);
+    const result = {};
+    for (const language of ['de', 'en']) {
+        if (value[language] === undefined)
+            continue;
+        const entry = boundedString(value[language], max, `${path}.${language}`, issues);
+        if (entry !== undefined)
+            result[language] = entry;
+    }
+    if (result.de === undefined && result.en === undefined)
+        return fail(issues, path, 'needs de or en');
+    return result;
+}
+function pattern(value, regex, path, issues) {
+    return typeof value === 'string' && regex.test(value) ? value : fail(issues, path, `must match ${regex}`);
+}
+function list(value, max, path, issues, item) {
+    if (!Array.isArray(value) || value.length > max)
+        return fail(issues, path, `an array of at most ${max} entries`);
+    const result = [];
+    value.forEach((entry, index) => {
+        const parsed = item(entry, `${path}[${index}]`);
+        if (parsed !== undefined)
+            result.push(parsed);
+    });
+    return result;
+}
+function fixedArgs(value, path, issues) {
+    if ((0, chat_command_js_1.serializeChatCommandArgs)(value) === undefined)
+        return fail(issues, path, 'a JSON object of at most 2000 characters');
+    return value;
+}
+function arg(value, path, issues) {
+    if (!isRecord(value))
+        return fail(issues, path, 'an object');
+    checkKeys(value, ['name', 'label', 'required', 'entity', 'options'], path, issues);
+    if (!isChatArgumentPath(value.name))
+        return fail(issues, `${path}.name`, 'a dotted argument path');
+    const label = text(value.label, exports.CHAT_INTERACTION_LIMITS.labelLength, `${path}.label`, issues);
+    if (value.required !== undefined && typeof value.required !== 'boolean')
+        fail(issues, `${path}.required`, 'a boolean');
+    const entity = value.entity === undefined ? undefined : pattern(value.entity, exports.CHAT_ENTITY_TYPE_PATTERN, `${path}.entity`, issues);
+    const options = value.options === undefined
+        ? undefined
+        : list(value.options, exports.CHAT_INTERACTION_LIMITS.options, `${path}.options`, issues, (entry, entryPath) => boundedString(entry, 100, entryPath, issues));
+    if (label === undefined)
+        return undefined;
+    return {
+        name: value.name,
+        label,
+        ...(value.required === true ? { required: true } : {}),
+        ...(entity ? { entity } : {}),
+        ...(options ? { options } : {}),
+    };
+}
+function args(value, path, issues) {
+    const parsed = list(value, exports.CHAT_INTERACTION_LIMITS.args, path, issues, (entry, entryPath) => arg(entry, entryPath, issues));
+    if (parsed && new Set(parsed.map((entry) => entry.name)).size !== parsed.length) {
+        return fail(issues, path, 'argument names must be unique');
+    }
+    return parsed;
+}
+function toolRun(value, path, issues) {
+    if (!isRecord(value))
+        return fail(issues, path, 'an object');
+    checkKeys(value, ['kind', 'tool', 'args'], path, issues);
+    if (value.kind !== 'tool' && value.kind !== 'ui')
+        return fail(issues, `${path}.kind`, "'tool' or 'ui'");
+    const tool = pattern(value.tool, chat_command_js_1.CHAT_COMMAND_TOOL_PATTERN, `${path}.tool`, issues);
+    const fixed = value.args === undefined ? undefined : fixedArgs(value.args, `${path}.args`, issues);
+    if (tool === undefined)
+        return undefined;
+    return { kind: value.kind, tool, ...(fixed ? { args: fixed } : {}) };
+}
+function commandRun(value, path, issues) {
+    if (isRecord(value) && value.kind === 'prompt') {
+        checkKeys(value, ['kind', 'prompt'], path, issues);
+        const prompt = text(value.prompt, exports.CHAT_INTERACTION_LIMITS.promptLength, `${path}.prompt`, issues);
+        return prompt === undefined ? undefined : { kind: 'prompt', prompt };
+    }
+    return toolRun(value, path, issues);
+}
+const COMMAND_FIELDS = ['label', 'description', 'keywords', 'icon', 'args', 'run'];
+function commandFields(value, path, issues) {
+    const result = {};
+    if (value.label !== undefined)
+        result.label = text(value.label, exports.CHAT_INTERACTION_LIMITS.labelLength, `${path}.label`, issues);
+    if (value.description !== undefined) {
+        result.description = text(value.description, exports.CHAT_INTERACTION_LIMITS.descriptionLength, `${path}.description`, issues);
+    }
+    if (value.keywords !== undefined) {
+        result.keywords = list(value.keywords, exports.CHAT_INTERACTION_LIMITS.keywords, `${path}.keywords`, issues, (entry, entryPath) => boundedString(entry, 60, entryPath, issues));
+    }
+    if (value.icon !== undefined)
+        result.icon = pattern(value.icon, ICON, `${path}.icon`, issues);
+    if (value.args !== undefined)
+        result.args = args(value.args, `${path}.args`, issues);
+    if (value.run !== undefined)
+        result.run = commandRun(value.run, `${path}.run`, issues);
+    return result;
+}
+function command(value, path, issues) {
+    if (!isRecord(value))
+        return fail(issues, path, 'an object');
+    checkKeys(value, ['id', ...COMMAND_FIELDS], path, issues);
+    const id = pattern(value.id, chat_command_js_1.CHAT_COMMAND_ID_PATTERN, `${path}.id`, issues);
+    const fields = commandFields(value, path, issues);
+    if (value.label === undefined)
+        fail(issues, `${path}.label`, 'required');
+    if (value.run === undefined)
+        fail(issues, `${path}.run`, 'required');
+    if (id === undefined || fields.label === undefined || fields.run === undefined)
+        return undefined;
+    return { id, ...fields };
+}
+function search(value, path, issues) {
+    if (!isRecord(value))
+        return fail(issues, path, 'an object');
+    checkKeys(value, ['tool', 'path', 'queryParam', 'itemsPath', 'idField', 'labelField', 'descriptionField', 'limitParam'], path, issues);
+    const tool = pattern(value.tool, chat_command_js_1.CHAT_COMMAND_TOOL_PATTERN, `${path}.tool`, issues);
+    const route = typeof value.path === 'string' && value.path.startsWith('/') && !value.path.startsWith('//')
+        && value.path.length <= 512 && !/[?#\\:\s]/.test(value.path)
+        && !value.path.split('/').some((segment) => segment === '.' || segment === '..')
+        ? value.path
+        : fail(issues, `${path}.path`, 'an app-internal path without parameters');
+    const field = (key) => pattern(value[key], FIELD, `${path}.${key}`, issues);
+    const queryParam = field('queryParam');
+    const idField = field('idField');
+    const labelField = field('labelField');
+    const descriptionField = value.descriptionField === undefined ? undefined : field('descriptionField');
+    const limitParam = value.limitParam === undefined ? undefined : field('limitParam');
+    const itemsPath = list(value.itemsPath, 4, `${path}.itemsPath`, issues, (entry, entryPath) => pattern(entry, FIELD, entryPath, issues));
+    if (!tool || !route || !queryParam || !idField || !labelField || !itemsPath)
+        return undefined;
+    return {
+        tool, path: route, queryParam, itemsPath, idField, labelField,
+        ...(descriptionField ? { descriptionField } : {}),
+        ...(limitParam ? { limitParam } : {}),
+    };
+}
+const ACTION_FIELDS = ['label', 'entityArg', 'args', 'run'];
+function actionFields(value, path, issues) {
+    const result = {};
+    if (value.label !== undefined)
+        result.label = text(value.label, exports.CHAT_INTERACTION_LIMITS.labelLength, `${path}.label`, issues);
+    if (value.entityArg !== undefined) {
+        result.entityArg = isChatArgumentPath(value.entityArg)
+            ? value.entityArg
+            : fail(issues, `${path}.entityArg`, 'a dotted argument path');
+    }
+    if (value.args !== undefined)
+        result.args = args(value.args, `${path}.args`, issues);
+    if (value.run !== undefined)
+        result.run = toolRun(value.run, `${path}.run`, issues);
+    return result;
+}
+function action(value, path, issues) {
+    if (!isRecord(value))
+        return fail(issues, path, 'an object');
+    checkKeys(value, ['id', ...ACTION_FIELDS], path, issues);
+    const id = pattern(value.id, chat_command_js_1.CHAT_COMMAND_ID_PATTERN, `${path}.id`, issues);
+    const fields = actionFields(value, path, issues);
+    for (const key of ['label', 'entityArg', 'run']) {
+        if (value[key] === undefined)
+            fail(issues, `${path}.${key}`, 'required');
+    }
+    if (!id || fields.label === undefined || fields.entityArg === undefined || fields.run === undefined)
+        return undefined;
+    return { id, ...fields };
+}
+function uniqueBy(entries, key, path, issues) {
+    const seen = new Set();
+    for (const entry of entries) {
+        const value = key(entry);
+        if (seen.has(value))
+            issues.push(`${path}: duplicate ${value}`);
+        seen.add(value);
+    }
+}
+function entity(value, path, issues) {
+    if (!isRecord(value))
+        return fail(issues, path, 'an object');
+    checkKeys(value, ['type', 'label', 'icon', 'search', 'actions'], path, issues);
+    const type = pattern(value.type, exports.CHAT_ENTITY_TYPE_PATTERN, `${path}.type`, issues);
+    const label = text(value.label, exports.CHAT_INTERACTION_LIMITS.labelLength, `${path}.label`, issues);
+    const icon = value.icon === undefined ? undefined : pattern(value.icon, ICON, `${path}.icon`, issues);
+    const parsedSearch = value.search === undefined ? undefined : search(value.search, `${path}.search`, issues);
+    const actions = value.actions === undefined
+        ? undefined
+        : list(value.actions, exports.CHAT_INTERACTION_LIMITS.actionsPerEntity, `${path}.actions`, issues, (entry, entryPath) => action(entry, entryPath, issues));
+    if (actions)
+        uniqueBy(actions, (entry) => entry.id, `${path}.actions`, issues);
+    if (!type || label === undefined)
+        return undefined;
+    return {
+        type, label,
+        ...(icon ? { icon } : {}),
+        ...(parsedSearch ? { search: parsedSearch } : {}),
+        ...(actions ? { actions } : {}),
+    };
+}
+/** Validates interaction data strictly; throws `ChatInteractionsError` listing every issue. */
+function parseChatInteractions(value) {
+    const issues = [];
+    if (!isRecord(value))
+        throw new ChatInteractionsError(['$: an object']);
+    checkKeys(value, ['schemaVersion', 'entities', 'commands'], '$', issues);
+    if (value.schemaVersion !== 1)
+        issues.push('$.schemaVersion: must be 1');
+    const entities = list(value.entities, exports.CHAT_INTERACTION_LIMITS.entities, '$.entities', issues, (entry, path) => entity(entry, path, issues)) ?? [];
+    const commands = list(value.commands, exports.CHAT_INTERACTION_LIMITS.commands, '$.commands', issues, (entry, path) => command(entry, path, issues)) ?? [];
+    uniqueBy(entities, (entry) => entry.type, '$.entities', issues);
+    uniqueBy(commands, (entry) => entry.id, '$.commands', issues);
+    if (issues.length > 0)
+        throw new ChatInteractionsError(issues);
+    return { schemaVersion: 1, entities, commands };
+}
+function overrideMap(value, path, keyPattern, issues, entry) {
+    if (value === undefined)
+        return undefined;
+    if (!isRecord(value))
+        return fail(issues, path, 'an object');
+    const result = {};
+    for (const [key, patch] of Object.entries(value)) {
+        if (!keyPattern.test(key)) {
+            issues.push(`${path}.${key}: invalid key`);
+            continue;
+        }
+        if (!isRecord(patch)) {
+            issues.push(`${path}.${key}: an object`);
+            continue;
+        }
+        if (patch.hidden !== undefined && typeof patch.hidden !== 'boolean')
+            issues.push(`${path}.${key}.hidden: a boolean`);
+        result[key] = entry(patch, `${path}.${key}`);
+    }
+    return result;
+}
+/** Validates `.glirastes/chat-interactions.json`; throws `ChatInteractionsError`. */
+function parseChatInteractionOverrides(value) {
+    const issues = [];
+    if (!isRecord(value))
+        throw new ChatInteractionsError(['$: an object']);
+    checkKeys(value, ['schemaVersion', 'entities', 'commands'], '$', issues);
+    if (value.schemaVersion !== 1)
+        issues.push('$.schemaVersion: must be 1');
+    const commands = overrideMap(value.commands, '$.commands', chat_command_js_1.CHAT_COMMAND_ID_PATTERN, issues, (patch, path) => {
+        checkKeys(patch, ['hidden', ...COMMAND_FIELDS], path, issues);
+        return { ...(patch.hidden === true ? { hidden: true } : {}), ...commandFields(patch, path, issues) };
+    });
+    const entities = overrideMap(value.entities, '$.entities', exports.CHAT_ENTITY_TYPE_PATTERN, issues, (patch, path) => {
+        checkKeys(patch, ['hidden', 'label', 'icon', 'search', 'actions'], path, issues);
+        const result = patch.hidden === true ? { hidden: true } : {};
+        if (patch.label !== undefined)
+            result.label = text(patch.label, exports.CHAT_INTERACTION_LIMITS.labelLength, `${path}.label`, issues);
+        if (patch.icon !== undefined)
+            result.icon = pattern(patch.icon, ICON, `${path}.icon`, issues);
+        if (patch.search !== undefined)
+            result.search = search(patch.search, `${path}.search`, issues);
+        const actions = overrideMap(patch.actions, `${path}.actions`, chat_command_js_1.CHAT_COMMAND_ID_PATTERN, issues, (actionPatch, actionPath) => {
+            checkKeys(actionPatch, ['hidden', ...ACTION_FIELDS], actionPath, issues);
+            return { ...(actionPatch.hidden === true ? { hidden: true } : {}), ...actionFields(actionPatch, actionPath, issues) };
+        });
+        if (actions)
+            result.actions = actions;
+        return result;
+    });
+    if (issues.length > 0)
+        throw new ChatInteractionsError(issues);
+    return {
+        schemaVersion: 1,
+        ...(entities ? { entities } : {}),
+        ...(commands ? { commands } : {}),
+    };
+}
+function withoutHidden(patch) {
+    const { hidden: _hidden, ...rest } = patch;
+    return rest;
+}
+function hasFields(patch, required) {
+    return required.every((key) => patch[key] !== undefined);
+}
+/**
+ * Applies overrides to derived data: a patch replaces the fields it names,
+ * `hidden: true` removes the entry, and a complete entry under a new id or
+ * type is added (a command needs `label` and `run`, an action `label`,
+ * `entityArg` and `run`, an entity `label` and a `search` or an action). A
+ * patch under an id or type that is not derived and is no complete entry is
+ * a stale patch, typically for a tool a refresh no longer derives: it is
+ * ignored, with one console warning naming it, so the chat route still loads
+ * and the entry keeps nothing. The result is validated again.
+ */
+function mergeChatInteractions(base, overrides) {
+    if (!overrides)
+        return parseChatInteractions(base);
+    const ignored = [];
+    const commandPatches = overrides.commands ?? {};
+    const commands = base.commands
+        .filter((entry) => commandPatches[entry.id]?.hidden !== true)
+        .map((entry) => ({ ...entry, ...withoutHidden(commandPatches[entry.id] ?? {}) }));
+    const known = new Set(base.commands.map((entry) => entry.id));
+    for (const [id, patch] of Object.entries(commandPatches)) {
+        if (known.has(id) || patch.hidden === true)
+            continue;
+        if (hasFields(patch, ['label', 'run']))
+            commands.push({ id, ...withoutHidden(patch) });
+        else
+            ignored.push(`commands.${id}`);
+    }
+    const entityPatches = overrides.entities ?? {};
+    const mergeActions = (actions, patches, path, stale) => {
+        const merged = actions
+            .filter((entry) => patches[entry.id]?.hidden !== true)
+            .map((entry) => ({ ...entry, ...withoutHidden(patches[entry.id] ?? {}) }));
+        const ids = new Set(actions.map((entry) => entry.id));
+        for (const [id, patch] of Object.entries(patches)) {
+            if (ids.has(id) || patch.hidden === true)
+                continue;
+            if (hasFields(patch, ['label', 'entityArg', 'run']))
+                merged.push({ id, ...withoutHidden(patch) });
+            else
+                stale.push(`${path}.actions.${id}`);
+        }
+        return merged;
+    };
+    const entities = base.entities
+        .filter((entry) => entityPatches[entry.type]?.hidden !== true)
+        .map((entry) => {
+        const patch = entityPatches[entry.type];
+        if (!patch)
+            return entry;
+        const { actions: actionPatches, ...fields } = withoutHidden(patch);
+        const { actions: current, ...rest } = entry;
+        const actions = mergeActions(current ?? [], actionPatches ?? {}, `entities.${entry.type}`, ignored);
+        return { ...rest, ...fields, ...(actions.length > 0 ? { actions } : {}) };
+    });
+    const types = new Set(base.entities.map((entry) => entry.type));
+    for (const [type, patch] of Object.entries(entityPatches)) {
+        if (types.has(type) || patch.hidden === true)
+            continue;
+        const { actions: actionPatches, ...fields } = withoutHidden(patch);
+        const stale = [];
+        const actions = mergeActions([], actionPatches ?? {}, `entities.${type}`, stale);
+        if (hasFields(fields, ['label']) && (fields.search !== undefined || actions.length > 0)) {
+            entities.push({ type, ...fields, ...(actions.length > 0 ? { actions } : {}) });
+            ignored.push(...stale);
+        }
+        else {
+            ignored.push(`entities.${type}`);
+        }
+    }
+    if (ignored.length > 0) {
+        console.warn('[glirastes] .glirastes/chat-interactions.json: ignored patches for ids that are not derived '
+            + `(any more) and are no complete entries: ${ignored.join(', ')}. Remove them.`);
+    }
+    return parseChatInteractions({ schemaVersion: 1, entities, commands });
+}

package/dist/cjs/contracts/clarification.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Wire protocol between the built-in `ask_clarification` tool, the chat UI
+ * and the server-side resume. Dependency-free so both the React bundle and
+ * the server adapters can import it without pulling in Zod.
+ */
+export declare const CLARIFICATION_TOOL_NAME: "ask_clarification";
+export declare const CLARIFICATION_TARGETS: readonly ["person", "object", "time", "scope", "other"];
+export type ClarificationTarget = (typeof CLARIFICATION_TARGETS)[number];
+/**
+ * Option and answer limits shared by the server tool schema, the chat UI
+ * reader and the answer marker, so client and server validation cannot drift.
+ */
+export declare const CLARIFICATION_MAX_OPTIONS = 6;
+export declare const CLARIFICATION_MAX_QUESTION_LENGTH = 300;
+export declare const CLARIFICATION_MAX_LABEL_LENGTH = 120;
+export declare const CLARIFICATION_MAX_DESCRIPTION_LENGTH = 200;
+export declare const CLARIFICATION_MAX_ANSWER_LENGTH = 1000;
+/** Non-global on purpose: safe to share and to call `.test()` on repeatedly. */
+export declare const CLARIFICATION_OPTION_ID_PATTERN: RegExp;
+export interface ClarificationOption {
+    readonly id: string;
+    readonly label: string;
+    readonly description?: string;
+}
+export interface ClarificationRequest {
+    readonly question: string;
+    readonly target: ClarificationTarget;
+    readonly options: ReadonlyArray<ClarificationOption>;
+    readonly allowFreeText: boolean;
+}
+export interface ClarificationAnswerReference {
+    readonly toolCallId: string;
+    readonly optionId?: string;
+}
+export interface ParsedClarificationAnswer {
+    readonly reference: ClarificationAnswerReference;
+    /** The user's visible answer, marker removed and trimmed. */
+    readonly answer: string;
+}
+/**
+ * Text the chat UI sends to answer a clarification. The marker is invisible
+ * in rendered bubbles and survives mention serialization (it is not a
+ * `<!--context:...-->` block).
+ */
+export declare function formatClarificationAnswer(input: {
+    toolCallId: string;
+    answer: string;
+    optionId?: string;
+}): string;
+/** Parses the first clarification marker; anything malformed is ignored. */
+export declare function parseClarificationAnswer(text: string): ParsedClarificationAnswer | undefined;
+/** Removes every clarification marker for display or routing. */
+export declare function stripClarificationMarkers(text: string): string;

package/dist/cjs/contracts/clarification.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Wire protocol between the built-in `ask_clarification` tool, the chat UI
+ * and the server-side resume. Dependency-free so both the React bundle and
+ * the server adapters can import it without pulling in Zod.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLARIFICATION_OPTION_ID_PATTERN = exports.CLARIFICATION_MAX_ANSWER_LENGTH = exports.CLARIFICATION_MAX_DESCRIPTION_LENGTH = exports.CLARIFICATION_MAX_LABEL_LENGTH = exports.CLARIFICATION_MAX_QUESTION_LENGTH = exports.CLARIFICATION_MAX_OPTIONS = exports.CLARIFICATION_TARGETS = exports.CLARIFICATION_TOOL_NAME = void 0;
+exports.formatClarificationAnswer = formatClarificationAnswer;
+exports.parseClarificationAnswer = parseClarificationAnswer;
+exports.stripClarificationMarkers = stripClarificationMarkers;
+exports.CLARIFICATION_TOOL_NAME = 'ask_clarification';
+exports.CLARIFICATION_TARGETS = ['person', 'object', 'time', 'scope', 'other'];
+/**
+ * Option and answer limits shared by the server tool schema, the chat UI
+ * reader and the answer marker, so client and server validation cannot drift.
+ */
+exports.CLARIFICATION_MAX_OPTIONS = 6;
+exports.CLARIFICATION_MAX_QUESTION_LENGTH = 300;
+exports.CLARIFICATION_MAX_LABEL_LENGTH = 120;
+exports.CLARIFICATION_MAX_DESCRIPTION_LENGTH = 200;
+exports.CLARIFICATION_MAX_ANSWER_LENGTH = 1_000;
+/** Non-global on purpose: safe to share and to call `.test()` on repeatedly. */
+exports.CLARIFICATION_OPTION_ID_PATTERN = /^[A-Za-z0-9._:-]{1,64}$/;
+/**
+ * Provider tool call ids are passed through unchanged, so this covers the
+ * ones in use: `call_*` (OpenAI), `toolu_*` (Anthropic), `tooluse_*`
+ * (Bedrock), `chatcmpl-tool-*` and `functions.<name>:<index>` (Kimi K2).
+ * `<`, `>`, quotes, backslashes and whitespace stay out, so an id can never
+ * close the marker comment or the JSON payload.
+ */
+const TOOL_CALL_ID = /^[A-Za-z0-9._:-]{1,200}$/;
+const MARKER = /<!--glirastes:clarification (\{[^<>\n]{1,400}\})-->/;
+const MARKERS = /<!--glirastes:clarification \{[^<>\n]{0,400}\}-->[ \t]*\n?/g;
+/**
+ * Text the chat UI sends to answer a clarification. The marker is invisible
+ * in rendered bubbles and survives mention serialization (it is not a
+ * `<!--context:...-->` block).
+ */
+function formatClarificationAnswer(input) {
+    if (!TOOL_CALL_ID.test(input.toolCallId)) {
+        throw new Error('Invalid clarification tool call id');
+    }
+    if (input.optionId !== undefined && !exports.CLARIFICATION_OPTION_ID_PATTERN.test(input.optionId)) {
+        throw new Error('Invalid clarification option id');
+    }
+    const answer = input.answer.trim().slice(0, exports.CLARIFICATION_MAX_ANSWER_LENGTH);
+    if (!answer)
+        throw new Error('A clarification answer must not be empty');
+    const reference = input.optionId === undefined
+        ? { toolCallId: input.toolCallId }
+        : { toolCallId: input.toolCallId, optionId: input.optionId };
+    return `<!--glirastes:clarification ${JSON.stringify(reference)}-->\n${answer}`;
+}
+/** Parses the first clarification marker; anything malformed is ignored. */
+function parseClarificationAnswer(text) {
+    const match = MARKER.exec(text);
+    if (!match)
+        return undefined;
+    let record;
+    try {
+        // MARKER only captures a brace-delimited payload: this is an object or throws.
+        record = JSON.parse(match[1]);
+    }
+    catch {
+        return undefined;
+    }
+    if (Object.keys(record).some((key) => key !== 'toolCallId' && key !== 'optionId')) {
+        return undefined;
+    }
+    if (typeof record.toolCallId !== 'string' || !TOOL_CALL_ID.test(record.toolCallId)) {
+        return undefined;
+    }
+    if (record.optionId !== undefined
+        && (typeof record.optionId !== 'string' || !exports.CLARIFICATION_OPTION_ID_PATTERN.test(record.optionId))) {
+        return undefined;
+    }
+    const answer = stripClarificationMarkers(text).trim().slice(0, exports.CLARIFICATION_MAX_ANSWER_LENGTH);
+    if (!answer)
+        return undefined;
+    return {
+        reference: typeof record.optionId === 'string'
+            ? { toolCallId: record.toolCallId, optionId: record.optionId }
+            : { toolCallId: record.toolCallId },
+        answer,
+    };
+}
+/** Removes every clarification marker for display or routing. */
+function stripClarificationMarkers(text) {
+    return text.replace(MARKERS, '');
+}

package/dist/cjs/contracts/content-boundary.d.ts

@@ -0,0 +1,3 @@
+export declare function findForbiddenContentPath(value: unknown, path?: ReadonlyArray<string | number>): Array<string | number> | null;
+export declare function findSensitiveStringPath(value: unknown, path?: ReadonlyArray<string | number>): Array<string | number> | null;
+export declare function findForbiddenPlatformContentPath(value: unknown, path?: ReadonlyArray<string | number>): Array<string | number> | null;

package/dist/cjs/contracts/content-boundary.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findForbiddenContentPath = findForbiddenContentPath;
+exports.findSensitiveStringPath = findSensitiveStringPath;
+exports.findForbiddenPlatformContentPath = findForbiddenPlatformContentPath;
+const FORBIDDEN_CONTENT_KEYS = new Set([
+    'apikey',
+    'argument',
+    'arguments',
+    'authorization',
+    'content',
+    'cookie',
+    'cookies',
+    'credential',
+    'credentials',
+    'message',
+    'messages',
+    'password',
+    'prompt',
+    'result',
+    'secret',
+    'systemprompt',
+    'token',
+    'toolargument',
+    'toolarguments',
+    'toolresult',
+    'toolresults',
+]);
+function normalizeKey(key) {
+    return key.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+function isForbiddenContentKey(key) {
+    const normalized = normalizeKey(key);
+    return FORBIDDEN_CONTENT_KEYS.has(normalized)
+        || normalized.endsWith('apikey')
+        || normalized.endsWith('authorization')
+        || normalized.endsWith('cookie')
+        || normalized.endsWith('credential')
+        || normalized.endsWith('password')
+        || normalized.endsWith('secret')
+        || normalized.endsWith('token');
+}
+function findForbiddenContentPath(value, path = []) {
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index += 1) {
+            const match = findForbiddenContentPath(value[index], [...path, index]);
+            if (match)
+                return match;
+        }
+        return null;
+    }
+    if (value === null || typeof value !== 'object')
+        return null;
+    for (const [key, child] of Object.entries(value)) {
+        const nextPath = [...path, key];
+        if (isForbiddenContentKey(key))
+            return nextPath;
+        const match = findForbiddenContentPath(child, nextPath);
+        if (match)
+            return match;
+    }
+    return null;
+}
+const SENSITIVE_STRING_PATTERNS = [
+    /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/,
+    /\bBearer\s+[A-Za-z0-9._~+/-]{16,}={0,2}\b/i,
+    /\bsk-(?:or-v1-)?[A-Za-z0-9_-]{20,}\b/,
+];
+function findSensitiveStringPath(value, path = []) {
+    if (typeof value === 'string') {
+        return SENSITIVE_STRING_PATTERNS.some((pattern) => pattern.test(value))
+            ? [...path]
+            : null;
+    }
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index += 1) {
+            const match = findSensitiveStringPath(value[index], [...path, index]);
+            if (match)
+                return match;
+        }
+        return null;
+    }
+    if (value === null || typeof value !== 'object')
+        return null;
+    for (const [key, child] of Object.entries(value)) {
+        const match = findSensitiveStringPath(child, [...path, key]);
+        if (match)
+            return match;
+    }
+    return null;
+}
+function findForbiddenPlatformContentPath(value, path = []) {
+    return findForbiddenContentPath(value, path)
+        ?? findSensitiveStringPath(value, path);
+}