glirastes 0.3.2 → 0.5.0

package/dist/server/adapters/nextjs/create-ai-chat-handler.js

@@ -1,9 +1,22 @@
-import { toolsToAiTools, createFollowupTool } from '../../core/index.js';
+import { toolsToAiTools, createFollowupTool, createClarificationTool, createPlanTool, } from '../../core/index.js';
+import { CLARIFICATION_TOOL_NAME } from '../../../contracts/clarification.js';
+import { PLAN_TOOL_NAME } from '../../../contracts/plan.js';
+/** Handler-created built-ins that stay callable for every tool selection. */
+const ALWAYS_ON_BUILTINS = [CLARIFICATION_TOOL_NAME, PLAN_TOOL_NAME];
+import { applyClarificationResume, resolveClarificationResume, } from './clarification-resume.js';
+import { scopePipelineTools } from './scope-pipeline-tools.js';
+import { checkRequestHeaders, readJsonBody } from './request-guards.js';
+import { ApprovalHistoryError, ApprovalSecretMissingError, approvalScope, assertApprovalMaxAge, assertUnambiguousToolHistory, bindApprovalRequests, createApprovalExecutionGate, defaultApprovalStore, enforceApprovalBindings, gateApprovalTools, resolveApprovalBinder, } from './approval-binding.js';
+import { pseudonymizeCommandToolInputs, resolveDirectCommand, runDirectCommand, stripChatCommandMessages, } from './direct-command.js';
 import { applyPromptOverride } from '../../../types.js';
 import { streamText, createUIMessageStream, createUIMessageStreamResponse, } from 'ai';
 import { buildToolContext, createInternalApiCallerFromRequest, } from './context-helpers.js';
 import { prepareModelMessages, wrapToolsForVercelAi } from './prepare-model-messages.js';
 import { filterFallbackError } from './filter-fallback-error.js';
+import { toolPresentationOf } from './tool-presentation.js';
+import { PrincipalSchema } from '../../../contracts/index.js';
+import { createManagedTurnGuard, createRegistryToolDiscovery, createTurnMetricsRecorder, createTurnToolDiscovery, isToolRevoked, rawChunkCostUsd, resolveStepCost, RuntimePriceTableSchema, } from '../../../runtime/index.js';
+import { createHybridToolDiscovery, NON_DOMAIN_TOOL_NAMES, } from './tool-discovery.js';
 /**
  * Default soft cap on reasoning steps when no module-level or explicit
  * `maxSteps` is configured. Acts as a last-line safety against runaway
@@ -19,18 +32,74 @@ function asPositiveInt(value) {
     return normalized > 0 ? normalized : null;
 }
 export function resolveStepLimit(options) {
+    let resolved;
     const moduleMaxSteps = asPositiveInt(options.moduleMaxSteps);
     if (moduleMaxSteps) {
-        return { maxSteps: moduleMaxSteps, stepLimitSource: 'module' };
+        resolved = { maxSteps: moduleMaxSteps, stepLimitSource: 'module' };
     }
-    const configuredMaxSteps = asPositiveInt(options.configuredMaxSteps);
-    if (configuredMaxSteps) {
-        return { maxSteps: configuredMaxSteps, stepLimitSource: 'explicit' };
+    else {
+        const configuredMaxSteps = asPositiveInt(options.configuredMaxSteps);
+        resolved = configuredMaxSteps
+            ? { maxSteps: configuredMaxSteps, stepLimitSource: 'explicit' }
+            : {
+                maxSteps: asPositiveInt(options.safetyMaxSteps)
+                    ?? DEFAULT_SAFETY_MAX_STEPS,
+                stepLimitSource: 'safety',
+            };
     }
-    return {
-        maxSteps: asPositiveInt(options.safetyMaxSteps) ?? DEFAULT_SAFETY_MAX_STEPS,
-        stepLimitSource: 'safety',
-    };
+    const runtimeBudgetMaxSteps = asPositiveInt(options.runtimeBudgetMaxSteps);
+    return runtimeBudgetMaxSteps && runtimeBudgetMaxSteps < resolved.maxSteps
+        ? {
+            maxSteps: runtimeBudgetMaxSteps,
+            stepLimitSource: 'runtime-budget',
+        }
+        : resolved;
+}
+export function resolveTurnTimeout(totalTimeoutMs) {
+    if (totalTimeoutMs === undefined)
+        return undefined;
+    if (!Number.isFinite(totalTimeoutMs) || totalTimeoutMs <= 0) {
+        throw new RangeError('totalTimeoutMs must be a positive finite number');
+    }
+    return { totalMs: totalTimeoutMs };
+}
+export function shouldStopManagedExecution(options) {
+    return options.stepCount >= options.maxSteps
+        || options.budgetState === 'hard-limit'
+        || (options.lastStepToolNames ?? []).includes(CLARIFICATION_TOOL_NAME);
+}
+/** Model id of a finished step; AI SDK 6 versions differ in where they put it. */
+function stepModelId(event) {
+    const record = event;
+    const modelId = record.model?.modelId ?? record.response?.modelId;
+    return typeof modelId === 'string' ? modelId : null;
+}
+/**
+ * Names of the tool calls of a step that failed: thrown errors and the
+ * `{ error }` results SDK tools return. Only names leave this function.
+ */
+function failedToolNames(content) {
+    const names = [];
+    for (const part of content) {
+        const record = part;
+        if (typeof record?.toolName !== 'string')
+            continue;
+        const output = record.output;
+        if (record.type === 'tool-error'
+            || (record.type === 'tool-result'
+                && typeof output === 'object'
+                && output !== null
+                && typeof output.error === 'string')) {
+            names.push(record.toolName);
+        }
+    }
+    return names;
+}
+/** Hands endpoint contract rejections to the turn's metrics, when the app reports metrics. */
+function contractRejectionReporter(turnMetrics) {
+    return turnMetrics
+        ? { onContractRejected: ({ toolName, status }) => { turnMetrics.recordToolContractRejected(toolName, status); } }
+        : {};
 }
 function compactToolNames(toolCalls) {
     const unique = new Set();
@@ -111,34 +180,63 @@ function createPipelineState(options) {
  * Converts UI messages → model messages, wraps tools, calls streamText,
  * and returns a UI message stream response.
  */
-async function defaultStreamHandler(ctx, onFinish) {
-    const vercelTools = wrapToolsForVercelAi(ctx.tools);
+async function defaultStreamHandler(ctx, onFinish, onStreamError) {
+    // SDK built-ins the handler created itself are not manifest tools, so the
+    // managed guard would deny them. Everything else stays guarded.
+    const builtinNames = new Set(ctx.handlerBuiltinToolNames ?? []);
+    const builtinTools = {};
+    const domainTools = {};
+    for (const [name, tool] of Object.entries(ctx.tools)) {
+        (builtinNames.has(name) ? builtinTools : domainTools)[name] = tool;
+    }
+    const vercelTools = wrapToolsForVercelAi(domainTools, ctx.managedTurn
+        ? {
+            beforeToolCall: ctx.managedTurn.beforeToolCall,
+            afterToolCall: ctx.managedTurn.afterToolCall,
+            onToolError: ctx.managedTurn.onToolError,
+            resolveApproval: ctx.managedTurn.resolveApproval,
+            toolTimeoutMs: ctx.managedTurn.toolTimeoutMs,
+        }
+        : undefined);
+    if (Object.keys(builtinTools).length > 0) {
+        Object.assign(vercelTools, wrapToolsForVercelAi(builtinTools));
+    }
     const modelMessages = await prepareModelMessages(ctx.messages, { maxContextMessages: ctx.maxContextMessages });
     let wasTruncated = false;
-    let stoppedByLoop = false;
-    // Stop condition: step count OR consecutive identical tool calls (loop detection).
-    const LOOP_REPEAT_THRESHOLD = 3;
+    // At the runtime budget the turn blocks further tools and gets one bounded
+    // final summary, so it still ends with an answer instead of silence.
+    let finalSummaryClaimed = false;
+    const budgetExhausted = () => ctx.managedTurn?.tracker.evaluate().state === 'hard-limit';
     const shouldStop = (event) => {
-        if (event.steps.length >= ctx.maxSteps)
-            return true;
-        if (event.steps.length >= LOOP_REPEAT_THRESHOLD) {
-            const recent = event.steps.slice(-LOOP_REPEAT_THRESHOLD);
-            const signatures = recent.map((s) => s.toolCalls
-                .map((c) => c.toolName)
-                .sort()
-                .join(','));
-            if (signatures[0].length > 0 &&
-                signatures.every((sig) => sig === signatures[0])) {
-                stoppedByLoop = true;
-                return true;
-            }
-        }
-        return false;
+        const budgetState = ctx.managedTurn?.tracker.evaluate().state;
+        const summarize = budgetState === 'hard-limit'
+            && ctx.managedTurn.tracker.claimFinalSummary();
+        if (summarize)
+            finalSummaryClaimed = true;
+        return shouldStopManagedExecution({
+            stepCount: event.steps.length,
+            maxSteps: ctx.maxSteps,
+            budgetState: summarize ? undefined : budgetState,
+            lastStepToolNames: event.steps.at(-1)?.toolCalls.map((call) => call.toolName),
+        });
     };
+    let providerErrorReported = false;
     const stream = createUIMessageStream({
+        // A turn can also fail outside the provider call, e.g. on a model object
+        // from an unsupported AI SDK version. The client gets the generic text,
+        // the app's error callback the cause.
+        onError: (error) => {
+            if (!providerErrorReported) {
+                providerErrorReported = true;
+                onStreamError?.(error);
+            }
+            return 'AI request failed';
+        },
         execute: async ({ writer }) => {
             let totalSteps = 0;
             let finalStateWritten = false;
+            // Cost of the running model step, read from its raw stream chunks.
+            let stepRawCostUsd = null;
             const writePipelineState = (state, transient = false) => {
                 writer.write({
                     type: 'data-pipeline-state',
@@ -146,6 +244,11 @@ async function defaultStreamHandler(ctx, onFinish) {
                     transient,
                 });
             };
+            // Ahead of the first chunk, so the UI can name a tool the moment it is called.
+            const presentation = toolPresentationOf(ctx.managedTurn?.snapshot.manifestRevision);
+            if (presentation) {
+                writer.write({ type: 'data-tool-presentation', data: presentation, transient: true });
+            }
             writePipelineState(createPipelineState({
                 status: 'running',
                 totalSteps: 0,
@@ -157,10 +260,66 @@ async function defaultStreamHandler(ctx, onFinish) {
                 messages: modelMessages,
                 system: ctx.systemPrompt,
                 tools: vercelTools,
+                ...(ctx.toolDiscovery
+                    ? { activeTools: [...ctx.toolDiscovery.activeToolNames()] }
+                    : {}),
+                prepareStep: () => {
+                    if (budgetExhausted()) {
+                        return { activeTools: [], toolChoice: 'none' };
+                    }
+                    return ctx.toolDiscovery
+                        ? { activeTools: [...ctx.toolDiscovery.activeToolNames()] }
+                        : {};
+                },
                 maxOutputTokens: ctx.maxOutputTokens,
                 temperature: ctx.temperature,
+                timeout: resolveTurnTimeout(ctx.managedTurn?.snapshot.budget.totalTimeoutMs),
                 stopWhen: shouldStop,
-                onStepFinish: (event) => {
+                // OpenRouter reports `usage.cost` only in the raw final chunk when the
+                // OpenAI-compatible provider is used; the UI stream drops raw chunks.
+                includeRawChunks: Boolean(ctx.managedTurn || ctx.turnMetrics),
+                onChunk: ({ chunk }) => {
+                    if (chunk.type === 'raw') {
+                        stepRawCostUsd = rawChunkCostUsd(chunk.rawValue) ?? stepRawCostUsd;
+                        return;
+                    }
+                    ctx.turnMetrics?.markFirstChunk();
+                },
+                // AI SDK's default logs the complete provider error, including
+                // request/response content. Only the local consumer owns diagnostics.
+                onError: ({ error }) => {
+                    providerErrorReported = true;
+                    onStreamError?.(error);
+                },
+                onStepFinish: async (event) => {
+                    const inputTokens = event.usage.inputTokens ?? 0;
+                    const outputTokens = event.usage.outputTokens ?? 0;
+                    const model = stepModelId(event);
+                    const rawCostUsd = stepRawCostUsd;
+                    stepRawCostUsd = null;
+                    const cost = resolveStepCost({
+                        model,
+                        inputTokens,
+                        outputTokens,
+                        providerMetadata: event.providerMetadata,
+                        usageRaw: event.usage.raw,
+                        rawChunkCostUsd: rawCostUsd,
+                    }, ctx.modelPricing);
+                    // A known cost counts against maxEstimatedCostUsd; an unknown one
+                    // is never recorded as 0.
+                    await ctx.managedTurn?.afterModelStep({
+                        inputTokens,
+                        outputTokens,
+                        ...(cost.usd !== null ? { estimatedCostUsd: cost.usd } : {}),
+                    });
+                    ctx.turnMetrics?.recordStep({
+                        model,
+                        inputTokens,
+                        outputTokens,
+                        cost,
+                        toolNames: event.toolCalls.map((call) => call.toolName),
+                        failedToolNames: failedToolNames(event.content),
+                    });
                     const report = buildStepReport({
                         stepNumber: event.stepNumber,
                         finishReason: event.finishReason,
@@ -185,6 +344,12 @@ async function defaultStreamHandler(ctx, onFinish) {
                     ctx.onStepReport?.(report);
                 },
                 onAbort: (event) => {
+                    // The runtime time budget is the only abort source of this handler,
+                    // so an abort at the hard limit is a budget stop, not a user abort.
+                    const abortedByBudget = ctx.managedTurn?.tracker.evaluate().state === 'hard-limit';
+                    ctx.turnMetrics?.finish(abortedByBudget
+                        ? { status: 'safety-stop', errorCode: 'budget_exhausted' }
+                        : { status: 'aborted', errorCode: null });
                     if (finalStateWritten)
                         return;
                     totalSteps = Math.max(totalSteps, event.steps.length);
@@ -199,18 +364,26 @@ async function defaultStreamHandler(ctx, onFinish) {
                     finalStateWritten = true;
                 },
                 onFinish: (event) => {
-                    wasTruncated =
-                        event.finishReason === 'tool-calls' &&
-                            (event.steps.length >= ctx.maxSteps || stoppedByLoop);
+                    const budgetEvaluation = ctx.managedTurn?.tracker.evaluate();
+                    const stoppedByBudget = budgetEvaluation?.state === 'hard-limit';
+                    wasTruncated = finalSummaryClaimed || (event.finishReason === 'tool-calls' &&
+                        (event.steps.length >= ctx.maxSteps || stoppedByBudget));
                     totalSteps = Math.max(totalSteps, event.steps.length);
-                    const isSafetyStop = wasTruncated && ctx.stepLimitSource === 'safety' && !stoppedByLoop;
-                    const status = stoppedByLoop
+                    const isSafetyStop = wasTruncated
+                        && (ctx.stepLimitSource === 'safety'
+                            || ctx.stepLimitSource === 'runtime-budget'
+                            || stoppedByBudget);
+                    const status = isSafetyStop
                         ? 'safety-stop'
-                        : isSafetyStop
-                            ? 'safety-stop'
-                            : event.finishReason === 'error'
-                                ? 'error'
-                                : 'completed';
+                        : event.finishReason === 'error'
+                            ? 'error'
+                            : 'completed';
+                    ctx.turnMetrics?.finish({
+                        status,
+                        errorCode: status === 'safety-stop'
+                            ? stoppedByBudget ? 'budget_exhausted' : 'step_limit'
+                            : status === 'error' ? 'model_error' : null,
+                    });
                     if (!finalStateWritten) {
                         writePipelineState(createPipelineState({
                             status,
@@ -218,8 +391,8 @@ async function defaultStreamHandler(ctx, onFinish) {
                             finishReason: event.finishReason,
                             maxSteps: ctx.maxSteps,
                             stepLimitSource: ctx.stepLimitSource,
-                            message: stoppedByLoop
-                                ? 'Stopped: repeated tool call loop detected.'
+                            message: stoppedByBudget
+                                ? `Stopped at runtime budget: ${budgetEvaluation.reasons.join(', ')}.`
                                 : wasTruncated
                                     ? isSafetyStop
                                         ? 'Paused at step safety cap. You can continue or stop.'
@@ -242,11 +415,13 @@ async function defaultStreamHandler(ctx, onFinish) {
                     });
                 },
             });
-            writer.merge(result.toUIMessageStream());
+            const uiStream = result.toUIMessageStream({ onError: () => 'AI request failed' });
+            writer.merge(ctx.bindApprovalRequests ? ctx.bindApprovalRequests(uiStream) : uiStream);
             try {
                 await result.response;
             }
             catch (error) {
+                ctx.turnMetrics?.finish({ status: 'error', errorCode: 'model_error' });
                 if (finalStateWritten)
                     return;
                 writePipelineState(createPipelineState({
@@ -258,7 +433,8 @@ async function defaultStreamHandler(ctx, onFinish) {
                     message: 'Pipeline failed.',
                 }));
                 finalStateWritten = true;
-                throw error;
+                if (!providerErrorReported)
+                    throw error;
             }
         },
     });
@@ -284,7 +460,7 @@ async function defaultStreamHandler(ctx, onFinish) {
  * checks happen on the backend.
  */
 export function createAiChatHandler(config) {
-    const { tools: staticTools, pipeline, followups, loadTools, 
+    const { tools: staticTools, managedRuntime, pipeline, followups, clarification, planning, loadTools, 
     // PII Shield
     piiShield, 
     // Audit & Telemetry
@@ -292,7 +468,29 @@ export function createAiChatHandler(config) {
     // Lancer (Pro: runtime prompt + model overrides)
     lancer, modelDefaults, modelInstanceFactory, 
     // Shared
-    model: modelConfig, systemPrompt: systemPromptConfig, locale = 'en-US', uiActionSchema, maxOutputTokens = 600, temperature = 0.2, maxSteps: configuredMaxSteps, safetyMaxSteps = DEFAULT_SAFETY_MAX_STEPS, emitStepReports = true, maxContextMessages = 12, maxConversationHistoryPairs = 4, guardrails, intentRouter, wrapHandler, onError, onToolError, onPipelineResult, onStepReport, onFinish, streamHandler: customStreamHandler, } = config;
+    model: modelConfig, systemPrompt: systemPromptConfig, locale = 'en-US', uiActionSchema, maxOutputTokens = 600, temperature = 0.2, maxSteps: configuredMaxSteps, safetyMaxSteps = DEFAULT_SAFETY_MAX_STEPS, emitStepReports = true, maxContextMessages = 12, maxConversationHistoryPairs = 4, guardrails, intentRouter, wrapHandler, onError: onErrorConfig, onToolError, onPipelineResult, onStepReport, onFinish, streamHandler: customStreamHandler, toolDiscovery: enableToolDiscovery = false, toolSemantics, metrics, modelPricing: configuredModelPricing, directCommands = true, trustForwardedHeaders = false, endpointCaller = (request) => createInternalApiCallerFromRequest(request, { trustForwardedHeaders }), approvalSecret, approvalMaxAgeMs, approvalStore: configuredApprovalStore, approvalScope: approvalScopeOf, allowedOrigins, crossOriginProtection, maxBodyBytes, } = config;
+    if (approvalMaxAgeMs !== undefined)
+        assertApprovalMaxAge(approvalMaxAgeMs);
+    // Without a callback a failed turn would only say "AI request failed" to
+    // the user and nothing to the developer. Name only: provider errors can
+    // carry request and response content.
+    const onError = onErrorConfig ?? ((error) => {
+        const name = error instanceof Error ? error.name : typeof error;
+        console.error(`[glirastes] AI chat turn failed (${name}). Pass onError to createAiChatHandler to see the cause.`);
+    });
+    // The Proctor endpoint behind Lancer telemetry is not served by the
+    // Foundation control plane and its audit payloads are not content-free;
+    // the managed-local path reports through `metrics` instead.
+    if (managedRuntime && telemetry) {
+        throw new Error('createAiChatHandler: telemetry (legacy Lancer) cannot be combined with '
+            + 'managedRuntime; use metrics for content-free runtime metrics');
+    }
+    // Single use without configuration: one process's memory. Instances that
+    // share a secret need a shared store to refuse a replay across instances.
+    const approvalStore = configuredApprovalStore ?? defaultApprovalStore();
+    const modelPricing = configuredModelPricing
+        ? RuntimePriceTableSchema.parse(configuredModelPricing)
+        : undefined;
     // Report model defaults to Glirastes (fire-and-forget, once)
     let defaultsReported = false;
     function reportDefaultsOnce() {
@@ -302,7 +500,7 @@ export function createAiChatHandler(config) {
         lancer.config.reportModels(modelDefaults).catch(() => { });
     }
     // Build stream handler factory — per-request to allow session.ended audit
-    function createStreamHandler(auditContext) {
+    function createStreamHandler(req, auditContext) {
         const wrappedOnFinish = (event) => {
             onFinish?.(event);
             if (auditContext && (onAudit || telemetry)) {
@@ -339,23 +537,223 @@ export function createAiChatHandler(config) {
         };
         return customStreamHandler
             ? customStreamHandler
-            : (ctx) => defaultStreamHandler(ctx, wrappedOnFinish);
+            : (ctx) => defaultStreamHandler(ctx, wrappedOnFinish, (error) => onError?.(error, req));
     }
     if (!staticTools && !loadTools) {
         throw new Error('createAiChatHandler: either tools or loadTools must be provided');
     }
+    const clarificationTool = clarification
+        ? createClarificationTool(clarification)
+        : null;
+    const planTool = planning ? createPlanTool(planning) : null;
+    const withAlwaysOnBuiltins = (registry) => {
+        let next = registry;
+        for (const tool of [clarificationTool, planTool]) {
+            if (tool && !next[tool.id])
+                next = { ...next, [tool.id]: tool };
+        }
+        return next;
+    };
+    /** Keeps the always-on built-ins of `source` next to a scoped selection. */
+    const keepAlwaysOn = (scoped, source) => {
+        const kept = { ...scoped };
+        for (const name of ALWAYS_ON_BUILTINS) {
+            if (source[name])
+                kept[name] = source[name];
+        }
+        return kept;
+    };
+    /**
+     * The approval binder of a request, and the history with every approved
+     * call that this server did not issue (or that is expired or used) denied.
+     * Runs once the registry is known: whether tools can ask for approval
+     * decides if a missing secret is an error.
+     */
+    /**
+     * Who an approval of this request is for: the managed principal, else the
+     * app's `approvalScope(req)` (encoded as a one-element JSON array, so it
+     * cannot equal a managed scope), else `''`: the approval is then bound to
+     * no user, and `storeScopeOf` keeps the quota per caller instead.
+     */
+    async function requestApprovalScope(req, managedTurn) {
+        if (managedTurn)
+            return approvalScope(managedTurn.snapshot.principal);
+        if (!approvalScopeOf)
+            return '';
+        const scope = await approvalScopeOf(req);
+        if (typeof scope !== 'string')
+            throw new TypeError('approvalScope must return a string');
+        return JSON.stringify([scope]);
+    }
+    /**
+     * The scope the approval store counts a request's approvals under. With a
+     * managed principal or `approvalScope`, the signed scope. Otherwise a key
+     * per caller derived from the request's credentials (`Authorization`, else
+     * `Cookie`), HMAC-ed with the approval secret and never kept raw, so one
+     * caller with fixed credentials cannot use up everyone's quota (varying
+     * them gives a fresh quota; only the store's global limit bounds that).
+     * It only partitions the quota: it
+     * is not signed into the approval id (a cookie may rotate between the
+     * approval request and its answer), and single use is checked by the
+     * approval id across all keys. A request without credentials has `''`.
+     */
+    function storeScopeOf(req, scope, binder) {
+        if (scope !== '')
+            return scope;
+        const credentials = req.headers.get('authorization') ?? req.headers.get('cookie');
+        if (!credentials || !binder.callerQuotaKey)
+            return '';
+        return binder.callerQuotaKey(credentials);
+    }
+    async function secureApprovals(req, registry, messages, managedTurn, scope) {
+        const binder = resolveApprovalBinder({
+            secret: approvalSecret,
+            maxAgeMs: approvalMaxAgeMs,
+            scope,
+            // The managed policy and Lancer approvals can ask for approval of a
+            // tool that declares none.
+            hasApprovalTools: Boolean(managedTurn)
+                || Boolean(lancer?.approvals)
+                || Object.values(registry).some((tool) => Boolean(tool.needsApproval)),
+        });
+        const storeScope = storeScopeOf(req, scope, binder);
+        const checked = await enforceApprovalBindings(messages, {
+            binder, store: approvalStore, scope: storeScope, localToolNames: new Set(Object.keys(registry)),
+        });
+        return { binder, storeScope, messages: checked.messages, verified: checked.verified };
+    }
+    /**
+     * The tools handed to the stream handler, each one that can ask for
+     * approval behind the execution gate of this request: it runs only for an
+     * approval verified above (exact tool call id, tool name and input) or for
+     * a live call whose `needsApproval` said no. A managed policy can ask for
+     * approval of any domain tool, so with a managed turn every domain tool is
+     * gated; the handler's own built-ins are not.
+     */
+    function gateTools(tools, verified, managedTurn, builtinNames) {
+        return gateApprovalTools(tools, createApprovalExecutionGate(verified), (name, tool) => Boolean(tool.needsApproval) || (Boolean(managedTurn) && !builtinNames.includes(name)));
+    }
     async function handler(req) {
+        const refused = checkRequestHeaders(req, { allowedOrigins, crossOriginProtection });
+        if (refused)
+            return refused;
         reportDefaultsOnce();
+        let turnMetrics;
         try {
-            const { messages } = await req.json();
-            if (!Array.isArray(messages)) {
+            const body = await readJsonBody(req, maxBodyBytes);
+            if (!body.ok)
+                return body.response;
+            const { messages: requestMessages, glirastesClientActions } = body.value;
+            if (!Array.isArray(requestMessages)) {
                 return new Response(JSON.stringify({ error: 'messages must be an array' }), { status: 400, headers: { 'Content-Type': 'application/json' } });
             }
+            // A history the AI SDK could read in two ways (a tool call id in two
+            // parts, a non-boolean approval answer) is refused before anything else.
+            try {
+                assertUnambiguousToolHistory(requestMessages);
+            }
+            catch (error) {
+                if (error instanceof ApprovalHistoryError)
+                    return approvalHistoryRefusal(error);
+                throw error;
+            }
+            // A direct command (`/` command or entity action) runs its tool without
+            // the model; the model sees earlier commands only by their label.
+            const directCommand = directCommands ? resolveDirectCommand(requestMessages) : undefined;
+            // A clarification answer resumes its original request: routing sees
+            // request + answer, the model sees an explicit continuation. The client
+            // session keeps the untouched messages.
+            const clarificationResume = directCommand ? undefined : resolveClarificationResume(requestMessages);
+            const messages = directCommand
+                ? requestMessages
+                : stripChatCommandMessages(clarificationResume
+                    ? applyClarificationResume(requestMessages, clarificationResume)
+                    : requestMessages);
             // Build tool context
-            const toolContext = buildToolContext(req, { locale });
+            const toolContext = buildToolContext(req, { locale, trustForwardedHeaders });
+            const clientActions = readClientActions(glirastesClientActions);
+            if (clientActions)
+                toolContext.runtime = { ...toolContext.runtime, clientActions };
             const requestStart = Date.now();
+            const turnId = deriveSessionId(messages);
+            let managedTurn;
+            if (managedRuntime) {
+                const principalResult = PrincipalSchema.safeParse(await managedRuntime.resolvePrincipal(req));
+                if (!principalResult.success) {
+                    return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401, headers: { 'Content-Type': 'application/json' } });
+                }
+                const snapshot = await managedRuntime.resolveTurnSnapshot({
+                    request: req,
+                    turnId,
+                    principal: principalResult.data,
+                });
+                if (snapshot.turnId !== turnId
+                    || snapshot.principal.subjectId !== principalResult.data.subjectId
+                    || snapshot.principal.tenantId !== principalResult.data.tenantId) {
+                    return new Response(JSON.stringify({ error: 'Turn snapshot identity mismatch' }), { status: 403, headers: { 'Content-Type': 'application/json' } });
+                }
+                managedTurn = createManagedTurnGuard({
+                    snapshot,
+                    resolvePrincipal: async () => {
+                        const current = PrincipalSchema.safeParse(await managedRuntime.resolvePrincipal(req));
+                        return current.success ? current.data : undefined;
+                    },
+                    loadRevocations: managedRuntime.loadRevocations
+                        ? () => managedRuntime.loadRevocations({ request: req, snapshot })
+                        : undefined,
+                    onBudgetSignal: managedRuntime.onBudgetSignal,
+                });
+            }
+            turnMetrics = metrics
+                ? createTurnMetricsRecorder({
+                    sink: metrics,
+                    snapshot: managedTurn?.snapshot,
+                    startedAtMs: requestStart,
+                })
+                : undefined;
+            const buildDiscovery = async (registry, initialToolNames, handlerBuiltinNames) => {
+                if (!enableToolDiscovery)
+                    return undefined;
+                // Handler-created SDK built-ins stay active next to the searchable
+                // domain tools: clarification whenever configured, follow-ups when
+                // this turn's pipeline selected them. Registry-supplied tools sharing
+                // a built-in's name are never listed here and stay discoverable only
+                // through the manifest-checked index.
+                const builtinToolNames = handlerBuiltinNames.filter((name) => ALWAYS_ON_BUILTINS.includes(name) || initialToolNames.includes(name));
+                if (!managedTurn) {
+                    return createHybridToolDiscovery({
+                        discovery: createRegistryToolDiscovery({
+                            turnId,
+                            registry,
+                            excludeNames: NON_DOMAIN_TOOL_NAMES,
+                            semantics: toolSemantics,
+                        }),
+                        initialToolNames,
+                        builtinToolNames,
+                    });
+                }
+                const revocations = managedRuntime?.loadRevocations
+                    ? await managedRuntime.loadRevocations({
+                        request: req,
+                        snapshot: managedTurn.snapshot,
+                    })
+                    : [];
+                const revokedToolIds = managedTurn.snapshot.manifestRevision.tools
+                    .filter((tool) => isToolRevoked(managedTurn.snapshot, tool.toolId, revocations))
+                    .map((tool) => tool.toolId);
+                return createHybridToolDiscovery({
+                    discovery: createTurnToolDiscovery({
+                        snapshot: managedTurn.snapshot,
+                        registry,
+                        revokedToolIds,
+                        semantics: toolSemantics,
+                    }),
+                    initialToolNames,
+                    builtinToolNames,
+                });
+            };
             // Derive session ID — stable per conversation turn (groups approval flows)
-            const sessionId = (onAudit || piiShield || telemetry) ? deriveSessionId(messages) : '';
+            const sessionId = (onAudit || piiShield || telemetry) ? turnId : '';
             const toolOptions = {
                 uiActionSchema,
                 onError: onToolError,
@@ -388,12 +786,69 @@ export function createAiChatHandler(config) {
                 }
             }
             // ================================================================
+            // Direct command: no routing, no guardrails, no model call. The tool
+            // runs on the registry and wrappers of a model turn, so authorization,
+            // confirmation, revocation, budget, audit, the PII shield and metrics
+            // stay the same.
+            // ================================================================
+            if (directCommand) {
+                const callEndpoint = endpointCaller(req);
+                const endpointToolContext = {
+                    ...toolContext,
+                    callEndpoint,
+                    ...(managedTurn
+                        ? { turnSnapshot: managedTurn.snapshot }
+                        : {}),
+                    ...contractRejectionReporter(turnMetrics),
+                };
+                const registry = staticTools ?? await loadTools(endpointToolContext);
+                const commandScope = await requestApprovalScope(req, managedTurn);
+                const { binder: commandBinder, storeScope: commandStoreScope } = await secureApprovals(req, registry, [], managedTurn, commandScope);
+                let commandTools = toolsToAiTools(registry, endpointToolContext, toolOptions);
+                // The result stays in the chat history that later model turns send to the model.
+                if (piiShield) {
+                    commandTools = wrapToolsWithShield(commandTools, piiShield, sessionId);
+                }
+                if (lancer?.approvals) {
+                    commandTools = wrapToolsWithLancerApprovals(commandTools, lancer.approvals, sessionId);
+                }
+                return await runDirectCommand({
+                    command: directCommand,
+                    registry,
+                    tools: commandTools,
+                    managedTurn,
+                    turnMetrics,
+                    approvals: commandBinder,
+                    approvalStore,
+                    approvalScope: commandStoreScope,
+                    onError: (error) => onError?.(error, req),
+                });
+            }
+            // ================================================================
             // Pipeline mode
             // ================================================================
+            // The app's own input check runs first in both modes, without any model call.
+            let processedMessages = messages;
+            if (guardrails) {
+                const check = await guardrails(messages);
+                if (!check.ok) {
+                    return new Response(JSON.stringify({ error: check.reason ?? 'Invalid input' }), { status: 400, headers: { 'Content-Type': 'application/json' } });
+                }
+                if (check.sanitizedMessages) {
+                    processedMessages = check.sanitizedMessages;
+                }
+            }
             if (pipeline) {
                 // Create callEndpoint for endpoint tools (needed regardless of static/dynamic)
-                const callEndpoint = createInternalApiCallerFromRequest(req);
-                const endpointToolContext = { ...toolContext, callEndpoint };
+                const callEndpoint = endpointCaller(req);
+                const endpointToolContext = {
+                    ...toolContext,
+                    callEndpoint,
+                    ...(managedTurn
+                        ? { turnSnapshot: managedTurn.snapshot }
+                        : {}),
+                    ...contractRejectionReporter(turnMetrics),
+                };
                 // Get tools (static or dynamic)
                 let registry;
                 if (staticTools) {
@@ -403,21 +858,24 @@ export function createAiChatHandler(config) {
                     registry = await loadTools(endpointToolContext);
                 }
                 // Add followup tool if configured
-                if (followups) {
-                    const followupTool = createFollowupTool(followups);
-                    if (followupTool) {
-                        registry = { ...registry, [followupTool.id]: followupTool };
-                    }
+                const followupTool = followups ? createFollowupTool(followups) : null;
+                if (followupTool && !registry[followupTool.id]) {
+                    registry = { ...registry, [followupTool.id]: followupTool };
                 }
+                registry = withAlwaysOnBuiltins(registry);
+                const handlerBuiltinNames = findHandlerBuiltins(registry, [followupTool, clarificationTool, planTool]);
+                const pipelineApprovals = await secureApprovals(req, registry, processedMessages, managedTurn, await requestApprovalScope(req, managedTurn));
+                processedMessages = pipelineApprovals.messages;
                 // Extract user input for pipeline
-                let userText = extractLastUserText(messages);
+                let userText = clarificationResume?.routingText
+                    ?? extractLastUserText(processedMessages);
                 if (piiShield) {
                     userText = await piiShield.outbound(userText, sessionId);
                 }
                 // Build lightweight conversation history for intent classification.
                 // Include the last few user/assistant text exchanges (excluding the
                 // current message) so the classifier can understand follow-ups.
-                const conversationHistory = extractConversationHistory(messages, maxConversationHistoryPairs);
+                const conversationHistory = extractConversationHistory(processedMessages, maxConversationHistoryPairs);
                 // Run pipeline: guardrails + classification + routing + model selection
                 const pipelineResult = await pipeline.process(userText, toolContext, conversationHistory.length > 0 ? conversationHistory : undefined);
                 // Notify consumer about pipeline decision
@@ -465,21 +923,47 @@ export function createAiChatHandler(config) {
                         // Telemetry is fire-and-forget
                     }
                 }
+                const hasExplicitSelection = pipelineResult.toolSelection === 'explicit';
+                const initialToolNames = pipelineResult.blocked
+                    ? []
+                    : hasExplicitSelection || pipelineResult.tools.length > 0
+                        ? pipelineResult.tools
+                        : Object.keys(registry);
+                const discoveryController = pipelineResult.blocked
+                    ? undefined
+                    : await buildDiscovery(registry, initialToolNames, handlerBuiltinNames);
                 // Convert all tools to AI tools
                 let aiTools = await toolsToAiTools(registry, endpointToolContext, toolOptions);
+                const unscopedAiTools = aiTools;
                 // Scope tools to pipeline selection
                 if (pipelineResult.blocked) {
                     // Guardrails blocked — no tools allowed
                     aiTools = {};
                 }
-                else if (pipelineResult.tools.length > 0) {
-                    const scoped = {};
-                    for (const name of pipelineResult.tools) {
-                        if (aiTools[name])
-                            scoped[name] = aiTools[name];
+                else if (!discoveryController && (hasExplicitSelection || pipelineResult.tools.length > 0)) {
+                    aiTools = scopePipelineTools({
+                        aiTools,
+                        registryToolNames: new Set(Object.keys(registry)),
+                        selected: pipelineResult.tools,
+                        fallbackToAll: !hasExplicitSelection,
+                    });
+                    // Clarification and the plan stay callable, also for an empty
+                    // focused selection.
+                    aiTools = keepAlwaysOn(aiTools, unscopedAiTools);
+                }
+                // An approval verified (and consumed) above answers a call that an
+                // earlier request already routed. Routing for this request must not
+                // turn that approved call into a tool error, so its tool stays in the
+                // set (the AI SDK runs approved calls from `tools`, not `activeTools`).
+                // Only tools with a verified approval come back; a new call to one of
+                // them still needs its own approval. A guardrail block keeps no tools,
+                // so the approved call then ends as a tool error and is not run.
+                if (!pipelineResult.blocked) {
+                    for (const { toolName } of pipelineApprovals.verified) {
+                        const approvedTool = unscopedAiTools[toolName];
+                        if (approvedTool && !aiTools[toolName])
+                            aiTools = { ...aiTools, [toolName]: approvedTool };
                     }
-                    if (Object.keys(scoped).length > 0)
-                        aiTools = scoped;
                 }
                 // Resolve model — config callback > pipeline instance > error
                 let model;
@@ -493,6 +977,7 @@ export function createAiChatHandler(config) {
                     model = pipelineResult.model.instance;
                 }
                 else {
+                    turnMetrics?.finish({ status: 'error', errorCode: 'pipeline_error' });
                     return new Response(JSON.stringify({
                         error: 'No model configured. Provide model on handler config or as instance on ModelSelectorConfig.',
                     }), { status: 500, headers: { 'Content-Type': 'application/json' } });
@@ -502,6 +987,7 @@ export function createAiChatHandler(config) {
                     ? systemPromptConfig({
                         pipelineResult,
                         currentDate: new Date(),
+                        ...(managedTurn ? { turnSnapshot: managedTurn.snapshot } : {}),
                     })
                     : systemPromptConfig;
                 // Track the actual model ID used (may be overridden by Glirastes config)
@@ -541,10 +1027,11 @@ export function createAiChatHandler(config) {
                     moduleMaxSteps: pipelineResult.module?.executionDefaults?.maxSteps,
                     configuredMaxSteps,
                     safetyMaxSteps,
+                    runtimeBudgetMaxSteps: managedTurn?.snapshot.budget.maxModelSteps,
                 });
                 const contextWindow = pipelineResult.module?.executionDefaults?.contextWindow ??
                     maxContextMessages;
-                let recentMessages = messages.slice(-contextWindow);
+                let recentMessages = processedMessages.slice(-contextWindow);
                 // PII Shield: anonymize message history + wrap tools
                 if (piiShield) {
                     recentMessages = await anonymizeMessages(recentMessages, piiShield, sessionId);
@@ -554,13 +1041,16 @@ export function createAiChatHandler(config) {
                 if (lancer?.approvals) {
                     aiTools = wrapToolsWithLancerApprovals(aiTools, lancer.approvals, sessionId);
                 }
-                const pipelineStreamHandler = createStreamHandler((onAudit || telemetry) ? {
+                aiTools = gateTools(aiTools, pipelineApprovals.verified, managedTurn, handlerBuiltinNames);
+                const pipelineStreamHandler = createStreamHandler(req, (onAudit || telemetry) ? {
                     sessionId,
                     requestStart,
                     modelId: resolvedModelId,
                 } : undefined);
-                return pipelineStreamHandler({
-                    tools: aiTools,
+                return await pipelineStreamHandler({
+                    tools: discoveryController
+                        ? { ...aiTools, find_tools: discoveryController.tool }
+                        : aiTools,
                     messages: recentMessages,
                     systemPrompt,
                     model,
@@ -574,25 +1064,29 @@ export function createAiChatHandler(config) {
                     modelTier: pipelineResult.model.modelId,
                     pipelineResult,
                     piiShield: piiShield ? { shield: piiShield, sessionId } : undefined,
+                    managedTurn,
+                    turnMetrics,
+                    modelPricing,
+                    toolDiscovery: discoveryController,
+                    handlerBuiltinToolNames: discoveryController
+                        ? [...handlerBuiltinNames, 'find_tools']
+                        : handlerBuiltinNames,
+                    bindApprovalRequests: (stream) => bindApprovalRequests(stream, pipelineApprovals.binder),
                 });
             }
             // ================================================================
             // Legacy mode (without pipeline)
             // ================================================================
-            // Guardrails
-            let processedMessages = messages;
-            if (guardrails) {
-                const check = await guardrails(messages);
-                if (!check.ok) {
-                    return new Response(JSON.stringify({ error: check.reason ?? 'Invalid input' }), { status: 400, headers: { 'Content-Type': 'application/json' } });
-                }
-                if (check.sanitizedMessages) {
-                    processedMessages = check.sanitizedMessages;
-                }
-            }
             // Create callEndpoint for endpoint tools (needed regardless of static/dynamic)
-            const callEndpoint = createInternalApiCallerFromRequest(req);
-            const endpointToolContext = { ...toolContext, callEndpoint };
+            const callEndpoint = endpointCaller(req);
+            const endpointToolContext = {
+                ...toolContext,
+                callEndpoint,
+                ...(managedTurn
+                    ? { turnSnapshot: managedTurn.snapshot }
+                    : {}),
+                ...contractRejectionReporter(turnMetrics),
+            };
             // Load tools
             let registry;
             if (staticTools) {
@@ -601,7 +1095,12 @@ export function createAiChatHandler(config) {
             else {
                 registry = await loadTools(endpointToolContext);
             }
-            const allToolNames = Object.keys(registry);
+            registry = withAlwaysOnBuiltins(registry);
+            const handlerBuiltinNames = findHandlerBuiltins(registry, [clarificationTool, planTool]);
+            const legacyApprovals = await secureApprovals(req, registry, processedMessages, managedTurn, await requestApprovalScope(req, managedTurn));
+            processedMessages = legacyApprovals.messages;
+            const allToolNames = Object.keys(registry)
+                .filter((name) => !ALWAYS_ON_BUILTINS.includes(name));
             // PII Shield: anonymize for legacy mode
             const legacySessionId = piiShield ? deriveSessionId(processedMessages) : '';
             if (piiShield) {
@@ -611,7 +1110,8 @@ export function createAiChatHandler(config) {
             // Intent routing
             let routing;
             if (intentRouter) {
-                const text = extractLastUserText(processedMessages);
+                const text = clarificationResume?.routingText
+                    ?? extractLastUserText(processedMessages);
                 routing = await intentRouter(text, allToolNames);
             }
             // Convert to AI tools
@@ -623,11 +1123,19 @@ export function createAiChatHandler(config) {
                     if (aiTools[name])
                         scoped[name] = aiTools[name];
                 }
-                if (Object.keys(scoped).length > 0)
-                    aiTools = scoped;
+                if (Object.keys(scoped).length > 0) {
+                    aiTools = keepAlwaysOn(scoped, aiTools);
+                }
+            }
+            const discoveryController = await buildDiscovery(registry, routing?.toolNames?.length ? routing.toolNames : allToolNames, handlerBuiltinNames);
+            if (discoveryController) {
+                // Discovery needs the full eligible server-side set; `activeTools`
+                // preserves the intent router's fast initial scope.
+                aiTools = await toolsToAiTools(registry, endpointToolContext, toolOptions);
             }
             // Resolve model + system prompt (legacy mode — no pipeline fallback)
             if (!modelConfig) {
+                turnMetrics?.finish({ status: 'error', errorCode: 'pipeline_error' });
                 return new Response(JSON.stringify({
                     error: 'No model configured. In legacy mode (without pipeline), model is required.',
                 }), { status: 500, headers: { 'Content-Type': 'application/json' } });
@@ -639,11 +1147,13 @@ export function createAiChatHandler(config) {
                 ? systemPromptConfig({
                     routing,
                     currentDate: new Date(),
+                    ...(managedTurn ? { turnSnapshot: managedTurn.snapshot } : {}),
                 })
                 : systemPromptConfig;
             const stepLimit = resolveStepLimit({
                 configuredMaxSteps: routing?.maxSteps ?? configuredMaxSteps,
                 safetyMaxSteps,
+                runtimeBudgetMaxSteps: managedTurn?.snapshot.budget.maxModelSteps,
             });
             const contextWindow = routing?.contextWindow ?? maxContextMessages;
             let recentMessages = processedMessages.slice(-contextWindow);
@@ -656,13 +1166,16 @@ export function createAiChatHandler(config) {
             if (lancer?.approvals) {
                 aiTools = wrapToolsWithLancerApprovals(aiTools, lancer.approvals, legacySessionId || sessionId);
             }
-            const legacyStreamHandler = createStreamHandler((onAudit || telemetry) ? {
+            aiTools = gateTools(aiTools, legacyApprovals.verified, managedTurn, handlerBuiltinNames);
+            const legacyStreamHandler = createStreamHandler(req, (onAudit || telemetry) ? {
                 sessionId: legacySessionId || sessionId,
                 requestStart,
             } : undefined);
             // Delegate streaming to consumer's handler
-            return legacyStreamHandler({
-                tools: aiTools,
+            return await legacyStreamHandler({
+                tools: discoveryController
+                    ? { ...aiTools, find_tools: discoveryController.tool }
+                    : aiTools,
                 messages: recentMessages,
                 systemPrompt,
                 model,
@@ -676,10 +1189,26 @@ export function createAiChatHandler(config) {
                 modelTier: routing?.modelTier,
                 routing,
                 piiShield: piiShield ? { shield: piiShield, sessionId: legacySessionId } : undefined,
+                managedTurn,
+                turnMetrics,
+                modelPricing,
+                toolDiscovery: discoveryController,
+                handlerBuiltinToolNames: discoveryController
+                    ? [...handlerBuiltinNames, 'find_tools']
+                    : handlerBuiltinNames,
+                bindApprovalRequests: (stream) => bindApprovalRequests(stream, legacyApprovals.binder),
             });
         }
         catch (error) {
+            if (error instanceof ApprovalHistoryError) {
+                turnMetrics?.finish({ status: 'error', errorCode: 'pipeline_error' });
+                return approvalHistoryRefusal(error);
+            }
+            turnMetrics?.finish({ status: 'error', errorCode: 'pipeline_error' });
             onError?.(error, req);
+            if (error instanceof ApprovalSecretMissingError) {
+                return new Response(JSON.stringify({ error: error.code, message: error.message }), { status: 500, headers: { 'Content-Type': 'application/json' } });
+            }
             return new Response(JSON.stringify({ error: 'AI request failed' }), { status: 500, headers: { 'Content-Type': 'application/json' } });
         }
     }
@@ -688,6 +1217,14 @@ export function createAiChatHandler(config) {
     }
     return handler;
 }
+/**
+ * SDK built-ins whose tool instance the handler itself put into the registry.
+ * Instance identity decides, not the name: a registry- or manifest-supplied
+ * tool that shares a built-in's name is never listed and stays fully guarded.
+ */
+function findHandlerBuiltins(registry, created) {
+    return NON_DOMAIN_TOOL_NAMES.filter((name) => created.some((tool) => tool !== null && registry[name] === tool));
+}
 // ============================================================================
 // PII Shield Helpers
 // ============================================================================
@@ -700,7 +1237,10 @@ function deriveSessionId(messages) {
             return `ai-${msg.id}`;
         }
     }
-    return `ai-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    return `ai-${globalThis.crypto.randomUUID()}`;
+}
+function approvalHistoryRefusal(error) {
+    return new Response(JSON.stringify({ error: error.code, message: error.message }), { status: 400, headers: { 'Content-Type': 'application/json' } });
 }
 async function anonymizeMessages(messages, shield, sessionId) {
     const result = [];
@@ -710,9 +1250,10 @@ async function anonymizeMessages(messages, shield, sessionId) {
             continue;
         }
         const record = msg;
-        // Only anonymize user messages
+        // Only user messages carry text to anonymize; of the others, only the
+        // arguments of a direct command's tool call are the user's own words.
         if (record.role !== 'user') {
-            result.push(msg);
+            result.push(await pseudonymizeCommandToolInputs(record, shield, sessionId));
             continue;
         }
         // Anonymize string content
@@ -958,4 +1499,15 @@ function extractTextFromMessage(msg) {
     }
     return texts.join(' ');
 }
+/**
+ * The client actions the chat reported for the open page, or undefined when
+ * the report is missing or malformed (then client-action tools run as before).
+ */
+function readClientActions(value) {
+    if (!Array.isArray(value) || value.length > 500)
+        return undefined;
+    if (!value.every((id) => typeof id === 'string' && id.length > 0 && id.length <= 200))
+        return undefined;
+    return value;
+}
 //# sourceMappingURL=create-ai-chat-handler.js.map