glirastes 0.3.2 → 0.5.0

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

@@ -0,0 +1,87 @@
+import { buildNavigationHref, GLIRASTES_NAVIGATE_ACTION_ID, } from '../../browser/navigation.js';
+import { defineTool } from '../../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.
+ */
+export function uiActionToolToTool(definition) {
+    return 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 = buildNavigationHref({ destination, ...(params ? { params } : {}) });
+                    return {
+                        success: true,
+                        message: 'Action executed.',
+                        uiAction: {
+                            type: 'glirastes.navigate',
+                            actionId: 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 = buildNavigationHref({
+                    destination: action.destination,
+                    ...(params ? { params } : {}),
+                    query,
+                    arrayFormats,
+                });
+                return {
+                    success: true,
+                    message: 'Action executed.',
+                    uiAction: {
+                        type: 'glirastes.navigate',
+                        actionId: 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' };
+            }
+        },
+    });
+}
+//# sourceMappingURL=generated-ui-tool.js.map

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

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

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

package/dist/server/core/index.js

@@ -1,11 +1,25 @@
 import { defineTool } from '../../types.js';
 import { zodToCompactDescription } from './zod-compact.js';
+export { createLocalGuardrails } from './local-guardrails.js';
+export { createAdaptiveFastPath, createInMemoryFastPathStorage, } from './adaptive-fast-path.js';
 // ============================================================================
 // Helpers (internal)
 // ============================================================================
 function isRecord(value) {
     return typeof value === 'object' && value !== null;
 }
+const MAX_TOOL_ERROR_MESSAGE_CHARS = 1_000;
+function boundedToolFailure(result) {
+    const rawError = result.error;
+    const error = typeof rawError === 'string' && rawError.trim().length > 0
+        ? rawError.slice(0, MAX_TOOL_ERROR_MESSAGE_CHARS)
+        : 'Tool execution failed.';
+    return {
+        success: false,
+        error,
+        retryable: result.retryable === true,
+    };
+}
 /**
  * Default max characters for a serialized tool result (~4000 tokens).
  * Arrays exceeding this are truncated with a `_truncated` marker.
@@ -68,10 +82,37 @@ export function buildPath(pathTemplate, payload) {
         if (value === undefined || value === null || value === '') {
             throw new Error(`Missing required path parameter: "${paramName}" for ${pathTemplate}`);
         }
+        const text = String(value);
+        if (isDotSegment(text)) {
+            throw new Error(`Invalid path parameter "${paramName}" for ${pathTemplate}: "." and ".." segments are not allowed`);
+        }
         delete payload[paramName];
-        return encodeURIComponent(String(value));
+        return encodeURIComponent(text);
     });
 }
+/**
+ * `.` and `..` are path segments, not values: a URL parser (or the API's
+ * router) resolves them and the request lands on another route. A value is
+ * refused when, at any stage of percent-decoding it again and again, one of
+ * its segments (split at `/` and `\`) is `.` or `..`, because a proxy or
+ * framework in front of the API may decode once or several times, and some
+ * treat a backslash as a slash. Decoding is lenient (a malformed escape is
+ * left as it is, the valid ones around it are decoded) and stops at a fixed
+ * point; a value that has not reached one after a few rounds is refused.
+ */
+const MAX_DECODING_ROUNDS = 8;
+function isDotSegment(value) {
+    let current = value;
+    for (let round = 0; round <= MAX_DECODING_ROUNDS; round += 1) {
+        if (current.split(/[\\/]/).some((segment) => segment === '.' || segment === '..'))
+            return true;
+        const decoded = current.replace(/%([0-9a-fA-F]{2})/g, (_match, hex) => String.fromCharCode(parseInt(hex, 16)));
+        if (decoded === current)
+            return false;
+        current = decoded;
+    }
+    return true;
+}
 export function stripPathParams(pathTemplate, payload) {
     const pathParamNames = new Set();
     for (const match of pathTemplate.matchAll(/:([A-Za-z0-9_]+)/g)) {
@@ -298,6 +339,21 @@ export function normalizeResultUiAction(result, uiActionSchema) {
 // ============================================================================
 // Endpoint Tool Definition → Tool Conversion
 // ============================================================================
+/**
+ * `glirastes.*` UI actions belong to the generated UI tools (`ui.navigate`,
+ * `ui.filter.<view>`, `ui.<actionId>`), whose results the chat hands to the
+ * app's bridge without asking again. An endpoint result never carries one, so
+ * data an endpoint returns can neither navigate nor run a client action past
+ * that action's confirmation.
+ */
+function withoutReservedUiActions(uiAction) {
+    const reserved = (action) => (typeof action.type === 'string' && action.type.startsWith('glirastes.'));
+    if (Array.isArray(uiAction)) {
+        const kept = uiAction.filter((action) => !reserved(action));
+        return kept.length > 0 ? kept : undefined;
+    }
+    return uiAction && !reserved(uiAction) ? uiAction : undefined;
+}
 /**
  * Convert an endpoint tool definition into a Tool.
  * Uses callEndpoint from the ToolContext to execute HTTP requests.
@@ -314,7 +370,7 @@ export function endpointToolToTool(endpointTool) {
         outputSchema: endpointTool.outputSchema,
         method: endpointTool.method,
         needsApproval: endpointTool.needsApproval ??
-            (endpointTool.method === 'GET' ? false : true),
+            (endpointTool.method === 'GET' || endpointTool.method === 'HEAD' ? false : true),
         execute: async (rawInput, context) => {
             const endpointContext = context;
             if (!endpointContext.callEndpoint) {
@@ -323,10 +379,13 @@ export function endpointToolToTool(endpointTool) {
             const inputPayload = isRecord(rawInput) ? { ...rawInput } : {};
             const endpointPath = buildPath(endpointTool.path, inputPayload);
             const requestPayload = stripPathParams(endpointTool.path, inputPayload);
-            const requestPath = endpointTool.method === 'GET' || endpointTool.method === 'DELETE'
+            const queryOnly = endpointTool.method === 'GET'
+                || endpointTool.method === 'HEAD'
+                || endpointTool.method === 'DELETE';
+            const requestPath = queryOnly
                 ? `${endpointPath}${buildQueryString(requestPayload)}`
                 : endpointPath;
-            const requestBody = endpointTool.method === 'GET' || endpointTool.method === 'DELETE'
+            const requestBody = queryOnly
                 ? undefined
                 : Object.keys(requestPayload).length > 0
                     ? requestPayload
@@ -337,12 +396,21 @@ export function endpointToolToTool(endpointTool) {
                 body: requestBody,
             });
             if (!response.ok) {
+                if (response.status === 400 || response.status === 422) {
+                    try {
+                        endpointContext.onContractRejected?.({ toolName: endpointTool.toolName, status: response.status });
+                    }
+                    catch {
+                        // Metrics never change a tool result.
+                    }
+                }
                 return {
                     success: false,
                     error: response.error ?? `Endpoint failed (${response.status})`,
                 };
             }
-            const responseData = isRecord(response.data)
+            // A list or scalar answer has no fields of its own, so it travels under `data`.
+            const responseData = isRecord(response.data) && !Array.isArray(response.data)
                 ? response.data
                 : { data: response.data };
             // Priority: 1) Response uiAction, 2) uiPattern, 3) uiActionOnSuccess template
@@ -380,10 +448,13 @@ export function endpointToolToTool(endpointTool) {
                     uiAction = buildSuccessUiAction(endpointTool.uiActionOnSuccess, inputPayload, responseData);
                 }
             }
+            // The response's own uiAction field never reaches the chat unfiltered.
+            const { uiAction: _responseUiAction, ...responseFields } = responseData;
+            const resultUiAction = withoutReservedUiActions(uiAction);
             return {
                 success: true,
-                ...responseData,
-                ...(uiAction ? { uiAction } : {}),
+                ...responseFields,
+                ...(resultUiAction ? { uiAction: resultUiAction } : {}),
             };
         },
     });
@@ -547,15 +618,31 @@ export function toolToAiTool(tool, context, toolName, options) {
                 });
                 // Output schema: parse to strip extra fields, re-attach uiAction for client
                 let cleanResult = result;
-                if (tool.outputSchema &&
-                    isRecord(result) &&
-                    result.success !== false) {
-                    const parsed = tool.outputSchema.safeParse(result);
+                if (isRecord(result) && result.success === false) {
+                    cleanResult = boundedToolFailure(result);
+                }
+                else if (tool.outputSchema &&
+                    isRecord(result)) {
+                    const rec = result;
+                    let parsed = tool.outputSchema.safeParse(result);
+                    if (!parsed.success
+                        && rec.uiAction !== undefined) {
+                        const { uiAction: _transportUiAction, ...payloadWithoutUiAction } = rec;
+                        parsed = tool.outputSchema.safeParse(payloadWithoutUiAction);
+                    }
+                    if (!parsed.success && rec.success !== undefined) {
+                        const { success: _transportSuccess, uiAction: _transportUiAction, ...declaredPayload } = rec;
+                        parsed = tool.outputSchema.safeParse(declaredPayload);
+                    }
+                    const carriedUnderData = !parsed.success
+                        && rec.data !== undefined
+                        && (!isRecord(rec.data) || Array.isArray(rec.data));
+                    if (carriedUnderData)
+                        parsed = tool.outputSchema.safeParse(rec.data);
                     if (parsed.success) {
                         // Use parsed data (extra fields stripped by Zod)
-                        const rec = result;
                         cleanResult = {
-                            ...parsed.data,
+                            ...(carriedUnderData ? { data: parsed.data } : parsed.data),
                             // Preserve success flag
                             ...(rec.success !== undefined ? { success: rec.success } : {}),
                             // Re-attach uiAction for client stream (stripped by schema parse)
@@ -563,8 +650,17 @@ export function toolToAiTool(tool, context, toolName, options) {
                         };
                     }
                     else {
-                        // Schema mismatch — warn but pass through unmodified
-                        console.warn(`[glirastes] Output schema mismatch for tool "${name}":`, parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`));
+                        // Schema mismatch — retain bounded diagnostics locally, but never
+                        // expose an undeclared backend payload to the model.
+                        console.warn(`[glirastes] Output schema mismatch for tool "${name}":`, parsed.error.issues.map((i) => `${i.path?.join('.') ?? ''}: ${i.message ?? 'invalid value'}`));
+                        // The tool ran, and a write may already have happened: report it
+                        // as done, so the model neither claims a failure nor calls again.
+                        cleanResult = {
+                            success: true,
+                            outputWithheld: true,
+                            message: 'The tool ran, but its result did not match its declared output, so the details are withheld. Do not call it again for the same request.',
+                            ...(rec.uiAction ? { uiAction: rec.uiAction } : {}),
+                        };
                     }
                 }
                 // Truncate large arrays to prevent context overflow
@@ -671,6 +767,21 @@ function toErrorMessage(data, fallback) {
             return message;
         if (typeof data.error === 'string' && data.error.trim())
             return data.error;
+        // FastAPI: HTTPException returns { detail: string }, a validation error { detail: [{ loc, msg }] }.
+        const detail = data.detail;
+        if (typeof detail === 'string' && detail.trim())
+            return detail;
+        if (Array.isArray(detail)) {
+            const details = detail
+                .filter(isRecord)
+                .filter((item) => typeof item.msg === 'string' && item.msg.trim())
+                .map((item) => {
+                const location = Array.isArray(item.loc) ? item.loc.filter((part) => typeof part === 'string' || typeof part === 'number').join('.') : '';
+                return location ? `${location}: ${item.msg}` : item.msg;
+            });
+            if (details.length > 0)
+                return details.join('; ');
+        }
     }
     return fallback;
 }
@@ -710,7 +821,9 @@ export function createFetchInternalApiCaller(options) {
     const fetchImpl = options.fetchImpl ?? fetch;
     return async (request) => {
         const url = new URL(request.path, options.baseUrl).toString();
-        const methodAllowsBody = request.method !== 'GET' && request.method !== 'DELETE';
+        const methodAllowsBody = request.method !== 'GET'
+            && request.method !== 'HEAD'
+            && request.method !== 'DELETE';
         const headers = {
             ...(options.defaultHeaders ?? {}),
         };
@@ -764,15 +877,84 @@ export function createExpressInternalApiCaller(options) {
         },
     });
 }
+const HTTP_FORWARDED_HEADERS = ['cookie', 'authorization'];
+/**
+ * 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 function createHttpEndpointCaller(options) {
+    const base = new URL(options.baseUrl);
+    if (base.protocol !== 'http:' && base.protocol !== 'https:') {
+        throw new Error('createHttpEndpointCaller: baseUrl must be an http or https URL');
+    }
+    if (base.pathname !== '/' || base.search || base.hash || base.username || base.password) {
+        throw new Error('createHttpEndpointCaller: baseUrl is an origin; tool paths carry the full API path');
+    }
+    const names = new Set((options.forwardHeaderNames ?? HTTP_FORWARDED_HEADERS).map((name) => name.toLowerCase()));
+    const headers = {};
+    for (const [name, value] of Object.entries(options.defaultHeaders ?? {})) {
+        if (!names.has(name.toLowerCase()))
+            headers[name.toLowerCase()] = value;
+    }
+    for (const name of [...names].sort()) {
+        const value = options.request?.headers.get(name);
+        if (value)
+            headers[name] = value;
+    }
+    const call = createFetchInternalApiCaller({
+        baseUrl: base.origin,
+        ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+        defaultHeaders: headers,
+    });
+    return async (request) => {
+        if (!staysOnOrigin(request.path, base.origin)) {
+            return { ok: false, status: 400, error: 'Endpoint path must be relative to the API' };
+        }
+        return call(request);
+    };
+}
+/**
+ * A tool path is relative to the API. An absolute or protocol-relative one
+ * would leave it, and so would one that a URL parser rewrites: it drops tab,
+ * CR and LF anywhere and reads `\` as `/`, so `/<tab>/host` becomes `//host`.
+ * Control characters and `\` are therefore refused, and the resolved URL must
+ * still be on the API's origin.
+ */
+function staysOnOrigin(path, origin) {
+    if (!path.startsWith('/') || path.startsWith('//'))
+        return false;
+    for (const char of path) {
+        const code = char.codePointAt(0);
+        if (code <= 0x1f || code === 0x7f || char === '\\')
+            return false;
+    }
+    try {
+        return new URL(path, origin).origin === origin;
+    }
+    catch {
+        return false;
+    }
+}
 // ============================================================================
 // Re-exports
 // ============================================================================
 export { zodToCompactDescription } from './zod-compact.js';
+export { uiActionToolToTool, } from './generated-ui-tool.js';
 // ============================================================================
 // Followup Tool
 // ============================================================================
 export { createFollowupTool } from './followup-tool.js';
 // ============================================================================
+// Clarification Tool
+// ============================================================================
+export { createClarificationTool, ClarificationInputSchema, } from './clarification-tool.js';
+// ============================================================================
+// Plan Tool
+// ============================================================================
+export { createPlanTool, PlanInputSchema, } from './plan-tool.js';
+// ============================================================================
 // Module Routing
 // ============================================================================
 export { defineModule, createAiRouter } from './module-router.js';