glirastes 0.3.2 → 0.5.0

package/dist/cjs/server/adapters/nextjs/request-guards.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_BODY_BYTES = void 0;
+exports.checkRequestHeaders = checkRequestHeaders;
+exports.readJsonBody = readJsonBody;
+const context_helpers_js_1 = require("./context-helpers.js");
+/** Default cap on the request body of the chat handler: 1 MB. */
+exports.DEFAULT_MAX_BODY_BYTES = 1_000_000;
+const json = (status, error, message) => new Response(JSON.stringify({ error, message }), { status, headers: { 'Content-Type': 'application/json' } });
+/**
+ * Refuses a request a browser sent for another site, and a body that is not
+ * JSON.
+ *
+ * The chat route authenticates with the user's cookie, and a page on another
+ * site (also another subdomain of the same site) can make the browser post to
+ * it with that cookie. A `text/plain` form post needs no CORS preflight, so
+ * the content type must be JSON, which a cross-origin page cannot send
+ * without a preflight; and a browser cross-origin request is refused:
+ *
+ * - `Origin: null` (a sandboxed or opaque origin) is always refused.
+ * - `Sec-Fetch-Site`, when present, must be `same-origin` (or `none`, a
+ *   navigation by the user); `same-site` and `cross-site` pass only with an
+ *   `Origin` listed in `allowedOrigins`.
+ * - Otherwise `Origin`, when present, must be the request's own origin (the
+ *   request URL's, the Host header's, or the first forwarded host and
+ *   protocol, see `publicOrigins`) or one of `allowedOrigins`.
+ * - A request with neither header is not from a browser (server to server).
+ */
+function checkRequestHeaders(req, options = {}) {
+    if (options.crossOriginProtection !== false) {
+        const site = req.headers.get('sec-fetch-site');
+        const origin = req.headers.get('origin');
+        const refused = () => json(403, 'cross_origin_request_refused', 'Cross-origin requests are not allowed.');
+        if (origin === 'null')
+            return refused();
+        if (site !== null) {
+            // The browser's own verdict. Another site or subdomain passes only with
+            // an Origin the app listed itself; the request's own origin does not
+            // count here, because the browser says the request is not from it.
+            if (site !== 'same-origin' && site !== 'none') {
+                if (origin === null || !configuredOrigins(options.allowedOrigins).has(origin))
+                    return refused();
+            }
+        }
+        else if (origin !== null && !ownOrigins(req, options.allowedOrigins).has(origin)) {
+            return refused();
+        }
+    }
+    const mediaType = (req.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase();
+    if (mediaType !== 'application/json') {
+        return json(415, 'unsupported_media_type', 'The request body must be application/json.');
+    }
+    return undefined;
+}
+/** `value` without its trailing slashes; a plain loop, linear in the length (no regular expression). */
+function withoutTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 0x2f)
+        end -= 1;
+    return value.slice(0, end);
+}
+function configuredOrigins(allowed = []) {
+    return new Set(allowed.map(withoutTrailingSlashes).filter((origin) => origin !== 'null'));
+}
+function ownOrigins(req, allowed = []) {
+    const origins = configuredOrigins(allowed);
+    for (const origin of (0, context_helpers_js_1.publicOrigins)(req))
+        origins.add(origin);
+    return origins;
+}
+const tooLarge = () => json(413, 'payload_too_large', 'The request body is too large.');
+/**
+ * Reads the JSON body, or answers 413 once it exceeds `maxBytes` and 400
+ * (`invalid_json`) when it does not parse. The declared
+ * `Content-Length` is checked before the body is read, and the bytes actually
+ * read are counted, because the header may be absent (chunked) or wrong.
+ */
+async function readJsonBody(req, maxBytes = exports.DEFAULT_MAX_BODY_BYTES) {
+    const declared = Number(req.headers.get('content-length'));
+    if (req.headers.get('content-length') !== null && Number.isFinite(declared) && declared > maxBytes) {
+        return { ok: false, response: tooLarge() };
+    }
+    const chunks = [];
+    let total = 0;
+    if (req.body) {
+        const reader = req.body.getReader();
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel().catch(() => undefined);
+                return { ok: false, response: tooLarge() };
+            }
+            chunks.push(value);
+        }
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    try {
+        return { ok: true, value: JSON.parse(new TextDecoder().decode(bytes)) };
+    }
+    catch {
+        // A client error, not a server failure: no 500 and no onError.
+        return { ok: false, response: json(400, 'invalid_json', 'The request body is not valid JSON.') };
+    }
+}

package/dist/cjs/server/adapters/nextjs/sanitize-model-messages.js

@@ -76,17 +76,23 @@ function findPendingApprovalCallIds(messages, approvalIdToCallId) {
     const content = lastMsg.content;
     if (!Array.isArray(content))
         return pendingCallIds;
-    // Only consider this a pending approval if the tool message has NO
-    // tool-result parts (otherwise it's a completed step, not a pending approval)
-    const hasToolResult = content.some((part) => isRecord(part) && part.type === 'tool-result');
-    if (hasToolResult)
-        return pendingCallIds;
+    // A response whose own call already has a result here belongs to a completed
+    // step. A result of another call (a lookup made in the same step) does not
+    // complete it: collectToolApprovals still runs the approved call.
+    const resultCallIds = new Set();
+    for (const part of content) {
+        if (isRecord(part) &&
+            part.type === 'tool-result' &&
+            typeof part.toolCallId === 'string') {
+            resultCallIds.add(part.toolCallId);
+        }
+    }
     for (const part of content) {
         if (isRecord(part) &&
             part.type === 'tool-approval-response' &&
             typeof part.approvalId === 'string') {
             const linkedCallId = approvalIdToCallId.get(part.approvalId);
-            if (linkedCallId) {
+            if (linkedCallId && !resultCallIds.has(linkedCallId)) {
                 pendingCallIds.add(linkedCallId);
             }
         }

package/dist/cjs/server/adapters/nextjs/scope-pipeline-tools.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Scope the model-facing tools to the pipeline's module selection.
+ *
+ * A selected name missing from `aiTools` but present in the registry was
+ * removed for this principal (roles, approval state) and is skipped silently.
+ * A selected name the registry has never served is configuration drift —
+ * module definitions referencing retired tool names once shipped an app whose
+ * model could not call a single domain tool while every probe stayed green.
+ * That case fails closed and names the offenders.
+ */
+export declare function scopePipelineTools<T>(options: {
+    aiTools: Record<string, T>;
+    registryToolNames: ReadonlySet<string>;
+    selected: ReadonlyArray<string>;
+    /** Preserve historical behavior unless the pipeline declares an exact selection. */
+    fallbackToAll?: boolean;
+}): Record<string, T>;

package/dist/cjs/server/adapters/nextjs/scope-pipeline-tools.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scopePipelineTools = scopePipelineTools;
+/**
+ * Scope the model-facing tools to the pipeline's module selection.
+ *
+ * A selected name missing from `aiTools` but present in the registry was
+ * removed for this principal (roles, approval state) and is skipped silently.
+ * A selected name the registry has never served is configuration drift —
+ * module definitions referencing retired tool names once shipped an app whose
+ * model could not call a single domain tool while every probe stayed green.
+ * That case fails closed and names the offenders.
+ */
+function scopePipelineTools(options) {
+    const unknown = options.selected.filter((name) => !options.registryToolNames.has(name));
+    if (unknown.length > 0) {
+        throw new Error('Pipeline selected tools unknown to the tool registry '
+            + `(module configuration drift): ${unknown.join(', ')}`);
+    }
+    const scoped = {};
+    for (const name of options.selected) {
+        if (options.aiTools[name])
+            scoped[name] = options.aiTools[name];
+    }
+    return options.fallbackToAll === false || Object.keys(scoped).length > 0
+        ? scoped
+        : options.aiTools;
+}

package/dist/cjs/server/adapters/nextjs/tool-discovery.d.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import type { ToolDiscoveryResult, TurnToolDiscovery } from '../../../runtime/index.js';
+declare const FindToolsInputSchema: z.ZodObject<{
+    query: z.ZodString;
+}, z.core.$strip>;
+/**
+ * SDK-provided tools that are never domain capabilities: registry-mode
+ * `find_tools` never indexes them, and they are not manifest tools.
+ */
+export declare const NON_DOMAIN_TOOL_NAMES: readonly ["find_tools", "suggest_followups", "ask_clarification", "update_plan"];
+export interface HybridToolDiscovery {
+    readonly turnId: string;
+    readonly tool: {
+        description: string;
+        parameters: typeof FindToolsInputSchema;
+        execute(input: unknown): Promise<{
+            tools: ReadonlyArray<ToolDiscoveryResult>;
+        }>;
+    };
+    activeToolNames(): ReadonlyArray<string>;
+    prepareStep(): {
+        activeTools: ReadonlyArray<string>;
+    };
+}
+/**
+ * Turn-local activation bookkeeping. Only names emitted by the immutable
+ * discovery index can be added; model-supplied names and descriptors are
+ * ignored by construction.
+ */
+export declare function createHybridToolDiscovery(options: {
+    discovery: TurnToolDiscovery;
+    initialToolNames: ReadonlyArray<string>;
+    /**
+     * Server-configured SDK tools (for example `ask_clarification`) that stay
+     * active for the whole turn. They are never searchable or model-supplied.
+     */
+    builtinToolNames?: ReadonlyArray<string>;
+}): HybridToolDiscovery;
+export {};

package/dist/cjs/server/adapters/nextjs/tool-discovery.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NON_DOMAIN_TOOL_NAMES = void 0;
+exports.createHybridToolDiscovery = createHybridToolDiscovery;
+const zod_1 = require("zod");
+const FindToolsInputSchema = zod_1.z.object({
+    query: zod_1.z.string().trim().min(1).max(200),
+});
+/**
+ * SDK-provided tools that are never domain capabilities: registry-mode
+ * `find_tools` never indexes them, and they are not manifest tools.
+ */
+exports.NON_DOMAIN_TOOL_NAMES = Object.freeze([
+    'find_tools',
+    'suggest_followups',
+    'ask_clarification',
+    'update_plan',
+]);
+/**
+ * Turn-local activation bookkeeping. Only names emitted by the immutable
+ * discovery index can be added; model-supplied names and descriptors are
+ * ignored by construction.
+ */
+function createHybridToolDiscovery(options) {
+    const eligible = new Set(options.discovery.eligibleNames);
+    const builtins = [...new Set(options.builtinToolNames ?? [])]
+        .filter((name) => name !== 'find_tools' && !eligible.has(name));
+    const active = new Set(options.initialToolNames.filter((name) => eligible.has(name)));
+    const activeNames = () => Object.freeze(['find_tools', ...builtins, ...active]
+        .sort((left, right) => left.localeCompare(right)));
+    const controller = {
+        turnId: options.discovery.turnId,
+        tool: {
+            description: 'Find eligible tools for the current turn by capability or intent.',
+            parameters: FindToolsInputSchema,
+            async execute(input) {
+                const { query } = FindToolsInputSchema.parse(input);
+                const tools = options.discovery.search(query);
+                for (const match of tools) {
+                    if (eligible.has(match.name))
+                        active.add(match.name);
+                }
+                return { tools };
+            },
+        },
+        activeToolNames: activeNames,
+        prepareStep: () => ({ activeTools: activeNames() }),
+    };
+    return Object.freeze(controller);
+}

package/dist/cjs/server/adapters/nextjs/tool-presentation.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The wording the chat UI shows for the tools of a turn: a short label per
+ * tool, keyed by the name the model calls it by, and the language of the app.
+ * It comes from the pinned manifest (`presentation`, derived by
+ * `glirastes tools refresh` or written with the tool descriptions), so a chat
+ * without any `toolLabels` of its own never shows a raw tool name.
+ */
+export interface ToolPresentationPart {
+    locale: string;
+    tools: Record<string, {
+        label: string;
+    }>;
+}
+interface WordedManifest {
+    tools: ReadonlyArray<{
+        name: string;
+        modelName?: string;
+        presentation?: {
+            locale: string;
+            approval: string;
+        };
+    }>;
+}
+/** Null when the manifest words none of its tools. */
+export declare function toolPresentationOf(manifest: WordedManifest | undefined): ToolPresentationPart | null;
+export {};

package/dist/cjs/server/adapters/nextjs/tool-presentation.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolPresentationOf = toolPresentationOf;
+/** Null when the manifest words none of its tools. */
+function toolPresentationOf(manifest) {
+    if (!manifest)
+        return null;
+    const tools = {};
+    let locale;
+    for (const tool of manifest.tools) {
+        if (!tool.presentation)
+            continue;
+        // The confirmation may be phrased as a question; the label is the action.
+        const label = tool.presentation.approval.replace(/\s*\?+\s*$/, '').trim();
+        if (label === '')
+            continue;
+        tools[tool.modelName ?? tool.name] = { label };
+        locale ??= tool.presentation.locale;
+    }
+    return locale === undefined ? null : { locale, tools };
+}

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