glirastes 0.4.0 → 0.5.0

package/dist/cjs/contracts/app-setup.d.ts

@@ -0,0 +1,346 @@
+import { z } from 'zod';
+export declare const AppSetupStatusSchema: z.ZodEnum<{
+    discovering: "discovering";
+    assessing: "assessing";
+    waiting_for_interview: "waiting_for_interview";
+    review: "review";
+    ready: "ready";
+    published: "published";
+    failed: "failed";
+}>;
+export declare const AppSetupAssessmentModeSchema: z.ZodEnum<{
+    autonomous: "autonomous";
+    interview: "interview";
+}>;
+export declare const AppSetupOperationGroupSchema: z.ZodEnum<{
+    delete: "delete";
+    ui: "ui";
+    read: "read";
+    create: "create";
+    update: "update";
+    needs_attention: "needs_attention";
+}>;
+/**
+ * Optional, content-free provenance a capability report carries per tool
+ * (P08b shared contract item 5): where each local policy value came from and
+ * how description and input schema were obtained ("von Hand / aus Code /
+ * Agent / Vorlage", "Zod / OpenAPI / Agent / nur Feldnamen"). A local report
+ * never claims a Platform origin. Absent fields mean "not reported".
+ */
+export declare const AppSetupToolProvenanceSchema: z.ZodObject<{
+    policyOrigin: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodEnum<{
+            "code-default": "code-default";
+            "local-policy": "local-policy";
+        }>>;
+        requiresApproval: z.ZodOptional<z.ZodEnum<{
+            "code-default": "code-default";
+            "local-policy": "local-policy";
+        }>>;
+        riskClass: z.ZodOptional<z.ZodEnum<{
+            "code-default": "code-default";
+            "local-policy": "local-policy";
+        }>>;
+        allowedRoles: z.ZodOptional<z.ZodEnum<{
+            "code-default": "code-default";
+            "local-policy": "local-policy";
+        }>>;
+        description: z.ZodOptional<z.ZodEnum<{
+            "code-default": "code-default";
+            "local-policy": "local-policy";
+        }>>;
+    }, z.core.$strict>>;
+    contractSource: z.ZodOptional<z.ZodEnum<{
+        native: "native";
+        "contract-module": "contract-module";
+        "legacy-ai-tool": "legacy-ai-tool";
+        resolution: "resolution";
+        openapi: "openapi";
+        derived: "derived";
+        "ui-bridge": "ui-bridge";
+    }>>;
+    descriptionSource: z.ZodOptional<z.ZodEnum<{
+        code: "code";
+        agent: "agent";
+        human: "human";
+        template: "template";
+    }>>;
+    schemaSource: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        agent: "agent";
+        openapi: "openapi";
+        zod: "zod";
+        "json-schema": "json-schema";
+        "field-names": "field-names";
+    }>>;
+}, z.core.$strict>;
+/** The Platform's strict caps on reported exclusions (P08b Task 9). */
+export declare const APP_SETUP_EXCLUSION_LIMITS: Readonly<{
+    maxEntries: 5000;
+    maxStableKeyLength: 512;
+}>;
+/** A route or page the code deliberately does not expose as a tool. */
+export declare const AppSetupExclusionSchema: z.ZodObject<{
+    stableKey: z.ZodString;
+    origin: z.ZodEnum<{
+        default: "default";
+        code: "code";
+        policy: "policy";
+    }>;
+}, z.core.$strict>;
+export declare const AppSetupToolCandidateSchema: z.ZodObject<{
+    toolId: z.ZodUUID;
+    sourceFingerprint: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    modelName: z.ZodOptional<z.ZodString>;
+    module: z.ZodOptional<z.ZodString>;
+    sharedWith: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    usageHints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    presentation: z.ZodOptional<z.ZodObject<{
+        locale: z.ZodString;
+        singular: z.ZodString;
+        plural: z.ZodString;
+        approval: z.ZodString;
+    }, z.core.$strict>>;
+    executionKind: z.ZodEnum<{
+        endpoint: "endpoint";
+        ui: "ui";
+    }>;
+    method: z.ZodOptional<z.ZodEnum<{
+        GET: "GET";
+        HEAD: "HEAD";
+        POST: "POST";
+        PATCH: "PATCH";
+        PUT: "PUT";
+        DELETE: "DELETE";
+    }>>;
+    path: z.ZodOptional<z.ZodString>;
+    authBindingRef: z.ZodOptional<z.ZodString>;
+    actionBindingRef: z.ZodOptional<z.ZodString>;
+    allowedRoles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    operationGroup: z.ZodEnum<{
+        delete: "delete";
+        ui: "ui";
+        read: "read";
+        create: "create";
+        update: "update";
+        needs_attention: "needs_attention";
+    }>;
+    riskClass: z.ZodEnum<{
+        unknown: "unknown";
+        external: "external";
+        "safe-read": "safe-read";
+        "read-sensitive": "read-sensitive";
+        write: "write";
+        delete: "delete";
+        financial: "financial";
+    }>;
+    enabled: z.ZodBoolean;
+    requiresApproval: z.ZodBoolean;
+    inputSchemaDigest: z.ZodString;
+    outputSchemaDigest: z.ZodString;
+    provenance: z.ZodOptional<z.ZodObject<{
+        policyOrigin: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodEnum<{
+                "code-default": "code-default";
+                "local-policy": "local-policy";
+            }>>;
+            requiresApproval: z.ZodOptional<z.ZodEnum<{
+                "code-default": "code-default";
+                "local-policy": "local-policy";
+            }>>;
+            riskClass: z.ZodOptional<z.ZodEnum<{
+                "code-default": "code-default";
+                "local-policy": "local-policy";
+            }>>;
+            allowedRoles: z.ZodOptional<z.ZodEnum<{
+                "code-default": "code-default";
+                "local-policy": "local-policy";
+            }>>;
+            description: z.ZodOptional<z.ZodEnum<{
+                "code-default": "code-default";
+                "local-policy": "local-policy";
+            }>>;
+        }, z.core.$strict>>;
+        contractSource: z.ZodOptional<z.ZodEnum<{
+            native: "native";
+            "contract-module": "contract-module";
+            "legacy-ai-tool": "legacy-ai-tool";
+            resolution: "resolution";
+            openapi: "openapi";
+            derived: "derived";
+            "ui-bridge": "ui-bridge";
+        }>>;
+        descriptionSource: z.ZodOptional<z.ZodEnum<{
+            code: "code";
+            agent: "agent";
+            human: "human";
+            template: "template";
+        }>>;
+        schemaSource: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            agent: "agent";
+            openapi: "openapi";
+            zod: "zod";
+            "json-schema": "json-schema";
+            "field-names": "field-names";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const AppSetupArtifactSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    artifactId: z.ZodUUID;
+    runId: z.ZodUUID;
+    appId: z.ZodUUID;
+    discoveryDigest: z.ZodString;
+    assessmentMode: z.ZodEnum<{
+        autonomous: "autonomous";
+        interview: "interview";
+    }>;
+    status: z.ZodEnum<{
+        review: "review";
+        ready: "ready";
+    }>;
+    tools: z.ZodArray<z.ZodObject<{
+        toolId: z.ZodUUID;
+        sourceFingerprint: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        modelName: z.ZodOptional<z.ZodString>;
+        module: z.ZodOptional<z.ZodString>;
+        sharedWith: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        usageHints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        presentation: z.ZodOptional<z.ZodObject<{
+            locale: z.ZodString;
+            singular: z.ZodString;
+            plural: z.ZodString;
+            approval: z.ZodString;
+        }, z.core.$strict>>;
+        executionKind: z.ZodEnum<{
+            endpoint: "endpoint";
+            ui: "ui";
+        }>;
+        method: z.ZodOptional<z.ZodEnum<{
+            GET: "GET";
+            HEAD: "HEAD";
+            POST: "POST";
+            PATCH: "PATCH";
+            PUT: "PUT";
+            DELETE: "DELETE";
+        }>>;
+        path: z.ZodOptional<z.ZodString>;
+        authBindingRef: z.ZodOptional<z.ZodString>;
+        actionBindingRef: z.ZodOptional<z.ZodString>;
+        allowedRoles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        operationGroup: z.ZodEnum<{
+            delete: "delete";
+            ui: "ui";
+            read: "read";
+            create: "create";
+            update: "update";
+            needs_attention: "needs_attention";
+        }>;
+        riskClass: z.ZodEnum<{
+            unknown: "unknown";
+            external: "external";
+            "safe-read": "safe-read";
+            "read-sensitive": "read-sensitive";
+            write: "write";
+            delete: "delete";
+            financial: "financial";
+        }>;
+        enabled: z.ZodBoolean;
+        requiresApproval: z.ZodBoolean;
+        inputSchemaDigest: z.ZodString;
+        outputSchemaDigest: z.ZodString;
+        provenance: z.ZodOptional<z.ZodObject<{
+            policyOrigin: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodOptional<z.ZodEnum<{
+                    "code-default": "code-default";
+                    "local-policy": "local-policy";
+                }>>;
+                requiresApproval: z.ZodOptional<z.ZodEnum<{
+                    "code-default": "code-default";
+                    "local-policy": "local-policy";
+                }>>;
+                riskClass: z.ZodOptional<z.ZodEnum<{
+                    "code-default": "code-default";
+                    "local-policy": "local-policy";
+                }>>;
+                allowedRoles: z.ZodOptional<z.ZodEnum<{
+                    "code-default": "code-default";
+                    "local-policy": "local-policy";
+                }>>;
+                description: z.ZodOptional<z.ZodEnum<{
+                    "code-default": "code-default";
+                    "local-policy": "local-policy";
+                }>>;
+            }, z.core.$strict>>;
+            contractSource: z.ZodOptional<z.ZodEnum<{
+                native: "native";
+                "contract-module": "contract-module";
+                "legacy-ai-tool": "legacy-ai-tool";
+                resolution: "resolution";
+                openapi: "openapi";
+                derived: "derived";
+                "ui-bridge": "ui-bridge";
+            }>>;
+            descriptionSource: z.ZodOptional<z.ZodEnum<{
+                code: "code";
+                agent: "agent";
+                human: "human";
+                template: "template";
+            }>>;
+            schemaSource: z.ZodOptional<z.ZodEnum<{
+                none: "none";
+                agent: "agent";
+                openapi: "openapi";
+                zod: "zod";
+                "json-schema": "json-schema";
+                "field-names": "field-names";
+            }>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    planner: z.ZodObject<{
+        plannerId: z.ZodUUID;
+        modelBindingRef: z.ZodString;
+        promptBindingRef: z.ZodString;
+        budgetProfileRef: z.ZodString;
+        toolIds: z.ZodArray<z.ZodUUID>;
+    }, z.core.$strict>;
+    prompts: z.ZodObject<{
+        bundleDigest: z.ZodString;
+        artifactRef: z.ZodString;
+        plannerDigest: z.ZodString;
+        appBehaviorDigest: z.ZodString;
+        responseStyleDigest: z.ZodString;
+        capabilityFragmentDigests: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>;
+    warnings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        subjectRef: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    exclusions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        stableKey: z.ZodString;
+        origin: z.ZodEnum<{
+            default: "default";
+            code: "code";
+            policy: "policy";
+        }>;
+    }, z.core.$strict>>>;
+    generatedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type AppSetupStatus = z.infer<typeof AppSetupStatusSchema>;
+export type AppSetupAssessmentMode = z.infer<typeof AppSetupAssessmentModeSchema>;
+export type AppSetupOperationGroup = z.infer<typeof AppSetupOperationGroupSchema>;
+export type AppSetupToolCandidate = z.infer<typeof AppSetupToolCandidateSchema>;
+export type AppSetupArtifact = z.infer<typeof AppSetupArtifactSchema>;
+export type AppSetupToolProvenance = z.infer<typeof AppSetupToolProvenanceSchema>;
+export type AppSetupExclusion = z.infer<typeof AppSetupExclusionSchema>;
+/**
+ * Strong gate used by CLI validate/setup and standalone consumers. The base
+ * schema keeps historical artifacts readable; any newly generated artifact
+ * must pass this complete semantic parity check before it can be used.
+ */
+export declare function assertAppSetupSemanticParity(value: unknown, servedToolNames: ReadonlyArray<string>): AppSetupArtifact;

package/dist/cjs/contracts/app-setup.js

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppSetupArtifactSchema = exports.AppSetupToolCandidateSchema = exports.AppSetupExclusionSchema = exports.APP_SETUP_EXCLUSION_LIMITS = exports.AppSetupToolProvenanceSchema = exports.AppSetupOperationGroupSchema = exports.AppSetupAssessmentModeSchema = exports.AppSetupStatusSchema = void 0;
+exports.assertAppSetupSemanticParity = assertAppSetupSemanticParity;
+const zod_1 = require("zod");
+const content_boundary_js_1 = require("./content-boundary.js");
+const revisions_js_1 = require("./revisions.js");
+const uuid = zod_1.z.uuid();
+const identifier = zod_1.z.string().trim().min(1).max(200);
+const digest = zod_1.z.string().regex(/^sha256:(?:[A-Za-z0-9_-]{43}|[A-Za-z0-9+/]{43}=)$/);
+const timestamp = zod_1.z.iso.datetime({ offset: true });
+exports.AppSetupStatusSchema = zod_1.z.enum([
+    'discovering',
+    'assessing',
+    'waiting_for_interview',
+    'review',
+    'ready',
+    'published',
+    'failed',
+]);
+exports.AppSetupAssessmentModeSchema = zod_1.z.enum([
+    'autonomous',
+    'interview',
+]);
+exports.AppSetupOperationGroupSchema = zod_1.z.enum([
+    'read',
+    'create',
+    'update',
+    'delete',
+    'ui',
+    'needs_attention',
+]);
+const LocalPolicyOriginSchema = zod_1.z.enum(['code-default', 'local-policy']);
+/**
+ * Optional, content-free provenance a capability report carries per tool
+ * (P08b shared contract item 5): where each local policy value came from and
+ * how description and input schema were obtained ("von Hand / aus Code /
+ * Agent / Vorlage", "Zod / OpenAPI / Agent / nur Feldnamen"). A local report
+ * never claims a Platform origin. Absent fields mean "not reported".
+ */
+exports.AppSetupToolProvenanceSchema = zod_1.z.object({
+    policyOrigin: zod_1.z.object({
+        enabled: LocalPolicyOriginSchema,
+        requiresApproval: LocalPolicyOriginSchema,
+        riskClass: LocalPolicyOriginSchema,
+        allowedRoles: LocalPolicyOriginSchema,
+        description: LocalPolicyOriginSchema,
+    }).partial().strict().optional(),
+    contractSource: zod_1.z.enum([
+        'native',
+        'contract-module',
+        'legacy-ai-tool',
+        'resolution',
+        'openapi',
+        'derived',
+        'ui-bridge',
+    ]).optional(),
+    descriptionSource: zod_1.z.enum(['human', 'code', 'agent', 'template']).optional(),
+    schemaSource: zod_1.z.enum(['zod', 'openapi', 'json-schema', 'agent', 'field-names', 'none'])
+        .optional(),
+}).strict();
+/** The Platform's strict caps on reported exclusions (P08b Task 9). */
+exports.APP_SETUP_EXCLUSION_LIMITS = Object.freeze({
+    maxEntries: 5_000,
+    maxStableKeyLength: 512,
+});
+/** A route or page the code deliberately does not expose as a tool. */
+exports.AppSetupExclusionSchema = zod_1.z.object({
+    stableKey: zod_1.z.string().trim().min(1).max(exports.APP_SETUP_EXCLUSION_LIMITS.maxStableKeyLength),
+    origin: zod_1.z.enum(['default', 'policy', 'code']),
+}).strict();
+exports.AppSetupToolCandidateSchema = zod_1.z.object({
+    toolId: uuid,
+    sourceFingerprint: digest,
+    name: identifier,
+    /**
+     * Short prose so a reviewer can judge an operation before overriding its
+     * risk class or approval requirement. Bounded because a description is
+     * never a place to carry source, schemas, or secrets.
+     */
+    description: zod_1.z.string().trim().min(1).max(1_000).optional(),
+    /** Deterministic provider-safe name exposed to the model. */
+    modelName: zod_1.z.string().regex(/^[A-Za-z0-9_-]+$/).max(200).optional(),
+    /** Primary intent module plus optional additional module memberships. */
+    module: identifier.optional(),
+    sharedWith: zod_1.z.array(identifier).max(50).optional(),
+    /** Short operational guidance; never prompts, source, or business data. */
+    usageHints: zod_1.z.array(zod_1.z.string().trim().min(1).max(500)).min(1).max(20)
+        .optional(),
+    /** Curated operator-facing labels, shared by CLI, runtime, and UI. */
+    presentation: revisions_js_1.ToolPresentationSchema.optional(),
+    executionKind: zod_1.z.enum(['endpoint', 'ui']),
+    /**
+     * Technical metadata that describes the operation without being prose, so
+     * the description can stay about purpose and a reviewer can still see the
+     * facts. Optional because a UI entry has no route and an endpoint has no
+     * action binding.
+     */
+    method: zod_1.z.enum(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE']).optional(),
+    path: zod_1.z.string().startsWith('/').max(2_048).optional(),
+    authBindingRef: identifier.optional(),
+    actionBindingRef: identifier.optional(),
+    /**
+     * Roles the assessment proposes may call this. Empty means undecided, not
+     * "everyone": the local endpoint remains the final authorization boundary
+     * either way.
+     */
+    allowedRoles: zod_1.z.array(identifier).max(50).optional(),
+    operationGroup: exports.AppSetupOperationGroupSchema,
+    riskClass: revisions_js_1.ToolRiskClassSchema,
+    enabled: zod_1.z.boolean(),
+    requiresApproval: zod_1.z.boolean(),
+    inputSchemaDigest: digest,
+    outputSchemaDigest: digest,
+    provenance: exports.AppSetupToolProvenanceSchema.optional(),
+}).strict();
+const AppSetupPlannerMetadataSchema = zod_1.z.object({
+    plannerId: uuid,
+    modelBindingRef: identifier,
+    promptBindingRef: identifier,
+    budgetProfileRef: identifier,
+    toolIds: zod_1.z.array(uuid),
+}).strict();
+const AppSetupPromptMetadataSchema = zod_1.z.object({
+    bundleDigest: digest,
+    artifactRef: zod_1.z.string().trim().min(1).max(2_048),
+    plannerDigest: digest,
+    appBehaviorDigest: digest,
+    responseStyleDigest: digest,
+    capabilityFragmentDigests: zod_1.z.record(identifier, digest).default({}),
+}).strict();
+const AppSetupWarningSchema = zod_1.z.object({
+    code: identifier,
+    subjectRef: identifier.optional(),
+}).strict();
+exports.AppSetupArtifactSchema = zod_1.z.object({
+    schemaVersion: zod_1.z.literal(1),
+    artifactId: uuid,
+    runId: uuid,
+    appId: uuid,
+    discoveryDigest: digest,
+    assessmentMode: exports.AppSetupAssessmentModeSchema,
+    status: zod_1.z.enum(['review', 'ready']),
+    tools: zod_1.z.array(exports.AppSetupToolCandidateSchema),
+    planner: AppSetupPlannerMetadataSchema,
+    prompts: AppSetupPromptMetadataSchema,
+    warnings: zod_1.z.array(AppSetupWarningSchema).default([]),
+    exclusions: zod_1.z.array(exports.AppSetupExclusionSchema)
+        .max(exports.APP_SETUP_EXCLUSION_LIMITS.maxEntries)
+        .optional(),
+    generatedAt: timestamp,
+}).strict().superRefine((artifact, context) => {
+    const toolIds = new Set(artifact.tools.map((tool) => tool.toolId));
+    for (const [index, toolId] of artifact.planner.toolIds.entries()) {
+        if (!toolIds.has(toolId)) {
+            context.addIssue({
+                code: 'custom',
+                message: 'Planner tool reference is not present in the setup artifact',
+                path: ['planner', 'toolIds', index],
+            });
+        }
+    }
+    const forbiddenPath = (0, content_boundary_js_1.findForbiddenPlatformContentPath)(artifact);
+    if (forbiddenPath) {
+        context.addIssue({
+            code: 'custom',
+            message: 'App setup artifact contains prohibited content',
+            path: forbiddenPath,
+        });
+    }
+});
+/**
+ * Strong gate used by CLI validate/setup and standalone consumers. The base
+ * schema keeps historical artifacts readable; any newly generated artifact
+ * must pass this complete semantic parity check before it can be used.
+ */
+function assertAppSetupSemanticParity(value, servedToolNames) {
+    const artifact = exports.AppSetupArtifactSchema.parse(value);
+    const served = new Set(servedToolNames);
+    const artifactNames = new Set(artifact.tools.map((tool) => tool.name));
+    if (served.size !== artifactNames.size
+        || [...served].some((name) => !artifactNames.has(name))) {
+        throw new Error('App setup semantic parity does not match the served registry');
+    }
+    const modelNames = new Map();
+    for (const tool of artifact.tools.filter((candidate) => candidate.enabled)) {
+        if (!tool.modelName
+            || !tool.module
+            || !tool.sharedWith
+            || !tool.usageHints
+            || !tool.presentation) {
+            throw new Error(`Tool ${tool.name} has incomplete curated semantics`);
+        }
+        const expectedModelName = tool.name.replace(/\./g, '_');
+        if (tool.modelName !== expectedModelName) {
+            throw new Error(`Tool ${tool.name} has a non-deterministic model-facing tool name`);
+        }
+        const owner = modelNames.get(tool.modelName);
+        if (owner && owner !== tool.name) {
+            throw new Error(`Tools ${owner} and ${tool.name} collide on model-facing tool name ${tool.modelName}`);
+        }
+        if (tool.sharedWith.includes(tool.module)) {
+            throw new Error(`Tool ${tool.name} repeats its primary module in sharedWith`);
+        }
+        modelNames.set(tool.modelName, tool.name);
+    }
+    return artifact;
+}

package/dist/cjs/contracts/chat-command.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Wire protocol of direct chat commands: a `/` command or an entity action
+ * the user runs without a model call. The chat UI sends it as the complete
+ * text of a user message; the chat handler runs the named tool through the
+ * normal tool path (authorization, confirmation, revocation, budget, audit).
+ * Dependency-free like `clarification.ts`, so the React bundle,
+ * `<glirastes-chat>` and the server adapters share it.
+ */
+/** Command and action ids: a letter or digit, then `[A-Za-z0-9._-]`, at most 200 characters. */
+export declare const CHAT_COMMAND_ID_PATTERN: RegExp;
+/** Catalog definition ids, e.g. `ui.navigate` or `tasks.update`. */
+export declare const CHAT_COMMAND_TOOL_PATTERN: RegExp;
+/** Serialized JSON of the arguments, after escaping. */
+export declare const CHAT_COMMAND_MAX_ARGS_LENGTH = 2000;
+export declare const CHAT_COMMAND_MAX_LABEL_LENGTH = 200;
+/**
+ * Longest message text read as a command. A formatted command is below 2,700
+ * characters (marker payload at most 2,434, framing about 30, label at most
+ * 200); the parser sees unauthenticated, unbounded user text before any
+ * guardrail runs, so anything longer is not parsed at all.
+ */
+export declare const CHAT_COMMAND_MAX_MESSAGE_LENGTH = 4096;
+/** Tool call ids of direct commands start with this prefix. */
+export declare const CHAT_COMMAND_TOOL_CALL_PREFIX = "glirastes-command-";
+export interface ChatCommandInvocation {
+    readonly commandId: string;
+    /** Catalog definition id of the tool to run. */
+    readonly tool: string;
+    readonly args: Readonly<Record<string, unknown>>;
+}
+export interface ParsedChatCommandMessage {
+    readonly invocation: ChatCommandInvocation;
+    /** The visible line after the marker, trimmed (may be empty). */
+    readonly label: string;
+}
+/**
+ * JSON of `args` with `<` and `>` escaped, so it can never close the marker
+ * comment, or `undefined` when it is not a plain object or too long.
+ */
+export declare function serializeChatCommandArgs(args: unknown): string | undefined;
+/**
+ * The user message that runs a command without a model call:
+ * `<!--glirastes:command {"commandId":…,"tool":…,"args":{…}}-->` and the
+ * visible label on the next line. Throws on an id, tool or argument set the
+ * server would refuse.
+ */
+export declare function formatChatCommandMessage(input: {
+    commandId: string;
+    tool: string;
+    args?: Readonly<Record<string, unknown>>;
+    label: string;
+}): string;
+/**
+ * Reads a message that consists of exactly one command marker (and its
+ * label line). Anything else, including a malformed or oversized payload or
+ * a message longer than `CHAT_COMMAND_MAX_MESSAGE_LENGTH`, is not a command.
+ */
+export declare function parseChatCommandMessage(text: string): ParsedChatCommandMessage | undefined;
+/** Removes every command marker, e.g. for display or for the model's copy of old messages. */
+export declare function stripChatCommandMarkers(text: string): string;
+/**
+ * A tool call id of a direct command: the prefix, then only characters every
+ * model provider accepts in a tool call id (later model turns replay it).
+ */
+export declare function isChatCommandToolCallId(toolCallId: unknown): toolCallId is string;