glirastes 0.3.2 → 0.5.0

package/dist/server/adapters/nextjs/types.d.ts

@@ -1,8 +1,10 @@
-import type { z } from 'zod';
-import type { ToolContext, ToolRegistry, EndpointMethod, UiActionTemplate, UiPattern, ModelTier, AuditEmitter, AiPipeline, FollowupsConfig, PipelineResult, PiiShield, TelemetrySink, PromptOverride } from '../../../types.js';
+import type { ToolContext, ToolRegistry, EndpointMethod, UiActionTemplate, UiPattern, ModelTier, AuditEmitter, AiPipeline, FollowupsConfig, PipelineResult, PiiShield, TelemetrySink, PromptOverride, SchemaLike } from '../../../types.js';
 import type { Lancer } from '../../lancer/index.js';
-import type { InternalApiCaller } from '../../core/index.js';
-export interface WithAiToolOptions<TInput extends z.ZodTypeAny = z.ZodTypeAny> {
+import type { ApprovalStore } from './approval-binding.js';
+import type { ClarificationConfig, InternalApiCaller, PlanningConfig } from '../../core/index.js';
+import type { Principal, SecurityRevocation } from '../../../contracts/index.js';
+import type { ManagedTurnBudgetSignal, RuntimeMetricsSink, RuntimePriceTable, ToolSearchSemanticsMap, TurnSnapshot } from '../../../runtime/index.js';
+export interface WithAiToolOptions<TInput extends SchemaLike = SchemaLike> {
     toolName: string;
     id?: string;
     module?: string;
@@ -22,6 +24,8 @@ export type AiToolRouteHandler = ((req: Request, context?: {
 };
 export type LoadTools = (context: ToolContext & {
     callEndpoint: InternalApiCaller;
+    /** Immutable signed revision set pinned before dynamic tools are loaded. */
+    turnSnapshot?: TurnSnapshot;
 }) => ToolRegistry | Promise<ToolRegistry>;
 export interface GuardrailResult {
     ok: boolean;
@@ -38,7 +42,31 @@ export interface IntentRoutingResult {
     metadata?: Record<string, unknown>;
 }
 export type IntentRouter = (latestUserText: string, allToolNames: string[]) => IntentRoutingResult | Promise<IntentRoutingResult>;
-export type StepLimitSource = 'explicit' | 'module' | 'safety';
+export type StepLimitSource = 'explicit' | 'module' | 'safety' | 'runtime-budget';
+export interface ResolveTurnSnapshotContext {
+    request: Request;
+    turnId: string;
+    principal: Principal;
+}
+export interface ManagedLocalRuntimeConfig {
+    /**
+     * Resolve identity exclusively from a verified server-side session.
+     * Returning undefined fails closed before model or tool processing.
+     */
+    resolvePrincipal: (request: Request) => Principal | undefined | Promise<Principal | undefined>;
+    /**
+     * Return the immutable snapshot pinned for this turn. Approval
+     * continuations must return the same snapshot for the same turnId.
+     */
+    resolveTurnSnapshot: (context: ResolveTurnSnapshotContext) => TurnSnapshot | Promise<TurnSnapshot>;
+    /** Load current signed security revocations before every tool call. */
+    loadRevocations?: (context: {
+        request: Request;
+        snapshot: TurnSnapshot;
+    }) => ReadonlyArray<SecurityRevocation> | Promise<ReadonlyArray<SecurityRevocation>>;
+    /** Receives content-free local budget state transitions. */
+    onBudgetSignal?: (signal: ManagedTurnBudgetSignal) => void | Promise<void>;
+}
 export interface StepUsage {
     inputTokens: number;
     outputTokens: number;
@@ -71,6 +99,24 @@ export interface AiChatHandlerConfig {
      * Alternative to loadTools — when both are provided, `tools` takes precedence.
      */
     tools?: ToolRegistry;
+    /**
+     * Managed-local runtime boundary. When configured, the handler verifies a
+     * server principal, pins one turn snapshot, and guards every tool locally.
+     */
+    managedRuntime?: ManagedLocalRuntimeConfig;
+    /**
+     * Enable local `find_tools` recovery. With managedRuntime (managed or
+     * standalone source) discovery is pinned to the turn snapshot and its
+     * authorization; without it the per-request registry is the deployed,
+     * app-authorized tool set. false preserves static scoping.
+     */
+    toolDiscovery?: boolean;
+    /**
+     * Search-only synonyms keyed by model-facing tool name (for example from
+     * generated tool semantics). They improve `find_tools` ranking and never
+     * make a tool eligible or reach the model.
+     */
+    toolSemantics?: ToolSearchSemanticsMap;
     /**
      * Dynamic tool loader. Used in legacy mode (without pipeline).
      * When `tools` is provided, loadTools is ignored.
@@ -88,6 +134,20 @@ export interface AiChatHandlerConfig {
      * Only used with pipeline mode.
      */
     followups?: FollowupsConfig;
+    /**
+     * Built-in structured clarification (`ask_clarification`). The model asks
+     * one targeted question inside its normal step (no extra planner call);
+     * the turn ends after the question, and the UI's answer resumes the
+     * original request. Omit to keep the tool unavailable.
+     */
+    clarification?: ClarificationConfig;
+    /**
+     * Built-in task list (`update_plan`). The model records a short plan only
+     * for requests with several distinct actions and updates its statuses as
+     * it works; the chat UI shows the latest call as a checklist. The turn
+     * continues after each call. Omit to keep the tool unavailable.
+     */
+    planning?: PlanningConfig;
     /**
      * Model or model-resolver. Optional when pipeline `ModelSelectorConfig`
      * entries include an `instance` field — the adapter falls back to
@@ -101,9 +161,14 @@ export interface AiChatHandlerConfig {
         routing?: IntentRoutingResult;
         pipelineResult?: PipelineResult;
         currentDate: Date;
+        /**
+         * Revision set pinned for this turn. It lets a consumer assemble the
+         * prompt against exactly the revisions the turn started with.
+         */
+        turnSnapshot?: TurnSnapshot;
     }) => string);
     locale?: string;
-    uiActionSchema?: z.ZodTypeAny;
+    uiActionSchema?: SchemaLike;
     maxOutputTokens?: number;
     temperature?: number;
     /**
@@ -132,7 +197,8 @@ export interface AiChatHandlerConfig {
      */
     maxConversationHistoryPairs?: number;
     /**
-     * @deprecated Use `pipeline` instead. Ignored when `pipeline` is set.
+     * The app's own input check. Runs before the pipeline or the intent router,
+     * also with `pipeline` set; a refusal answers 400 without any model call.
      */
     guardrails?: GuardrailHook;
     /**
@@ -174,12 +240,13 @@ export interface AiChatHandlerConfig {
      */
     onAudit?: AuditEmitter;
     /**
-     * Remote telemetry sink for forwarding audit events to Glirastes.
+     * Legacy remote telemetry sink (Lancer, `/v1/proctor/events`).
      *
-     * Pass `lancer.telemetry` to enable monitoring on the Glirastes dashboard
-     * — works with both Free and Pro API keys. When combined with `pipeline`,
-     * Pro-tier telemetry is handled by server-pro; this field additionally
-     * forwards adapter-level session events.
+     * Not available with `managedRuntime`: the Foundation control plane does
+     * not serve the Proctor endpoint and these audit payloads are not
+     * content-free, so `createAiChatHandler` refuses the combination. Use
+     * `metrics` there. Without `managedRuntime` the legacy behaviour is
+     * unchanged:
      *
      * ```typescript
      * const lancer = createLancer({ apiKey: process.env.GLIRASTES_API_KEY! });
@@ -187,6 +254,154 @@ export interface AiChatHandlerConfig {
      * ```
      */
     telemetry?: TelemetrySink;
+    /**
+     * Content-free turn metrics (TechnicalRuntimeEvent v2) for the Glirastes
+     * Platform, e.g. `metrics` from `createGlirastes(...).chatTurn()` in
+     * `glirastes/runtime`. One event per turn (tokens, cost with provenance,
+     * latency, outcome, tool ids); never prompts, messages, arguments, results
+     * or secrets. Recording is synchronous and cheap, delivery happens later
+     * off the turn, and a failing sink never blocks or fails a turn.
+     */
+    metrics?: RuntimeMetricsSink;
+    /**
+     * Prices for models whose provider reports no cost (`source:
+     * 'price-table'`). A provider-reported cost (OpenRouter `usage.cost`)
+     * always wins; without either a turn's cost stays unknown (`null`), never
+     * 0. A known cost also counts against the turn's `maxEstimatedCostUsd`.
+     */
+    modelPricing?: RuntimePriceTable;
+    /**
+     * Direct chat commands (`/` commands and entity actions of the chat UI,
+     * default `true`): a user message that is exactly one command marker runs
+     * its tool without a model call, through the same registry, guard,
+     * confirmation, audit, PII shield and metrics as a model turn. Routing,
+     * guardrails and the model are skipped. `false` sends such a message to
+     * the model like any other text.
+     */
+    directCommands?: boolean;
+    /**
+     * The caller endpoint tools of one chat request use. When absent, calls go
+     * to the origin of the chat request's URL and carry only its cookie
+     * (`createInternalApiCallerFromRequest`); `Host` and `x-forwarded-host` are
+     * not read unless `trustForwardedHeaders` is set. An API on its own origin,
+     * an app that cannot reach itself under its request URL, or one that
+     * authenticates by `Authorization` header, passes
+     * `(request) => createHttpEndpointCaller({ baseUrl, request })`.
+     */
+    endpointCaller?: (request: Request) => InternalApiCaller;
+    /**
+     * Let the default endpoint caller and `runtime.origin` take the origin from
+     * `x-forwarded-host` / `x-forwarded-proto` (their last value, which the
+     * proxy nearest to the app set). Default `false`.
+     *
+     * Set it only when every request reaches the app through a proxy that sets
+     * or appends these headers. Anyone who can reach the app directly can put
+     * any host there, including internal addresses, and endpoint tools then
+     * send the user's cookie to it. A fixed `endpointCaller` with
+     * `createHttpEndpointCaller({ baseUrl })` is safer. The cross-origin check
+     * does not depend on this option.
+     */
+    trustForwardedHeaders?: boolean;
+    /**
+     * Secret that binds every approval the handler asks for to the tool call it
+     * was asked for (HMAC-SHA-256 over tool call id, tool name, input, issue
+     * time, expiry and the principal's scope). The browser sends the whole chat history back with the user's
+     * answer, and the AI SDK runs the approved call from that history; without
+     * the binding, a forged or replayed history would run any tool with any
+     * input. At least 16 characters, the same on every instance that can serve
+     * the second request of an approval. Falls back to the
+     * `GLIRASTES_APPROVAL_SECRET` environment variable.
+     *
+     * Without a secret, a handler whose tools can ask for approval derives a
+     * random per-process secret outside production and logs one warning; with
+     * `NODE_ENV=production` it refuses requests with HTTP 500
+     * (`approval_secret_missing`) instead. Approvals issued before an upgrade,
+     * by another secret or by another process are refused, not run.
+     */
+    approvalSecret?: string;
+    /**
+     * How long an approval stays valid after the handler asked for it, in
+     * milliseconds. Default 15 minutes. The expiry is signed into the approval
+     * id; an answer after it, or after the issue time plus this handler's own
+     * `approvalMaxAgeMs` if that is earlier, is refused with `approval_expired`.
+     * Must be a whole number above 0 and at most 24 hours; anything else makes
+     * `createAiChatHandler` throw a `RangeError`.
+     */
+    approvalMaxAgeMs?: number;
+    /**
+     * Single-use store for approvals. `consume(approvalId, expiresAtMs,
+     * { scope })` must atomically record the id and return `false` when it was
+     * recorded before; it receives the canonical id of a verified approval and
+     * a quota scope. Single use is by id alone, across all scopes: an id
+     * consumed under one scope must be refused under every other. The scope
+     * only says whose quota the entry counts against: the managed principal's
+     * scope, else the `approvalScope` value (both also signed into the id),
+     * else a per-caller key `caller:<hmac>` derived from the request's
+     * `Authorization` header, or its `Cookie` header without one (HMAC-SHA-256
+     * under the approval secret; the raw credentials are never passed or kept),
+     * else `''` for a request without credentials. Entries may be dropped after
+     * `expiresAtMs`. A throw refuses the approval
+     * (`approval_store_unavailable`). Only approvals the AI SDK can run in this
+     * request are consumed.
+     *
+     * Default: a bounded store in this process's memory, shared by every
+     * handler of the process (20,000 live approvals, at most 200 of them per
+     * scope; when either is full, further approvals are refused, not run). An
+     * entry, and the count of its scope, exists only for a genuine approval
+     * that was consumed. It makes a single instance replay-safe.
+     * Several instances that share `GLIRASTES_APPROVAL_SECRET` need a shared
+     * store (e.g. Redis `SET key 1 NX PXAT expiresAtMs`): with the default, an
+     * approved history replayed to another instance runs there once more,
+     * within `approvalMaxAgeMs`.
+     */
+    approvalStore?: ApprovalStore;
+    /**
+     * Who an approval is for when the handler runs without a managed runtime
+     * (with one, the managed principal's tenant and subject are used), e.g.
+     * `(req) => session(req).userId`. The value is signed into every approval
+     * id, so an approval issued to one user does not verify for another, and
+     * it is the scope of the approval store's per-scope quota.
+     *
+     * Without it and without a managed runtime, approvals are not bound to a
+     * user, and the store's quota is kept per caller, keyed by a hash of the
+     * request's `Authorization` or `Cookie` header (requests without either
+     * share one quota). That key is not signed into the approval id, because a
+     * cookie may change between the approval request and its answer. Set this
+     * option when the app identifies users another way, or to also bind each
+     * approval to its user.
+     */
+    approvalScope?: (request: Request) => string | Promise<string>;
+    /**
+     * Origins, besides the request's own, whose pages may post to the handler
+     * from a browser, e.g. `['https://admin.example.com']`. The request's own
+     * origin is taken from `x-forwarded-host` / `x-forwarded-proto` (the first
+     * value of each) when a proxy sets them. A browser request from a listed
+     * origin passes also when the browser marks it `Sec-Fetch-Site:
+     * same-site` or `cross-site`; `Origin: null` is never accepted.
+     */
+    allowedOrigins?: ReadonlyArray<string>;
+    /**
+     * Browser cross-origin protection, on by default. A page on another site
+     * can make a browser post to the chat route with the user's cookie, so the
+     * handler refuses (403) a request with `Sec-Fetch-Site` other than
+     * `same-origin` / `none` unless its `Origin` is in `allowedOrigins`, or,
+     * without that header, with an `Origin` that is neither its own nor in
+     * `allowedOrigins`, and always `Origin: null`. Requests with neither header
+     * (server to server) pass.
+     *
+     * `false` turns this off, and only an app whose chat route does not
+     * authenticate by cookie may do so (a bearer token the page adds itself,
+     * which a cross-origin page does not have). With cookie authentication it
+     * re-opens cross-site request forgery: any page the user visits could send
+     * chat turns, and run tools, as the user. The JSON content type check stays.
+     */
+    crossOriginProtection?: boolean;
+    /**
+     * Largest request body in bytes. Default 1,000,000. A larger body is
+     * answered with 413 before it is parsed; the limit counts the bytes read,
+     * not only the declared `Content-Length`.
+     */
+    maxBodyBytes?: number;
     /**
      * Lancer client for runtime prompt and model overrides (Pro feature).
      *
@@ -231,12 +446,13 @@ export interface AiChatHandlerConfig {
 }
 export type { PromptOverride };
 export type { AiPipeline, FollowupsConfig, PipelineResult };
+export type { ClarificationConfig, PlanningConfig };
 export interface ExecuteToolOptions {
     toolName: string;
     input: unknown;
     tools: ToolRegistry;
     locale?: string;
-    uiActionSchema?: z.ZodTypeAny;
+    uiActionSchema?: SchemaLike;
 }
 export interface ExecuteToolResult {
     success: boolean;

package/dist/server/adapters/nextjs/with-ai-tool.d.ts

@@ -1,9 +1,9 @@
-import type { z } from 'zod';
+import type { SchemaLike } from '../../../types.js';
 import type { WithAiToolOptions, AiToolRouteHandler } from './types.js';
 /**
  * Wraps a Next.js App Router handler with AI tool metadata.
  * The handler works as before -- metadata is for the codegen scanner.
  */
-export declare function withAiTool<TInput extends z.ZodTypeAny>(options: WithAiToolOptions<TInput>, handler: (req: Request, context?: {
+export declare function withAiTool<TInput extends SchemaLike>(options: WithAiToolOptions<TInput>, handler: (req: Request, context?: {
     params: Promise<Record<string, string>>;
 }) => Response | Promise<Response>): AiToolRouteHandler;

package/dist/server/core/adaptive-fast-path.d.ts

@@ -0,0 +1,3 @@
+import type { AdaptiveFastPathInstance, FastPathConfig, FastPathStorage } from '../../types.js';
+export declare function createAdaptiveFastPath(config?: FastPathConfig, storage?: FastPathStorage): AdaptiveFastPathInstance;
+export declare function createInMemoryFastPathStorage(): FastPathStorage;

package/dist/server/core/adaptive-fast-path.js

@@ -0,0 +1,185 @@
+const DEFAULT_CONFIG = {
+    promotionThreshold: 3,
+    minConfidence: 0.85,
+    maxPatterns: 500,
+    patternTtlMs: 7 * 24 * 60 * 60 * 1_000,
+    enableLearning: true,
+    confidenceThreshold: 0.95,
+};
+function clonePattern(pattern) {
+    return { ...pattern };
+}
+class AdaptiveFastPath {
+    storage;
+    patterns = new Map();
+    config;
+    dirty = false;
+    constructor(config = {}, storage) {
+        this.storage = storage;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        for (const pattern of config.initialPatterns ?? []) {
+            this.patterns.set(pattern.pattern, clonePattern(pattern));
+        }
+    }
+    normalize(text) {
+        return text
+            .toLowerCase()
+            .trim()
+            .replace(/\s+/g, ' ')
+            .replace(/[.!?]+/g, (run, offset, all) => (offset + run.length === all.length ? '' : run));
+    }
+    match(input) {
+        const key = this.normalize(input);
+        const pattern = this.patterns.get(key);
+        if (!pattern?.promotedAt)
+            return null;
+        if (this.config.patternTtlMs > 0
+            && Date.now() - pattern.lastSeen > this.config.patternTtlMs) {
+            this.patterns.delete(key);
+            this.dirty = true;
+            return null;
+        }
+        pattern.lastSeen = Date.now();
+        pattern.hitCount += 1;
+        this.dirty = true;
+        return {
+            intent: pattern.intent,
+            confidence: this.config.confidenceThreshold,
+        };
+    }
+    learn(input, result) {
+        if (!this.config.enableLearning)
+            return;
+        if (result.intent === 'ambiguous')
+            return;
+        if (result.confidence < this.config.minConfidence)
+            return;
+        const key = this.normalize(input);
+        if (!key)
+            return;
+        const existing = this.patterns.get(key);
+        if (!existing) {
+            this.evictIfNeeded();
+            this.patterns.set(key, {
+                pattern: key,
+                intent: result.intent,
+                confidence: result.confidence,
+                hitCount: 1,
+                lastSeen: Date.now(),
+                ...(this.config.promotionThreshold <= 1
+                    ? { promotedAt: Date.now() }
+                    : {}),
+            });
+            this.dirty = true;
+            return;
+        }
+        if (existing.intent !== result.intent) {
+            existing.intent = result.intent;
+            existing.confidence = result.confidence;
+            existing.hitCount = 1;
+            existing.lastSeen = Date.now();
+            existing.promotedAt = this.config.promotionThreshold <= 1
+                ? Date.now()
+                : undefined;
+            this.dirty = true;
+            return;
+        }
+        existing.hitCount += 1;
+        existing.lastSeen = Date.now();
+        existing.confidence = (existing.confidence * (existing.hitCount - 1)
+            + result.confidence) / existing.hitCount;
+        if (existing.hitCount >= this.config.promotionThreshold
+            && !existing.promotedAt) {
+            existing.promotedAt = Date.now();
+        }
+        this.dirty = true;
+    }
+    evictIfNeeded() {
+        if (this.patterns.size < this.config.maxPatterns)
+            return;
+        const candidates = [...this.patterns.entries()].sort(([, left], [, right]) => {
+            if (Boolean(left.promotedAt) !== Boolean(right.promotedAt)) {
+                return left.promotedAt ? 1 : -1;
+            }
+            return left.lastSeen - right.lastSeen;
+        });
+        const oldest = candidates[0]?.[0];
+        if (oldest)
+            this.patterns.delete(oldest);
+    }
+    getPatterns() {
+        return [...this.patterns.values()].map(clonePattern);
+    }
+    getPromotedPatterns() {
+        return this.getPatterns().filter((pattern) => pattern.promotedAt);
+    }
+    importPatterns(patterns) {
+        for (const candidate of patterns) {
+            const key = this.normalize(candidate.pattern);
+            if (!key)
+                continue;
+            const existing = this.patterns.get(key);
+            if (!existing || candidate.hitCount > existing.hitCount) {
+                this.evictIfNeeded();
+                this.patterns.set(key, { ...candidate, pattern: key });
+            }
+        }
+        this.dirty = true;
+    }
+    getStats() {
+        const patterns = this.getPatterns();
+        return {
+            totalPatterns: patterns.length,
+            promotedPatterns: patterns.filter((pattern) => pattern.promotedAt).length,
+            avgHitCount: patterns.length > 0
+                ? patterns.reduce((total, pattern) => total + pattern.hitCount, 0)
+                    / patterns.length
+                : 0,
+            oldestPattern: patterns.length > 0
+                ? Math.min(...patterns.map((pattern) => pattern.lastSeen))
+                : Date.now(),
+        };
+    }
+    clear() {
+        this.patterns.clear();
+        this.dirty = true;
+    }
+    async loadFromStorage() {
+        if (!this.storage)
+            return;
+        try {
+            const patterns = await this.storage.load();
+            this.importPatterns(patterns);
+            this.dirty = false;
+        }
+        catch {
+            // Storage is an optional local optimization.
+        }
+    }
+    async saveToStorage() {
+        if (!this.storage || !this.dirty)
+            return;
+        try {
+            await this.storage.save(this.getPatterns());
+            this.dirty = false;
+        }
+        catch {
+            // Storage is an optional local optimization.
+        }
+    }
+}
+export function createAdaptiveFastPath(config, storage) {
+    return new AdaptiveFastPath(config, storage);
+}
+export function createInMemoryFastPathStorage() {
+    let patterns = [];
+    return {
+        async load() {
+            return patterns.map(clonePattern);
+        },
+        async save(nextPatterns) {
+            patterns = nextPatterns.map(clonePattern);
+        },
+    };
+}
+//# sourceMappingURL=adaptive-fast-path.js.map

package/dist/server/core/adaptive-fast-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adaptive-fast-path.js","sourceRoot":"","sources":["../../../src/server/core/adaptive-fast-path.ts"],"names":[],"mappings":"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"}

package/dist/server/core/clarification-tool.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { type Tool } from '../../types.js';
+export interface ClarificationConfig {
+    /** Default true when the object is provided. */
+    enabled?: boolean;
+    /** Replaces the model-facing description, e.g. for a German-only prompt. */
+    description?: string;
+}
+export declare const ClarificationInputSchema: z.ZodObject<{
+    question: z.ZodString;
+    target: z.ZodEnum<{
+        object: "object";
+        person: "person";
+        time: "time";
+        other: "other";
+        scope: "scope";
+    }>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    allowFreeText: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * Built-in, side-effect-free clarification tool. It never calls the app; the
+ * chat UI renders the request and resumes the original task with the answer.
+ */
+export declare function createClarificationTool(config?: ClarificationConfig): Tool | null;

package/dist/server/core/clarification-tool.js

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { defineTool } from '../../types.js';
+import { CLARIFICATION_MAX_DESCRIPTION_LENGTH, CLARIFICATION_MAX_LABEL_LENGTH, CLARIFICATION_MAX_OPTIONS, CLARIFICATION_MAX_QUESTION_LENGTH, CLARIFICATION_OPTION_ID_PATTERN, CLARIFICATION_TARGETS, CLARIFICATION_TOOL_NAME, } from '../../contracts/clarification.js';
+const DEFAULT_DESCRIPTION = [
+    'Ask the user exactly one targeted question when the request lacks a required',
+    'target person, object, time or scope that cannot be derived from the',
+    `conversation, mentions or app context. Offer up to ${CLARIFICATION_MAX_OPTIONS} concrete options when`,
+    'you know them. Never ask when the intent is clear: act instead. After calling',
+    'this tool, end your turn and wait for the answer.',
+].join(' ');
+const OptionSchema = z.object({
+    id: z.string().regex(CLARIFICATION_OPTION_ID_PATTERN),
+    label: z.string().trim().min(1).max(CLARIFICATION_MAX_LABEL_LENGTH),
+    description: z.string().trim().min(1).max(CLARIFICATION_MAX_DESCRIPTION_LENGTH).optional(),
+});
+export const ClarificationInputSchema = z.object({
+    question: z.string().trim().min(1).max(CLARIFICATION_MAX_QUESTION_LENGTH),
+    target: z.enum(CLARIFICATION_TARGETS),
+    options: z.array(OptionSchema).max(CLARIFICATION_MAX_OPTIONS).optional(),
+    allowFreeText: z.boolean().optional(),
+}).superRefine((input, context) => {
+    const ids = (input.options ?? []).map((option) => option.id);
+    if (new Set(ids).size !== ids.length) {
+        context.addIssue({ code: 'custom', message: 'Option ids must be unique', path: ['options'] });
+    }
+    if (ids.length === 0 && input.allowFreeText === false) {
+        context.addIssue({
+            code: 'custom',
+            message: 'Provide options or allow a free-text answer',
+            path: ['allowFreeText'],
+        });
+    }
+});
+/**
+ * Built-in, side-effect-free clarification tool. It never calls the app; the
+ * chat UI renders the request and resumes the original task with the answer.
+ */
+export function createClarificationTool(config) {
+    if (config?.enabled === false)
+        return null;
+    return defineTool({
+        id: CLARIFICATION_TOOL_NAME,
+        description: config?.description ?? DEFAULT_DESCRIPTION,
+        inputSchema: ClarificationInputSchema,
+        needsApproval: false,
+        execute: async (input) => {
+            const clarification = {
+                question: input.question,
+                target: input.target,
+                options: input.options ?? [],
+                allowFreeText: input.allowFreeText ?? true,
+            };
+            return {
+                success: true,
+                clarification,
+                _instruction: 'The question is shown to the user. End this turn now and wait for the answer.',
+            };
+        },
+    });
+}
+//# sourceMappingURL=clarification-tool.js.map

package/dist/server/core/clarification-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clarification-tool.js","sourceRoot":"","sources":["../../../src/server/core/clarification-tool.ts"],"names":[],"mappings":"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"}

package/dist/server/core/generated-ui-tool.d.ts

@@ -0,0 +1,31 @@
+import { type SchemaLike, type Tool } from '../../types.js';
+/** What a generated UI tool asks the browser to do. */
+export type GeneratedUiAction = {
+    kind: 'navigate';
+} | {
+    kind: 'filter';
+    /** Route spelling of the filtered page, e.g. `/tasks` or `/projects/:id/tasks`. */
+    destination: string;
+    keys: ReadonlyArray<{
+        key: string;
+        array?: 'comma' | 'repeat';
+    }>;
+} | {
+    kind: 'client-action';
+    actionId: string;
+};
+export interface GeneratedUiToolDefinition {
+    id: string;
+    toolName: string;
+    description: string;
+    inputSchema: SchemaLike;
+    outputSchema?: SchemaLike;
+    needsApproval: boolean;
+    action: GeneratedUiAction;
+}
+/**
+ * Runtime of the tools that `glirastes tools refresh` generates from pages,
+ * URL filters and client actions. They never call a server: the result
+ * carries a `glirastes.*` uiAction that the chat hands to the app's bridge.
+ */
+export declare function uiActionToolToTool(definition: GeneratedUiToolDefinition): Tool;