glirastes 0.4.0 → 0.5.1

package/dist/cjs/server/core/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseJsonResponse = exports.buildClassificationPrompt = exports.classifyWithHeuristics = exports.jaccardSimilarity = exports.tokenize = exports.createIntentClassifier = exports.createModelSelectorFromMap = exports.createModelSelector = exports.createAiRouter = exports.defineModule = exports.createFollowupTool = exports.zodToCompactDescription = void 0;
+exports.parseJsonResponse = exports.buildClassificationPrompt = exports.classifyWithHeuristics = exports.jaccardSimilarity = exports.tokenize = exports.createIntentClassifier = exports.createModelSelectorFromMap = exports.createModelSelector = exports.createAiRouter = exports.defineModule = exports.PlanInputSchema = exports.createPlanTool = exports.ClarificationInputSchema = exports.createClarificationTool = exports.createFollowupTool = exports.uiActionToolToTool = exports.zodToCompactDescription = exports.createInMemoryFastPathStorage = exports.createAdaptiveFastPath = exports.createLocalGuardrails = void 0;
 exports.truncateToolResult = truncateToolResult;
 exports.buildPath = buildPath;
 exports.stripPathParams = stripPathParams;
@@ -18,14 +18,32 @@ exports.normalizeNodeHeaders = normalizeNodeHeaders;
 exports.createFetchInternalApiCaller = createFetchInternalApiCaller;
 exports.createNextInternalApiCaller = createNextInternalApiCaller;
 exports.createExpressInternalApiCaller = createExpressInternalApiCaller;
+exports.createHttpEndpointCaller = createHttpEndpointCaller;
 const types_js_1 = require("../../types.js");
 const zod_compact_js_1 = require("./zod-compact.js");
+var local_guardrails_js_1 = require("./local-guardrails.js");
+Object.defineProperty(exports, "createLocalGuardrails", { enumerable: true, get: function () { return local_guardrails_js_1.createLocalGuardrails; } });
+var adaptive_fast_path_js_1 = require("./adaptive-fast-path.js");
+Object.defineProperty(exports, "createAdaptiveFastPath", { enumerable: true, get: function () { return adaptive_fast_path_js_1.createAdaptiveFastPath; } });
+Object.defineProperty(exports, "createInMemoryFastPathStorage", { enumerable: true, get: function () { return adaptive_fast_path_js_1.createInMemoryFastPathStorage; } });
 // ============================================================================
 // 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.
@@ -88,10 +106,37 @@ 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;
+}
 function stripPathParams(pathTemplate, payload) {
     const pathParamNames = new Set();
     for (const match of pathTemplate.matchAll(/:([A-Za-z0-9_]+)/g)) {
@@ -318,6 +363,21 @@ 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.
@@ -334,7 +394,7 @@ 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) {
@@ -343,10 +403,13 @@ 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
@@ -357,12 +420,21 @@ 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
@@ -400,10 +472,13 @@ 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 } : {}),
             };
         },
     });
@@ -567,15 +642,31 @@ 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)
@@ -583,8 +674,17 @@ 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
@@ -691,6 +791,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;
 }
@@ -730,7 +845,9 @@ 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 ?? {}),
         };
@@ -784,17 +901,91 @@ 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.
+ */
+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
 // ============================================================================
 var zod_compact_js_2 = require("./zod-compact.js");
 Object.defineProperty(exports, "zodToCompactDescription", { enumerable: true, get: function () { return zod_compact_js_2.zodToCompactDescription; } });
+var generated_ui_tool_js_1 = require("./generated-ui-tool.js");
+Object.defineProperty(exports, "uiActionToolToTool", { enumerable: true, get: function () { return generated_ui_tool_js_1.uiActionToolToTool; } });
 // ============================================================================
 // Followup Tool
 // ============================================================================
 var followup_tool_js_1 = require("./followup-tool.js");
 Object.defineProperty(exports, "createFollowupTool", { enumerable: true, get: function () { return followup_tool_js_1.createFollowupTool; } });
 // ============================================================================
+// Clarification Tool
+// ============================================================================
+var clarification_tool_js_1 = require("./clarification-tool.js");
+Object.defineProperty(exports, "createClarificationTool", { enumerable: true, get: function () { return clarification_tool_js_1.createClarificationTool; } });
+Object.defineProperty(exports, "ClarificationInputSchema", { enumerable: true, get: function () { return clarification_tool_js_1.ClarificationInputSchema; } });
+// ============================================================================
+// Plan Tool
+// ============================================================================
+var plan_tool_js_1 = require("./plan-tool.js");
+Object.defineProperty(exports, "createPlanTool", { enumerable: true, get: function () { return plan_tool_js_1.createPlanTool; } });
+Object.defineProperty(exports, "PlanInputSchema", { enumerable: true, get: function () { return plan_tool_js_1.PlanInputSchema; } });
+// ============================================================================
 // Module Routing
 // ============================================================================
 var module_router_js_1 = require("./module-router.js");

package/dist/cjs/server/core/local-guardrails.d.ts

@@ -0,0 +1,6 @@
+import type { Guardrails, GuardrailsConfig } from '../../types.js';
+/**
+ * Deterministic, provider-independent input validation that runs entirely in
+ * the target application. It never sends content to the control plane.
+ */
+export declare function createLocalGuardrails(config?: GuardrailsConfig): Guardrails;

package/dist/cjs/server/core/local-guardrails.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLocalGuardrails = createLocalGuardrails;
+const DEFAULT_INJECTION_PATTERNS = [
+    /ignore\s+(all\s+)?previous\s+instructions/i,
+    /tell\s+me\s+your\s+(system\s+)?prompt/i,
+    /you\s+are\s+now\s+a\s+different/i,
+    /act\s+as\s+an?\s+(admin|root|system)/i,
+    /bypass\s+(security|auth)/i,
+];
+/**
+ * Deterministic, provider-independent input validation that runs entirely in
+ * the target application. It never sends content to the control plane.
+ */
+function createLocalGuardrails(config) {
+    const maxLength = config?.maxInputLength ?? 4_000;
+    const injectionEnabled = config?.enableInjectionDetection ?? true;
+    const patterns = [
+        ...DEFAULT_INJECTION_PATTERNS,
+        ...(config?.injectionPatterns ?? []),
+    ];
+    function validate(input) {
+        const trimmed = input.trim();
+        if (trimmed.length === 0) {
+            return {
+                valid: false,
+                blocked: true,
+                reason: 'empty_input',
+                sanitized: '',
+            };
+        }
+        if (trimmed.length > maxLength) {
+            return {
+                valid: false,
+                blocked: true,
+                reason: 'input_too_long',
+                sanitized: trimmed.slice(0, maxLength),
+            };
+        }
+        if (injectionEnabled) {
+            for (const pattern of patterns) {
+                pattern.lastIndex = 0;
+                if (pattern.test(trimmed)) {
+                    return {
+                        valid: true,
+                        blocked: false,
+                        reason: 'prompt_injection_signal',
+                        sanitized: trimmed,
+                    };
+                }
+            }
+        }
+        for (const validator of config?.customValidators ?? []) {
+            const result = validator.validate(trimmed);
+            if (!result.valid)
+                return result;
+        }
+        return {
+            valid: true,
+            blocked: false,
+            sanitized: trimmed,
+        };
+    }
+    return {
+        validate,
+        sanitize(input) {
+            return input.trim().slice(0, maxLength);
+        },
+    };
+}

package/dist/cjs/server/core/module-router.d.ts

@@ -6,9 +6,11 @@ export declare function defineModule(config: ModuleDefinition): ModuleDefinition
 /**
  * Create an AI router that selects tools based on classified intent.
  *
- * The router uses confidence-based expansion:
+ * Legacy routing uses confidence-based expansion:
  * - High confidence (>= 0.85): Only primary module's own tools
  * - Medium confidence (0.7-0.85): Primary module tools + shared tools from all modules
  * - Low confidence (< 0.7): All tools (ambiguous fallback)
+ * Focused routing instead leaves uncertain intents unselected for clarification
+ * or bounded discovery and expands only through explicit module relationships.
  */
 export declare function createAiRouter(config: AiRouterConfig): AiRouter;

package/dist/cjs/server/core/module-router.js

@@ -49,13 +49,15 @@ function defineModule(config) {
 /**
  * Create an AI router that selects tools based on classified intent.
  *
- * The router uses confidence-based expansion:
+ * Legacy routing uses confidence-based expansion:
  * - High confidence (>= 0.85): Only primary module's own tools
  * - Medium confidence (0.7-0.85): Primary module tools + shared tools from all modules
  * - Low confidence (< 0.7): All tools (ambiguous fallback)
+ * Focused routing instead leaves uncertain intents unselected for clarification
+ * or bounded discovery and expands only through explicit module relationships.
  */
 function createAiRouter(config) {
-    const { modules, relatedModules = {}, confidenceThresholds = {}, } = config;
+    const { modules, relatedModules = {}, confidenceThresholds = {}, routingMode = 'legacy', } = config;
     const thresholds = {
         high: confidenceThresholds.high ?? DEFAULT_THRESHOLDS.high,
         medium: confidenceThresholds.medium ?? DEFAULT_THRESHOLDS.medium,
@@ -64,6 +66,24 @@ function createAiRouter(config) {
     const allToolNames = getAllTools(modules);
     return {
         route(intent, _allToolNames) {
+            if (routingMode === 'focused') {
+                const primary = moduleMap.get(intent.intent);
+                if (intent.intent === 'ambiguous' || !primary
+                    || !Number.isFinite(intent.confidence)
+                    || intent.confidence < thresholds.medium
+                    || intent.confidence < 0 || intent.confidence > 1) {
+                    return { tools: [], module: null, strategy: 'none' };
+                }
+                const expanded = intent.confidence < thresholds.high;
+                const relatedShared = expanded
+                    ? (relatedModules[primary.id] ?? []).flatMap((id) => moduleMap.get(id)?.sharedTools ?? [])
+                    : [];
+                return {
+                    tools: unique([...primary.tools, ...(primary.sharedTools ?? []), ...relatedShared]),
+                    module: primary,
+                    strategy: expanded ? 'expanded' : 'single',
+                };
+            }
             // Ambiguous: use all tools
             if (intent.intent === 'ambiguous') {
                 return {

package/dist/cjs/server/core/plan-tool.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { type Tool } from '../../types.js';
+export interface PlanningConfig {
+    /** 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 PlanInputSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        status: z.ZodEnum<{
+            pending: "pending";
+            completed: "completed";
+            in_progress: "in_progress";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Built-in, side-effect-free planning tool. It never calls the app; the chat
+ * UI renders the latest call as a checklist and the turn simply continues.
+ */
+export declare function createPlanTool(config?: PlanningConfig): Tool | null;

package/dist/cjs/server/core/plan-tool.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlanInputSchema = void 0;
+exports.createPlanTool = createPlanTool;
+const zod_1 = require("zod");
+const types_js_1 = require("../../types.js");
+const plan_js_1 = require("../../contracts/plan.js");
+const DEFAULT_DESCRIPTION = [
+    'Show the user a short task list when a request needs several distinct',
+    'actions (for example: find tasks, then create a team, then invite members).',
+    'Never call it for a simple request that one or two tool calls answer.',
+    'Call it once before you start, then again with updated statuses whenever an',
+    'item starts or finishes. Keep exactly one item in_progress while you work.',
+].join(' ');
+exports.PlanInputSchema = zod_1.z.object({
+    items: zod_1.z.array(zod_1.z.object({
+        title: zod_1.z.string().trim().min(1).max(plan_js_1.PLAN_MAX_TITLE_LENGTH),
+        status: zod_1.z.enum(plan_js_1.PLAN_ITEM_STATUSES),
+    })).min(2).max(plan_js_1.PLAN_MAX_ITEMS),
+});
+/**
+ * Built-in, side-effect-free planning tool. It never calls the app; the chat
+ * UI renders the latest call as a checklist and the turn simply continues.
+ */
+function createPlanTool(config) {
+    if (config?.enabled === false)
+        return null;
+    return (0, types_js_1.defineTool)({
+        id: plan_js_1.PLAN_TOOL_NAME,
+        description: config?.description ?? DEFAULT_DESCRIPTION,
+        inputSchema: exports.PlanInputSchema,
+        needsApproval: false,
+        execute: async (input) => ({ success: true, items: input.items.length }),
+    });
+}

package/dist/cjs/server/core/zod-compact.d.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import type { SchemaLike } from '../../types.js';
 /**
  * Convert a Zod schema to a compact TypeScript-like description string.
  *
@@ -15,4 +15,4 @@ import { z } from 'zod';
  * @param schema - Any Zod schema
  * @param maxDepth - Maximum nesting depth before collapsing to "..." (default: 3)
  */
-export declare function zodToCompactDescription(schema: z.ZodTypeAny, maxDepth?: number): string;
+export declare function zodToCompactDescription(schema: SchemaLike, maxDepth?: number): string;

package/dist/cjs/server/core/zod-compact.js

@@ -20,9 +20,53 @@ exports.zodToCompactDescription = zodToCompactDescription;
 function zodToCompactDescription(schema, maxDepth = 3) {
     return describeSchema(schema, 0, maxDepth);
 }
-/** Read Zod v4's internal schema definition (`schema._zod.def`). */
+const ZOD_3_TYPES = {
+    ZodAny: 'any',
+    ZodArray: 'array',
+    ZodBigInt: 'bigint',
+    ZodBoolean: 'boolean',
+    ZodCatch: 'catch',
+    ZodDate: 'date',
+    ZodDefault: 'default',
+    ZodDiscriminatedUnion: 'union',
+    ZodEffects: 'effects',
+    ZodEnum: 'enum',
+    ZodLazy: 'lazy',
+    ZodLiteral: 'literal',
+    ZodNativeEnum: 'enum',
+    ZodNullable: 'nullable',
+    ZodNull: 'null',
+    ZodNumber: 'number',
+    ZodObject: 'object',
+    ZodOptional: 'optional',
+    ZodPipeline: 'pipe',
+    ZodReadonly: 'readonly',
+    ZodRecord: 'record',
+    ZodString: 'string',
+    ZodTuple: 'tuple',
+    ZodUndefined: 'undefined',
+    ZodUnion: 'union',
+    ZodUnknown: 'unknown',
+    ZodVoid: 'void',
+};
+/** Read and normalize Zod v3/v4 internal schema definitions. */
 function getDef(schema) {
-    return schema?._zod?.def;
+    const v4 = schema?._zod?.def;
+    if (v4)
+        return v4;
+    const v3 = schema?._def;
+    if (!v3)
+        return undefined;
+    return {
+        ...v3,
+        type: ZOD_3_TYPES[v3.typeName] ?? v3.typeName,
+        element: v3.type,
+        entries: v3.values
+            ? Object.fromEntries(v3.values.map((value) => [value, value]))
+            : v3.values,
+        in: v3.in ?? v3.schema,
+        valueType: v3.valueType,
+    };
 }
 function describeSchema(schema, depth, maxDepth) {
     if (depth >= maxDepth)
@@ -40,8 +84,7 @@ function describeSchema(schema, depth, maxDepth) {
         case 'date':
             return 'string'; // Dates serialize as strings in JSON
         case 'literal':
-            // Zod v4 literals hold an array of allowed values.
-            return def.values
+            return (def.values ?? [def.value])
                 .map((v) => JSON.stringify(v))
                 .join(' | ');
         case 'null':
@@ -62,7 +105,7 @@ function describeSchema(schema, depth, maxDepth) {
         case 'array':
             return `Array<${describeSchema(def.element, depth + 1, maxDepth)}>`;
         case 'object': {
-            const shape = def.shape;
+            const shape = (typeof def.shape === 'function' ? def.shape() : def.shape);
             const entries = Object.entries(shape);
             if (entries.length === 0)
                 return '{}';
@@ -78,8 +121,9 @@ function describeSchema(schema, depth, maxDepth) {
         case 'record':
             return `Record<string, ${describeSchema(def.valueType, depth + 1, maxDepth)}>`;
         case 'union': {
-            // Covers both unions and discriminated unions in Zod v4.
-            const options = def.options;
+            const options = (def.options instanceof Map
+                ? [...def.options.values()]
+                : def.options);
             return options
                 .map((o) => describeSchema(o, depth + 1, maxDepth))
                 .join(' | ');
@@ -101,6 +145,8 @@ function describeSchema(schema, depth, maxDepth) {
             // Transforms / refinements become pipes in Zod v4; describe the input
             // side, matching the pre-v4 behaviour of describing the base schema.
             return describeSchema(def.in, depth, maxDepth);
+        case 'effects':
+            return describeSchema(def.schema, depth, maxDepth);
         case 'lazy':
             return describeSchema(def.getter(), depth, maxDepth);
         default:
@@ -123,6 +169,9 @@ function unwrap(schema) {
     if (type === 'pipe') {
         return unwrap(def.in);
     }
+    if (type === 'effects') {
+        return unwrap(def.schema);
+    }
     return schema;
 }
 function isOptional(schema) {