glirastes 0.3.2 → 0.5.0

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

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAdaptiveFastPath = createAdaptiveFastPath;
+exports.createInMemoryFastPathStorage = createInMemoryFastPathStorage;
+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.
+        }
+    }
+}
+function createAdaptiveFastPath(config, storage) {
+    return new AdaptiveFastPath(config, storage);
+}
+function createInMemoryFastPathStorage() {
+    let patterns = [];
+    return {
+        async load() {
+            return patterns.map(clonePattern);
+        },
+        async save(nextPatterns) {
+            patterns = nextPatterns.map(clonePattern);
+        },
+    };
+}

package/dist/cjs/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";
+        scope: "scope";
+        other: "other";
+    }>;
+    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/cjs/server/core/clarification-tool.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClarificationInputSchema = void 0;
+exports.createClarificationTool = createClarificationTool;
+const zod_1 = require("zod");
+const types_js_1 = require("../../types.js");
+const clarification_js_1 = require("../../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_js_1.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 = zod_1.z.object({
+    id: zod_1.z.string().regex(clarification_js_1.CLARIFICATION_OPTION_ID_PATTERN),
+    label: zod_1.z.string().trim().min(1).max(clarification_js_1.CLARIFICATION_MAX_LABEL_LENGTH),
+    description: zod_1.z.string().trim().min(1).max(clarification_js_1.CLARIFICATION_MAX_DESCRIPTION_LENGTH).optional(),
+});
+exports.ClarificationInputSchema = zod_1.z.object({
+    question: zod_1.z.string().trim().min(1).max(clarification_js_1.CLARIFICATION_MAX_QUESTION_LENGTH),
+    target: zod_1.z.enum(clarification_js_1.CLARIFICATION_TARGETS),
+    options: zod_1.z.array(OptionSchema).max(clarification_js_1.CLARIFICATION_MAX_OPTIONS).optional(),
+    allowFreeText: zod_1.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.
+ */
+function createClarificationTool(config) {
+    if (config?.enabled === false)
+        return null;
+    return (0, types_js_1.defineTool)({
+        id: clarification_js_1.CLARIFICATION_TOOL_NAME,
+        description: config?.description ?? DEFAULT_DESCRIPTION,
+        inputSchema: exports.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.',
+            };
+        },
+    });
+}

package/dist/cjs/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;

package/dist/cjs/server/core/generated-ui-tool.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uiActionToolToTool = uiActionToolToTool;
+const navigation_js_1 = require("../../browser/navigation.js");
+const types_js_1 = require("../../types.js");
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function stringParams(value) {
+    if (!isRecord(value))
+        return undefined;
+    return Object.fromEntries(Object.entries(value)
+        .filter((entry) => typeof entry[1] === 'string'));
+}
+/**
+ * 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.
+ */
+function uiActionToolToTool(definition) {
+    return (0, types_js_1.defineTool)({
+        id: definition.id,
+        description: definition.description,
+        inputSchema: definition.inputSchema,
+        ...(definition.outputSchema ? { outputSchema: definition.outputSchema } : {}),
+        needsApproval: definition.needsApproval,
+        execute: async (rawInput, context) => {
+            const input = isRecord(rawInput) ? rawInput : {};
+            const action = definition.action;
+            if (action.kind === 'client-action') {
+                const available = context?.runtime?.clientActions;
+                if (available && !available.includes(action.actionId)) {
+                    return {
+                        success: false,
+                        error: 'This action is not available on the page the user has open. Do not claim it happened; navigate to a page that offers it, or use another tool.',
+                        retryable: false,
+                    };
+                }
+                return {
+                    success: true,
+                    message: 'Action executed.',
+                    uiAction: { type: 'glirastes.action', actionId: action.actionId, payload: { ...input } },
+                };
+            }
+            const params = stringParams(input.params);
+            try {
+                if (action.kind === 'navigate') {
+                    const destination = typeof input.destination === 'string' ? input.destination : '';
+                    const href = (0, navigation_js_1.buildNavigationHref)({ destination, ...(params ? { params } : {}) });
+                    return {
+                        success: true,
+                        message: 'Action executed.',
+                        uiAction: {
+                            type: 'glirastes.navigate',
+                            actionId: navigation_js_1.GLIRASTES_NAVIGATE_ACTION_ID,
+                            payload: { href, destination, ...(params ? { params } : {}) },
+                        },
+                    };
+                }
+                const query = {};
+                const arrayFormats = {};
+                for (const { key, array } of action.keys) {
+                    if (input[key] !== undefined)
+                        query[key] = input[key];
+                    if (array)
+                        arrayFormats[key] = array;
+                }
+                const href = (0, navigation_js_1.buildNavigationHref)({
+                    destination: action.destination,
+                    ...(params ? { params } : {}),
+                    query,
+                    arrayFormats,
+                });
+                return {
+                    success: true,
+                    message: 'Action executed.',
+                    uiAction: {
+                        type: 'glirastes.navigate',
+                        actionId: navigation_js_1.GLIRASTES_NAVIGATE_ACTION_ID,
+                        payload: { href, destination: action.destination, ...(params ? { params } : {}), query },
+                    },
+                };
+            }
+            catch (error) {
+                return { success: false, error: error instanceof Error ? error.message : 'Navigation failed' };
+            }
+        },
+    });
+}

package/dist/cjs/server/core/index.d.ts

@@ -1,5 +1,6 @@
-import type { AiEndpointToolDefinition, AiUiToolDefinition, EndpointMethod, Tool, ToolContext, ToolRegistry, UiPattern, AuditEmitter, TelemetrySink } from '../../types.js';
-import { z } from 'zod';
+import type { AiEndpointToolDefinition, AiUiToolDefinition, EndpointMethod, Tool, ToolContext, ToolRegistry, UiPattern, AuditEmitter, SchemaLike, TelemetrySink } from '../../types.js';
+export { createLocalGuardrails } from './local-guardrails.js';
+export { createAdaptiveFastPath, createInMemoryFastPathStorage, } from './adaptive-fast-path.js';
 export interface InternalApiRequest {
     method: EndpointMethod;
     path: string;
@@ -31,8 +32,38 @@ export interface ExpressInternalApiCallerOptions {
     defaultHeaders?: Record<string, string>;
     fetchImpl?: typeof fetch;
 }
+export interface HttpEndpointCallerOptions {
+    /**
+     * Origin of the API the tools call, e.g. `http://127.0.0.1:4000`. The app
+     * fixes it; it is never read from the chat request, so a `Host` or
+     * `X-Forwarded-Host` header cannot send a tool call elsewhere. Tool paths
+     * carry the full API path, so the URL has no path of its own.
+     */
+    baseUrl: string;
+    /** The chat request whose user credentials every call carries. */
+    request?: Request;
+    /** Headers of `request` forwarded to the API; `cookie` and `authorization` when absent. */
+    forwardHeaderNames?: ReadonlyArray<string>;
+    /**
+     * Extra headers of every call. A default never stands in for a forwarded
+     * header: one with a forwarded name is dropped, also when the user sent none.
+     */
+    defaultHeaders?: Record<string, string>;
+    fetchImpl?: typeof fetch;
+}
 export interface EndpointToolContext extends ToolContext {
     callEndpoint: InternalApiCaller;
+    /**
+     * The endpoint refused a call that passed the tool's input schema (400 or
+     * 422): the contract is wrong (spec 4.7, `tool_contract_rejected`). Called
+     * with the endpoint tool's `toolName` (a dotted definitionId or its
+     * model-facing encoding; the turn recorder resolves either); it must not
+     * throw.
+     */
+    onContractRejected?: (rejection: {
+        toolName: string;
+        status: 400 | 422;
+    }) => void;
 }
 /**
  * Truncate large tool results to prevent LLM context overflow.
@@ -58,12 +89,12 @@ export declare function buildUiActionFromPattern(pattern: UiPattern, input: Reco
  * @param result - Tool execution result (may contain uiAction)
  * @param uiActionSchema - Zod schema to validate against (from createUiActionSchema)
  */
-export declare function normalizeResultUiAction(result: unknown, uiActionSchema?: z.ZodTypeAny): unknown;
+export declare function normalizeResultUiAction(result: unknown, uiActionSchema?: SchemaLike): unknown;
 /**
  * Convert an endpoint tool definition into a Tool.
  * Uses callEndpoint from the ToolContext to execute HTTP requests.
  */
-export declare function endpointToolToTool<TInput extends z.ZodTypeAny>(endpointTool: AiEndpointToolDefinition<TInput>): Tool;
+export declare function endpointToolToTool<TInput extends SchemaLike>(endpointTool: AiEndpointToolDefinition<TInput>): Tool;
 /**
  * Convert an array of endpoint tools into a ToolRegistry.
  */
@@ -72,7 +103,7 @@ export declare function endpointToolsToRegistry(endpointTools: ReadonlyArray<AiE
  * Convert a UI tool definition into a Tool.
  * UI tools never call external services — they only produce uiActions.
  */
-export declare function uiToolToTool<TInput extends z.ZodTypeAny>(uiTool: AiUiToolDefinition<TInput>): Tool;
+export declare function uiToolToTool<TInput extends SchemaLike>(uiTool: AiUiToolDefinition<TInput>): Tool;
 /**
  * Convert an array of UI tools into a ToolRegistry.
  */
@@ -81,8 +112,8 @@ export declare function uiToolsToRegistry(uiTools: ReadonlyArray<AiUiToolDefinit
  * Options for converting tools to AI SDK tools.
  */
 export interface ToolToAiToolOptions {
-    /** Zod schema for validating uiActions at runtime */
-    uiActionSchema?: z.ZodTypeAny;
+    /** Host schema for validating uiActions at runtime */
+    uiActionSchema?: SchemaLike;
     /** Called when a tool execution fails */
     onError?: (toolId: string, error: unknown) => void;
     /**
@@ -117,7 +148,7 @@ export interface ToolToAiToolOptions {
 export declare function toolToAiTool(tool: Tool, context: ToolContext, toolName?: string, options?: ToolToAiToolOptions): {
     _toolId: string;
     description: string;
-    parameters: z.ZodType<any, z.ZodTypeDef, any>;
+    parameters: SchemaLike<unknown>;
     needsApproval: ((input: unknown) => Promise<boolean>) | undefined;
     execute: (input: unknown) => Promise<unknown>;
 };
@@ -131,8 +162,18 @@ export declare function normalizeNodeHeaders(headers: NodeIncomingHeaders, allow
 export declare function createFetchInternalApiCaller(options: FetchInternalApiCallerOptions): InternalApiCaller;
 export declare function createNextInternalApiCaller(options: NextInternalApiCallerOptions): InternalApiCaller;
 export declare function createExpressInternalApiCaller(options: ExpressInternalApiCallerOptions): InternalApiCaller;
+/**
+ * Endpoint caller for an API on its own origin (a NestJS or FastAPI backend
+ * next to the chat handler): every call goes to the fixed `baseUrl` and
+ * carries only the `cookie` and `authorization` headers the user sent with
+ * the chat request, so the API authorizes the user, never a substitute.
+ */
+export declare function createHttpEndpointCaller(options: HttpEndpointCallerOptions): InternalApiCaller;
 export { zodToCompactDescription } from './zod-compact.js';
+export { uiActionToolToTool, type GeneratedUiAction, type GeneratedUiToolDefinition, } from './generated-ui-tool.js';
 export { createFollowupTool } from './followup-tool.js';
+export { createClarificationTool, ClarificationInputSchema, type ClarificationConfig, } from './clarification-tool.js';
+export { createPlanTool, PlanInputSchema, type PlanningConfig, } from './plan-tool.js';
 export { defineModule, createAiRouter } from './module-router.js';
 export { createModelSelector, createModelSelectorFromMap } from './model-selector.js';
 export { createIntentClassifier, tokenize, jaccardSimilarity, classifyWithHeuristics, buildClassificationPrompt, parseJsonResponse, } from './intent-classifier.js';