@agent-native/core 0.222.0 → 0.222.1-nightly-20261029092708

package/dist/agent/production-agent.d.ts

@@ -279,6 +279,7 @@ export declare function isUnavailableActionEntry(entry: ActionEntry | undefined)
  */
 export declare function pinAdditionalActionsToTurn(resolved: Record<string, ActionEntry>, turnNames: readonly string[], registered: Record<string, ActionEntry>): Record<string, ActionEntry>;
 export declare function filterActionsByAllowedNames(actions: Record<string, ActionEntry>, allowedActionNames: readonly string[]): Record<string, ActionEntry>;
+export declare function filterActionsByExcludedNames(actions: Record<string, ActionEntry>, excludedActionNames: readonly string[]): Record<string, ActionEntry>;
 export declare const PLAN_MODE_SYSTEM_PROMPT = "## Plan Mode Active\n\nYou are in Plan mode. This turn is for research, clarification, and a proposed approach only.\n\nHard rules:\n- Use only read-only tools. Do not edit files, write resources, run mutating bash commands, mutate SQL rows, navigate the UI, send notifications, create jobs, create tools, send messages or tasks to external agents, or change external systems.\n- If a needed detail is unclear, ask a concise clarifying question before proposing a plan.\n- When ready, present a concrete plan with the files/tools you expect to touch, the intended changes, validation steps, and notable risks.\n- Plan mode covers only this message. End with the plan and do not carry it out; the user starts implementation with the Implement button or their next message.";
 export declare function isPlanModeToolCallAllowed(name: string, input: unknown, entry: ActionEntry): boolean;
 export declare function createPlanModeActionRegistry(actions: Record<string, ActionEntry>): Record<string, ActionEntry>;
@@ -791,6 +792,7 @@ export declare function createRunSafeBoundaryGuards(input: {
     beforeModelDispatch: BeforeModelDispatch;
     beforeWrite: () => Promise<void>;
 };
+export declare function trackExperimentExposureAtDispatch(beforeModelDispatch: BeforeModelDispatch, trackExposure: () => void): BeforeModelDispatch;
 export declare function confirmQueuedRunInterrupt(input: {
     abort: () => Promise<boolean>;
     defer: () => Promise<unknown>;

package/dist/agent/production-agent.js

@@ -33,7 +33,8 @@ import { isMcpActionResult } from "../mcp-client/app-result.js";
 import { extractMcpToolResultImages } from "../mcp-client/index.js";
 import { isMcpToolAllowedForRequest } from "../mcp-client/visibility.js";
 import { describeSettingsViewForAgent, SETTINGS_VIEW_STATE_KEY, } from "../navigation/settings-redirects.js";
-import { isHostedModelExperimentEnabled, resolveHostedModelExperiment, } from "../observability/hosted-model-experiment.js";
+import { isHostedModelExperimentEnabled, resolveHostedModelExperiment, singleNonHostedAssignment, } from "../observability/hosted-model-experiment.js";
+import { InvalidQuestionIntakeExperimentAssignmentError, resolveQuestionIntakeExperimentAssignment, treatmentInstructionsForQuestionIntake, } from "../observability/question-intake-experiment.js";
 import { isFirstPartyHostedAgentNative, shouldInferSentimentForTurn, } from "../observability/sentiment.js";
 import { parseServiceIdentityEmail } from "../org/service-identity.js";
 import { ServicePrincipalRefusedError } from "../org/service-principal-guard.js";
@@ -61,6 +62,7 @@ import { stripDiagnosticSnippets } from "../shared/diagnostic-snippet.js";
 import { DurableAttachmentReferenceRequiredError, stripInlineBytes, } from "../shared/inline-bytes.js";
 import { isReasoningEffort, normalizeReasoningEffortForRequest, stepDownReasoningEffort, } from "../shared/reasoning-effort.js";
 import { SYNTHETIC_TRAFFIC_BETA_E2E, SYNTHETIC_TRAFFIC_HEADER, } from "../shared/test-traffic.js";
+import { trackQuestionIntakeExposure } from "../tracking/index.js";
 import { actionPreparationContinuationNote } from "./action-continuation-guidance.js";
 import { agentErrorDetails } from "./action-error-details.js";
 import { drainAgentWarnings, formatAgentWarningsForToolResult, } from "./action-warnings.js";
@@ -901,6 +903,12 @@ export function filterActionsByAllowedNames(actions, allowedActionNames) {
     }
     return filtered;
 }
+export function filterActionsByExcludedNames(actions, excludedActionNames) {
+    if (excludedActionNames.length === 0)
+        return actions;
+    const excludedNames = new Set(excludedActionNames);
+    return Object.fromEntries(Object.entries(actions).filter(([name]) => !excludedNames.has(name)));
+}
 export const PLAN_MODE_SYSTEM_PROMPT = `## Plan Mode Active
 
 You are in Plan mode. This turn is for research, clarification, and a proposed approach only.
@@ -4996,6 +5004,16 @@ export function createRunSafeBoundaryGuards(input) {
         },
     };
 }
+export function trackExperimentExposureAtDispatch(beforeModelDispatch, trackExposure) {
+    let tracked = false;
+    return async (dispatch) => beforeModelDispatch(() => {
+        if (!tracked) {
+            tracked = true;
+            trackExposure();
+        }
+        return dispatch();
+    });
+}
 export async function confirmQueuedRunInterrupt(input) {
     if (await input.abort())
         return "aborted";
@@ -9646,7 +9664,7 @@ export function createProductionAgentHandler(options) {
             }
             filtered[name] = entry;
         }
-        return filtered;
+        return filterActionsByExcludedNames(filtered, getRequestRunContext()?.excludedActionNames ?? []);
     };
     const getEngineTools = (actions) => actionsToEngineTools(getRequestActions(actions));
     return defineEventHandler(async (event) => {
@@ -9970,6 +9988,40 @@ export function createProductionAgentHandler(options) {
         });
         const ownerEmail = await resolveAgentOwnerEmail(options, event);
         const runRequestContext = getRequestContext();
+        const questionIntakeConfig = getAppConfig().agent.questionIntake;
+        let questionIntakeAssignment = null;
+        try {
+            // raw-sql-ok: the assignment store binds the authenticated user ID as a query argument.
+            questionIntakeAssignment =
+                await resolveQuestionIntakeExperimentAssignment(questionIntakeConfig, runRequestContext?.agentRunAnonymous
+                    ? undefined
+                    : runRequestContext?.authUserId);
+        }
+        catch (error) {
+            const invalidAssignment = error instanceof InvalidQuestionIntakeExperimentAssignmentError
+                ? error
+                : null;
+            console.error(invalidAssignment
+                ? "[agent-chat] question-intake assignment is invalid"
+                : "[agent-chat] question-intake assignment lookup failed");
+            setResponseStatus(event, invalidAssignment ? 500 : 503);
+            return {
+                error: "The agent run failed.",
+                code: invalidAssignment?.code ?? "question_intake_assignment_unavailable",
+                retryable: invalidAssignment === null,
+            };
+        }
+        if (questionIntakeAssignment) {
+            const runContext = ensureRequestRunContext();
+            if (runContext) {
+                runContext.questionIntakeExperimentAssignment =
+                    questionIntakeAssignment;
+                runContext.excludedActionNames =
+                    questionIntakeAssignment.variantId === "no_questions"
+                        ? (questionIntakeConfig?.questionToolNames ?? [])
+                        : [];
+            }
+        }
         const turnInitiator = ownerEmail
             ? {
                 email: ownerEmail,
@@ -10858,7 +10910,15 @@ export function createProductionAgentHandler(options) {
         let effectiveModel = model;
         let modelSelectionSource = modelSelection.source;
         const turnUsageLabel = normalizeUsageLabel(body.usageLabel);
-        let experimentAssignments = [];
+        let experimentAssignments = questionIntakeAssignment
+            ? [
+                {
+                    experimentId: questionIntakeAssignment.experimentId,
+                    variantId: questionIntakeAssignment.variantId,
+                },
+            ]
+            : [];
+        let singularExperimentAssignment;
         try {
             // A pinned request model suppresses the experiment's model override, so
             // resolving would assign (and persist) a variant this turn never ran.
@@ -10873,7 +10933,11 @@ export function createProductionAgentHandler(options) {
                             : undefined,
                         assignments: expConfig.assignments,
                     });
-                    experimentAssignments = experimentSelection.assignments;
+                    singularExperimentAssignment = singleNonHostedAssignment(experimentSelection.assignments);
+                    experimentAssignments = [
+                        ...experimentAssignments,
+                        ...experimentSelection.assignments,
+                    ];
                     if (experimentSelection.model) {
                         effectiveModel = normalizeModelForEngine(engine, experimentSelection.model);
                         modelSelectionSource = "experiment";
@@ -11013,7 +11077,10 @@ export function createProductionAgentHandler(options) {
                 const built = typeof options.systemPrompt === "function"
                     ? await options.systemPrompt(event)
                     : options.systemPrompt;
-                return built;
+                const treatmentInstructions = treatmentInstructionsForQuestionIntake(questionIntakeConfig, questionIntakeAssignment);
+                return treatmentInstructions
+                    ? [built, treatmentInstructions].filter(Boolean).join("\n\n")
+                    : built;
             }
             catch (error) {
                 systemPromptError =
@@ -12254,6 +12321,7 @@ export function createProductionAgentHandler(options) {
         if (backgroundSetupDeadlineExceeded?.()) {
             return { ok: true, skipped: "setup-deadline" };
         }
+        // raw-sql-ok: run callback IDs and prompts reach static queries as bound arguments.
         const startedRun = startRun(runId, effectiveThreadId, async (rawSend, signal, control) => {
             if (backgroundSetupDeadlineExceeded?.())
                 return;
@@ -12327,11 +12395,22 @@ export function createProductionAgentHandler(options) {
                 }
                 return "none";
             };
-            const { beforeModelDispatch, beforeWrite } = createRunSafeBoundaryGuards({
+            const { beforeModelDispatch: guardedBeforeModelDispatch, beforeWrite } = createRunSafeBoundaryGuards({
                 signal,
                 flushEvents: control.flushEvents,
                 interruptRequestedAtBoundary: interruptQueuedRunAtBoundary,
             });
+            const exposureAssignment = questionIntakeAssignment && !internalContinuation && !continueOf
+                ? questionIntakeAssignment
+                : null;
+            const beforeModelDispatch = exposureAssignment
+                ? trackExperimentExposureAtDispatch(guardedBeforeModelDispatch, () => trackQuestionIntakeExposure(exposureAssignment, {
+                    appId: options.appId ?? "app",
+                    ...(threadId === undefined ? {} : { threadId }),
+                    turnId: effectiveTurnId,
+                    ...(ownerEmail ? { userId: ownerEmail } : {}),
+                }))
+                : guardedBeforeModelDispatch;
             if (selfChainBudget?.skipToBoundary) {
                 await recordRunDiagnostic(runId, RUN_DIAG_STAGE.workerSetupStep, `self_chain_budget_exhausted elapsed=${Date.now() - setupT0}ms`).catch(() => { });
                 send({ type: "auto_continue", reason: "run_timeout" });
@@ -12809,6 +12888,7 @@ export function createProductionAgentHandler(options) {
                                     : {}),
                             },
                             experimentAssignments,
+                            singularExperimentAssignment,
                             modelSelectionSource,
                             sentimentInput: shouldInferSentimentForTurn({
                                 internalContinuation: Boolean(internalContinuation),

package/dist/agent/run-store.js

@@ -1,6 +1,6 @@
 import { MAX_BACKGROUND_RUN_CONTINUATIONS, TURN_RUN_LEDGER_SLACK, } from "../app-config/run-lifecycle-invariants.js";
 import { isArtifactReceipt, } from "../artifacts/detect.js";
-import { getDbExec, getScopedTransactionDbExec } from "../db/client.js";
+import { getDbExec, getScopedDbExec, getScopedTransactionDbExec, } from "../db/client.js";
 import { ensureColumnExists, ensureIndexExists, ensureTableExists, } from "../db/ddl-guard.js";
 import { defineStore } from "../db/store-registry.js";
 import { fromMigrationEntries } from "../db/versioned-store-migrations.js";
@@ -1320,7 +1320,8 @@ function earlierTurnProjectionPendingSql() {
   )`;
 }
 export async function claimBackgroundRun(runId) {
-    await ensureRunTables();
+    if (getScopedDbExec() === undefined)
+        await ensureRunTables();
     const client = getDbExec();
     const { rowsAffected } = await client.execute({
         sql: `UPDATE agent_runs

package/dist/app-config/agent.d.ts

@@ -2,6 +2,15 @@ import { z } from "zod";
 export declare const agentConfig: z.ZodObject<{
     engine: z.ZodOptional<z.ZodString>;
     model: z.ZodOptional<z.ZodString>;
+    questionIntake: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        disabled: z.ZodDefault<z.ZodBoolean>;
+        experimentId: z.ZodString;
+        questionToolNames: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        treatmentInstructions: z.ZodString;
+        trackedEventNames: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        clientTrackedEventNames: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
     builtInEngines: z.ZodOptional<z.ZodArray<z.ZodString>>;
     buildEnginePackages: z.ZodOptional<z.ZodString>;
     mode: z.ZodOptional<z.ZodString>;

package/dist/app-config/agent.js

@@ -16,6 +16,37 @@ export const agentConfig = z.object({
         env: ["AGENT_MODEL"],
         doc: "Model the agent runs with, when the caller does not pass one.",
     }),
+    questionIntake: z
+        .object({
+        enabled: z
+            .boolean()
+            .default(false)
+            .meta({
+            env: ["AGENT_QUESTION_INTAKE_EXPERIMENT_ENABLED"],
+            doc: "Enable signup-time assignment and run-level question-intake experimentation for this app.",
+        }),
+        disabled: z
+            .boolean()
+            .default(false)
+            .meta({
+            env: ["AGENT_QUESTION_INTAKE_EXPERIMENT_DISABLED"],
+            doc: "Emergency switch that disables this app's question-intake experiment, including when enabled by app config.",
+        }),
+        experimentId: z.string().trim().min(1),
+        questionToolNames: z.array(z.string().trim().min(1)).default([]),
+        treatmentInstructions: z.string().trim().min(1),
+        trackedEventNames: z.array(z.string().trim().min(1)).default([]),
+        clientTrackedEventNames: z
+            .array(z.string().trim().min(1))
+            .default([])
+            .meta({
+            doc: "Client-originated event names allowed to receive experiment assignment metadata. Keep outcome events restricted to server-confirmed behavior.",
+        }),
+    })
+        .optional()
+        .meta({
+        doc: "App-specific settings for the reusable question-intake experiment. Only new users created while enabled receive an assignment.",
+    }),
     builtInEngines: z
         .array(z.string().min(1))
         .min(1)

package/dist/app-config/schema.d.ts

@@ -26,6 +26,15 @@ export declare const appConfigSchema: z.ZodObject<{
     agent: z.ZodPrefault<z.ZodObject<{
         engine: z.ZodOptional<z.ZodString>;
         model: z.ZodOptional<z.ZodString>;
+        questionIntake: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            disabled: z.ZodDefault<z.ZodBoolean>;
+            experimentId: z.ZodString;
+            questionToolNames: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            treatmentInstructions: z.ZodString;
+            trackedEventNames: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            clientTrackedEventNames: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
         builtInEngines: z.ZodOptional<z.ZodArray<z.ZodString>>;
         buildEnginePackages: z.ZodOptional<z.ZodString>;
         mode: z.ZodOptional<z.ZodString>;

package/dist/app-config/store.js

@@ -26,8 +26,29 @@ function mergeLayers(base, override) {
     }
     return result;
 }
-function resolve(envLayer) {
-    state.layers.env = envLayer;
+function resolve(envLayer, questionIntakeEnvironment) {
+    const nonEnvironmentConfig = LAYER_ORDER.filter((layer) => layer !== "env").reduce((merged, layer) => state.layers[layer]
+        ? mergeLayers(merged, state.layers[layer])
+        : merged, {});
+    const configuredAgent = nonEnvironmentConfig.agent;
+    const configuredQuestionIntake = isPlainObject(configuredAgent)
+        ? configuredAgent.questionIntake
+        : undefined;
+    const hasQuestionIntakeConfig = isPlainObject(configuredQuestionIntake) &&
+        typeof configuredQuestionIntake.experimentId === "string" &&
+        typeof configuredQuestionIntake.treatmentInstructions === "string";
+    const resolvedEnvLayer = mergeLayers({}, envLayer);
+    if (hasQuestionIntakeConfig &&
+        questionIntakeEnvironment?.enabled !== undefined) {
+        const agentLayer = isPlainObject(resolvedEnvLayer.agent)
+            ? resolvedEnvLayer.agent
+            : (resolvedEnvLayer.agent = {});
+        const questionIntakeLayer = isPlainObject(agentLayer.questionIntake)
+            ? agentLayer.questionIntake
+            : (agentLayer.questionIntake = {});
+        questionIntakeLayer.enabled = questionIntakeEnvironment.enabled;
+    }
+    state.layers.env = resolvedEnvLayer;
     let merged = {};
     for (const layer of LAYER_ORDER) {
         const value = state.layers[layer];
@@ -35,6 +56,20 @@ function resolve(envLayer) {
             merged = mergeLayers(merged, value);
     }
     const parsed = appConfigSchema.parse(merged);
+    if (questionIntakeEnvironment?.enabled !== undefined &&
+        parsed.agent.questionIntake) {
+        parsed.agent.questionIntake = {
+            ...parsed.agent.questionIntake,
+            enabled: questionIntakeEnvironment.enabled,
+        };
+    }
+    if (questionIntakeEnvironment?.disabled === true &&
+        parsed.agent.questionIntake) {
+        parsed.agent.questionIntake = {
+            ...parsed.agent.questionIntake,
+            disabled: true,
+        };
+    }
     assertRunLifecycleInvariants(parsed.agent);
     parsed.app = deriveAppIdentity(parsed.app);
     return parsed;
@@ -68,12 +103,20 @@ export function defineAppConfig(config) {
     return () => { };
 }
 export function getAppConfig() {
-    const envLayer = readEnvConfigLayer(appConfigSchema, readConfigEnvironment());
-    const signature = JSON.stringify(envLayer);
+    const environment = readConfigEnvironment();
+    const questionIntakeEnvironment = readEnvConfigLayer(appConfigSchema, {
+        AGENT_QUESTION_INTAKE_EXPERIMENT_ENABLED: environment.AGENT_QUESTION_INTAKE_EXPERIMENT_ENABLED,
+        AGENT_QUESTION_INTAKE_EXPERIMENT_DISABLED: environment.AGENT_QUESTION_INTAKE_EXPERIMENT_DISABLED,
+    }).agent?.questionIntake;
+    const environmentWithoutQuestionIntakeSwitches = { ...environment };
+    delete environmentWithoutQuestionIntakeSwitches.AGENT_QUESTION_INTAKE_EXPERIMENT_ENABLED;
+    delete environmentWithoutQuestionIntakeSwitches.AGENT_QUESTION_INTAKE_EXPERIMENT_DISABLED;
+    const envLayer = readEnvConfigLayer(appConfigSchema, environmentWithoutQuestionIntakeSwitches);
+    const signature = JSON.stringify({ envLayer, questionIntakeEnvironment });
     if (state.resolved && state.envSignature === signature)
         return state.resolved;
     state.envSignature = signature;
-    return (state.resolved = resolve(envLayer));
+    return (state.resolved = resolve(envLayer, questionIntakeEnvironment));
 }
 export function resetAppConfigForTests() {
     state.layers = {};

package/dist/collab/routes.d.ts

@@ -25,8 +25,8 @@ export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import
     ok: boolean;
 }>>;
 export declare const postCollabText: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     text?: undefined;
+    ok?: undefined;
     error: string;
 } | {
     error?: undefined;

package/dist/collab/struct-routes.d.ts

@@ -13,9 +13,9 @@ export declare const postCollabPatch: import("h3").EventHandlerWithFetch<import(
     ok: boolean;
 }>>;
 export declare const getCollabJson: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    data?: undefined;
     error: string;
     docId?: undefined;
+    data?: undefined;
 } | {
     error?: undefined;
     docId: string;

package/dist/file-upload/actions/upload-image.d.ts

@@ -33,10 +33,10 @@ declare const _default: import("../../action.js").ActionDefinition<{
     idempotencyKey: string;
     deleted: boolean;
 } | {
-    id?: undefined;
+    provider?: undefined;
     error: string;
     url?: undefined;
-    provider?: undefined;
+    id?: undefined;
     configured?: undefined;
 } | {
     error?: undefined;
@@ -45,9 +45,9 @@ declare const _default: import("../../action.js").ActionDefinition<{
     provider: string;
     configured?: undefined;
 } | {
-    id?: undefined;
-    url?: undefined;
     provider?: undefined;
+    url?: undefined;
+    id?: undefined;
     error: string;
     configured: boolean;
 }>;

package/dist/jobs/run-history.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import { currentExecutionFence, StaleExecutionFenceError, withFencedExecutionWrite, } from "../agent/execution-fence.js";
 import { resolveBackgroundRunHardTimeoutMs } from "../agent/run-manager.js";
-import { getDbExec } from "../db/client.js";
+import { getDbExec, getScopedDbExec, } from "../db/client.js";
 import { ensureColumnExists, ensureIndexExists, ensureTableExists, } from "../db/ddl-guard.js";
 import { defineStore } from "../db/store-registry.js";
 import { fromMigrationEntries } from "../db/versioned-store-migrations.js";
@@ -717,7 +717,8 @@ export async function finishAutomationRun(id, status, error, errorCode, options
     }
 }
 export async function attachAutomationRunThread(id, threadId, runId, options = {}) {
-    await ensureTable();
+    if (getScopedDbExec() === undefined)
+        await ensureTable();
     const fence = currentExecutionFence();
     if (fence && (fence.runId !== runId || fence.threadId !== threadId)) {
         throw new StaleExecutionFenceError(fence);

package/dist/observability/hosted-model-experiment.d.ts

@@ -60,4 +60,4 @@ export declare function hostedModelExperimentVariant(assignments: readonly Hoste
  * The singular experiment tags predate the hosted test. They keep naming only
  * the other experiment on a turn, so the hosted arm never changes them.
  */
-export declare function singleNonHostedAssignment(assignments: readonly HostedModelExperimentAssignment[] | undefined): HostedModelExperimentAssignment | undefined;
+export declare function singleNonHostedAssignment(assignments: readonly HostedModelExperimentAssignment[] | undefined, selectedAssignment?: HostedModelExperimentAssignment): HostedModelExperimentAssignment | undefined;

package/dist/observability/hosted-model-experiment.js

@@ -86,7 +86,13 @@ export function hostedModelExperimentVariant(assignments) {
  * The singular experiment tags predate the hosted test. They keep naming only
  * the other experiment on a turn, so the hosted arm never changes them.
  */
-export function singleNonHostedAssignment(assignments) {
+export function singleNonHostedAssignment(assignments, selectedAssignment) {
+    if (selectedAssignment &&
+        selectedAssignment.experimentId !== HOSTED_MODEL_EXPERIMENT_ID &&
+        assignments?.some((assignment) => assignment.experimentId === selectedAssignment.experimentId &&
+            assignment.variantId === selectedAssignment.variantId)) {
+        return selectedAssignment;
+    }
     const others = assignments?.filter((assignment) => assignment.experimentId !== HOSTED_MODEL_EXPERIMENT_ID);
     return others?.length === 1 ? others[0] : undefined;
 }

package/dist/observability/question-intake-experiment.d.ts

@@ -0,0 +1,34 @@
+export declare const QUESTION_INTAKE_CONTROL_VARIANT: "control";
+export declare const QUESTION_INTAKE_TREATMENT_VARIANT: "no_questions";
+export interface QuestionIntakeExperimentConfig {
+    enabled: boolean;
+    disabled?: boolean;
+    experimentId: string;
+    questionToolNames: string[];
+    treatmentInstructions: string;
+    trackedEventNames: string[];
+    clientTrackedEventNames?: string[];
+}
+export interface QuestionIntakeExperimentAssignment {
+    authUserId: string;
+    experimentId: string;
+    variantId: typeof QUESTION_INTAKE_CONTROL_VARIANT | typeof QUESTION_INTAKE_TREATMENT_VARIANT;
+}
+export declare function questionIntakeExposureProperties(assignment: QuestionIntakeExperimentAssignment, context: {
+    appId: string;
+    threadId?: string;
+    turnId: string;
+}): Record<string, string>;
+export declare class QuestionIntakeAssignmentError extends Error {
+    readonly code = "question_intake_assignment_failed";
+    constructor(experimentId: string, cause: unknown);
+}
+export declare class InvalidQuestionIntakeExperimentAssignmentError extends Error {
+    readonly code = "question_intake_assignment_invalid";
+    constructor(experimentId: string);
+}
+export declare function treatmentInstructionsForQuestionIntake(config: QuestionIntakeExperimentConfig | undefined, assignment: QuestionIntakeExperimentAssignment | null): string | undefined;
+/** Assigns only from the user-create hook while the app config is enabled. */
+export declare function assignQuestionIntakeExperimentOnSignup(config: QuestionIntakeExperimentConfig | undefined, authUserId: string | undefined): Promise<QuestionIntakeExperimentAssignment | null>;
+/** Reads an existing signup assignment; agent runs never enroll older users. */
+export declare function resolveQuestionIntakeExperimentAssignment(config: QuestionIntakeExperimentConfig | undefined, authUserId: string | undefined): Promise<QuestionIntakeExperimentAssignment | null>;

package/dist/observability/question-intake-experiment.js

@@ -0,0 +1,114 @@
+import { createHash } from "node:crypto";
+import { getAssignment, upsertAssignment } from "./store.js";
+export const QUESTION_INTAKE_CONTROL_VARIANT = "control";
+export const QUESTION_INTAKE_TREATMENT_VARIANT = "no_questions";
+export function questionIntakeExposureProperties(assignment, context) {
+    return {
+        experiment_id: assignment.experimentId,
+        experiment_variant: assignment.variantId,
+        exposure_surface: "agent_run",
+        app_id: context.appId,
+        templateId: context.appId,
+        agent_native_app: context.appId,
+        ...(context.threadId ? { thread_id: context.threadId } : {}),
+        turn_id: context.turnId,
+    };
+}
+export class QuestionIntakeAssignmentError extends Error {
+    code = "question_intake_assignment_failed";
+    constructor(experimentId, cause) {
+        super(`Question-intake assignment failed after retry for ${experimentId}.`, { cause });
+        this.name = "QuestionIntakeAssignmentError";
+    }
+}
+export class InvalidQuestionIntakeExperimentAssignmentError extends Error {
+    code = "question_intake_assignment_invalid";
+    constructor(experimentId) {
+        super(`Question-intake assignment has an invalid stored variant for ${experimentId}.`);
+        this.name = "InvalidQuestionIntakeExperimentAssignmentError";
+    }
+}
+export function treatmentInstructionsForQuestionIntake(config, assignment) {
+    if (!configured(config) ||
+        assignment?.experimentId !== config.experimentId ||
+        assignment.variantId !== QUESTION_INTAKE_TREATMENT_VARIANT) {
+        return undefined;
+    }
+    return [
+        "For this assigned experiment treatment, the instructions below override conflicting intake-question directives in the app prompt or the user's current message, including app-injected directives.",
+        config.treatmentInstructions.trim(),
+    ].join("\n");
+}
+function configured(config) {
+    return Boolean(config?.enabled &&
+        !config.disabled &&
+        config.experimentId.trim() &&
+        config.questionToolNames.length > 0 &&
+        config.treatmentInstructions.trim());
+}
+function variantForUser(experimentId, authUserId) {
+    const bucket = createHash("sha256")
+        .update(`${experimentId}\0${authUserId}`)
+        .digest()
+        .readUInt8(0);
+    return bucket < 128
+        ? QUESTION_INTAKE_CONTROL_VARIANT
+        : QUESTION_INTAKE_TREATMENT_VARIANT;
+}
+function assignmentFromStored(config, authUserId, variantId) {
+    if (variantId !== QUESTION_INTAKE_CONTROL_VARIANT &&
+        variantId !== QUESTION_INTAKE_TREATMENT_VARIANT) {
+        throw new InvalidQuestionIntakeExperimentAssignmentError(config.experimentId);
+    }
+    return { authUserId, experimentId: config.experimentId, variantId };
+}
+/** Assigns only from the user-create hook while the app config is enabled. */
+// raw-sql-ok: authUserId is persisted only through the assignment store's bound arguments.
+export async function assignQuestionIntakeExperimentOnSignup(config, authUserId) {
+    if (!configured(config) || !authUserId?.trim())
+        return null;
+    const assign = async () => {
+        // raw-sql-ok: the assignment store binds the experiment and user IDs as query arguments.
+        const existing = await getAssignment(config.experimentId, authUserId);
+        if (existing) {
+            return assignmentFromStored(config, authUserId, existing.variantId);
+        }
+        const variantId = variantForUser(config.experimentId, authUserId);
+        await upsertAssignment({
+            experimentId: config.experimentId,
+            userId: authUserId,
+            variantId,
+            assignedAt: Date.now(),
+        });
+        return { authUserId, experimentId: config.experimentId, variantId };
+    };
+    try {
+        return await assign();
+    }
+    catch (firstError) {
+        if (firstError instanceof InvalidQuestionIntakeExperimentAssignmentError) {
+            throw firstError;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        try {
+            return await assign();
+        }
+        catch (retryError) {
+            if (retryError instanceof InvalidQuestionIntakeExperimentAssignmentError) {
+                throw retryError;
+            }
+            throw new QuestionIntakeAssignmentError(config.experimentId, new AggregateError([firstError, retryError], "Question-intake assignment failed twice."));
+        }
+    }
+}
+/** Reads an existing signup assignment; agent runs never enroll older users. */
+// raw-sql-ok: authUserId is read only through the assignment store's bound arguments.
+export async function resolveQuestionIntakeExperimentAssignment(config, authUserId) {
+    if (!configured(config) || !authUserId?.trim())
+        return null;
+    // raw-sql-ok: the assignment store binds the experiment and user IDs as query arguments.
+    const existing = await getAssignment(config.experimentId, authUserId);
+    if (!existing)
+        return null;
+    return assignmentFromStored(config, authUserId, existing.variantId);
+}

package/dist/observability/traces.d.ts

@@ -49,6 +49,10 @@ export declare function instrumentAgentLoop(opts: {
         experimentId: string;
         variantId: string;
     }>;
+    singularExperimentAssignment?: {
+        experimentId: string;
+        variantId: string;
+    };
     modelSelectionSource?: string;
     delegation?: {
         protocol: "a2a" | "mcp" | "agent-team";

package/dist/observability/traces.js

@@ -311,7 +311,7 @@ function emitLlmGenerationTrackingEvent(args) {
         properties.experiment_variants = args.experimentAssignments
             .map((assignment) => assignment.variantId)
             .join(",");
-        const singular = singleNonHostedAssignment(args.experimentAssignments);
+        const singular = singleNonHostedAssignment(args.experimentAssignments, args.singularExperimentAssignment);
         if (singular) {
             properties.experiment_id = singular.experimentId;
             properties.experiment_variant = singular.variantId;
@@ -404,6 +404,7 @@ export async function instrumentAgentLoop(opts) {
             .catch(() => null)
         : Promise.resolve(null);
     const browserSessionId = opts.browserSessionId ?? getRequestContext()?.browserSessionId;
+    const singularExperimentAssignment = singleNonHostedAssignment(opts.experimentAssignments, opts.singularExperimentAssignment);
     const otelRunSpanPromise = startAgentSpan("invoke_agent", {
         "gen_ai.operation.name": "invoke_agent",
         "gen_ai.provider.name": engineName,
@@ -412,9 +413,8 @@ export async function instrumentAgentLoop(opts) {
         "agent.run_id": runId,
         "agent.user_id": userId ?? undefined,
         "agent.model_selection_source": opts.modelSelectionSource,
-        "agent.experiment_id": singleNonHostedAssignment(opts.experimentAssignments)
-            ?.experimentId,
-        "agent.experiment_variant": singleNonHostedAssignment(opts.experimentAssignments)?.variantId,
+        "agent.experiment_id": singularExperimentAssignment?.experimentId,
+        "agent.experiment_variant": singularExperimentAssignment?.variantId,
         "agent.hosted_model_experiment_variant": hostedModelExperimentVariant(opts.experimentAssignments),
     });
     let otelRunSpan = null;
@@ -1265,6 +1265,7 @@ export async function instrumentAgentLoop(opts) {
                         createdAt: generation.createdAt,
                         endedAt: generation.endedAt,
                         experimentAssignments: opts.experimentAssignments,
+                        singularExperimentAssignment: opts.singularExperimentAssignment,
                         modelSelectionSource: opts.modelSelectionSource,
                         browserSessionId,
                         ...generationContent,