@indexnetwork/protocol 13.2.1-rc.467.1 → 14.1.0-rc.469.1

package/dist/chat/chat.prompt.modules.js

@@ -1,4 +1,3 @@
-import { focusedIntentId } from "../shared/agent/tool.scope.js";
 // ═══════════════════════════════════════════════════════════════════════════════
 // EXTRACTION
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -7,7 +6,7 @@ import { focusedIntentId } from "../shared/agent/tool.scope.js";
  *
  * Scans backwards to find the last HumanMessage, then collects all tool calls
  * from AIMessages after that point. This ensures multi-iteration tool history
- * is available for module resolution within a single user turn.
+ * is available for prompt construction within a single user turn.
  *
  * @param messages - The current conversation message array
  * @returns Flattened array of tool name + args from the current agent turn
@@ -39,236 +38,3 @@ export function extractRecentToolCalls(messages) {
     }
     return toolCalls;
 }
-// ═══════════════════════════════════════════════════════════════════════════════
-// HELPERS
-// ═══════════════════════════════════════════════════════════════════════════════
-/**
- * Checks whether recent tool calls include discover_opportunities with
- * introduction-specific arguments (partyUserIds or introTargetUserId).
- */
-function hasIntroductionArgs(recentTools) {
-    return recentTools.some((t) => t.name === "discover_opportunities" &&
-        (t.args.partyUserIds || t.args.introTargetUserId));
-}
-// ═══════════════════════════════════════════════════════════════════════════════
-// MODULE DEFINITIONS
-// ═══════════════════════════════════════════════════════════════════════════════
-const intentCreationModule = {
-    id: "intent-creation",
-    triggers: ["create_intent"],
-    content: () => `
-### 2. User explicitly wants to create or save an intent
-
-**YOU decide if it's specific enough. The tool proposes — the user confirms.**
-
-\`\`\`
-IF description is vague ("find a job", "meet people", "learn something"):
-  1. read_user_contexts()           → get their background
-  2. read_intents()                 → see existing intents for context
-  3. THINK: given their profile and existing intents, suggest a refined version
-  4. Reply: "Based on your background in X, did you mean something like 'Y'?"
-  5. Wait for confirmation
-  6. On "yes" → create_intent(description=exact_refined_text)
-
-IF description is specific enough ("contribute to an open-source LLM project"):
-  → create_intent(description=...) directly
-\`\`\`
-
-**CRITICAL: Never write a \`\`\`intent_proposal block yourself.** To propose an intent you MUST call create_intent(description=...). The tool returns a \`\`\`intent_proposal code block (with proposalId and description). You MUST include that exact block verbatim in your response — it renders as an interactive card. Do not summarize or invent the block; only the tool provides a valid one. Add a brief explanation that creating this intent will let the system look for relevant people in the background.
-
-Specificity test: Does it contain a concrete domain, action, or scope? If just a single generic verb+noun ("find a job"), it's vague. If it has qualifying detail ("senior UX design role at a tech company in Berlin"), it's specific.
-`,
-};
-const intentManagementModule = {
-    id: "intent-management",
-    triggers: ["update_intent", "delete_intent"],
-    content: () => `
-### 4. Update or delete an intent
-
-**YOU look up the ID first.**
-
-\`\`\`
-1. read_intents() → get current intents with IDs
-2. Match user's request to the right intent
-3. update_intent(intentId=exact_id, description=...) or delete_intent(intentId=exact_id)
-\`\`\`
-`,
-};
-const personLookupModule = {
-    id: "person-lookup",
-    triggers: ["read_user_contexts"],
-    content: () => `
-### 0. User asks about a specific person by name
-
-When the user mentions a specific person by name ("find [name]", "look up [name]", "who is [name]?", "tell me about [name]"), look them up by name first — do NOT use discovery.
-
-- Call \`read_user_contexts(query="the name")\` — this finds members by name across the user's indexes
-- If one match: the result already includes their full profile; present it naturally
-- If multiple matches: present the list and ask the user to clarify which person
-- If no matches: tell the user you couldn't find anyone by that name in their network
-- If the user then asks for semantic discovery (e.g. "find people like them"), use Pattern 1.
-- If the user wants to connect with this specific person (e.g. "yes, connect us", "what can I do with them", "I'd like to reach out"), use Pattern 1a.
-`,
-};
-const urlScrapingModule = {
-    id: "url-scraping",
-    triggers: ["scrape_url"],
-    regex: /(https?:\/\/)/i,
-    content: (ctx) => `
-### 3. User includes a URL
-
-**YOU handle scraping before ${focusedIntentId(ctx) ? "updating the selected intent" : "intent creation"}.**
-
-\`\`\`
-1. scrape_url(url, objective="Extract key details for an intent")
-2. Synthesize a conceptual description from scraped content
-3. ${focusedIntentId(ctx) ? `update_intent(intentId="${focusedIntentId(ctx)}", description=synthesized_summary)` : "create_intent(description=synthesized_summary)"}
-\`\`\`
-
-Exception: for profile creation, pass URLs directly to create_user_context (it handles scraping internally).
-
-If the user pastes or types a profile URL (e.g. linkedin.com/..., github.com/...) to create or update their profile, you MUST pass that exact URL in the corresponding parameter (e.g. linkedinUrl, githubUrl, twitterUrl) to create_user_context, or use scrape_url with that URL then update_user_context; do not use the user's stored social links for that request.
-`,
-};
-const communityModule = {
-    id: "community",
-    triggers: ["read_networks", "create_network", "create_network_membership", "update_network", "delete_network", "delete_network_membership"],
-    content: () => `
-### 8. Explore what a community is about
-
-\`\`\`
-0. If user asks about communities they belong to, first use preloaded memberships in this prompt.
-1. read_networks() → get network details (title, prompt)
-2. read_intents(networkId=X) → what members are looking for
-3. read_network_memberships(networkId=X) → who's in it
-4. Synthesize: community purpose, active needs, member composition
-\`\`\`
-
-### When to mention community/index
-Index and community membership is background: handle it without talking about indexes unless the user asks or it's sign-up, leave, or owner settings. Do not proactively mention "your indexes", "your communities", "which index", "in your current communities", or similar. Only mention indexes (or communities, lists) when: (i) post-onboarding sign-up to a community, (ii) user explicitly asked about their indexes/communities, (iii) user wants to leave one, (iv) owner is changing index/community settings. Otherwise use neutral language ("where you're connected", "people you're connected with") and do not narrate "your indexes", "your current communities", "in this network", etc.
-`,
-};
-const contactsModule = {
-    id: "contacts",
-    triggers: ["import_gmail_contacts", "add_contact", "list_contacts", "remove_contact"],
-    // Gate on the CONTACTS_ENABLED flag (fail-closed: only `true` enables). When
-    // contacts are disabled the import/add tools are de-registered, so this module
-    // must not be injected — otherwise the orchestrator keeps advertising Gmail
-    // import / add_contact and offers an action that then fails as "Unknown tool".
-    triggerFilter: (iterCtx) => iterCtx.ctx.contactsEnabled === true,
-    content: () => `
-### 9. Import contacts from Gmail
-
-**Single-step workflow:**
-
-\`\`\`
-import_gmail_contacts()
-→ If not connected: returns { requiresAuth: true, authUrl: "..." } — share the URL with the user
-→ If connected: imports contacts directly and returns stats { imported, skipped, newContacts, existingContacts }
-\`\`\`
-
-Ghost users are contacts without accounts — they're enriched with public data (LinkedIn, GitHub, X) and can appear in opportunity discovery once enriched.
-
-### 10. Add or manage contacts manually
-
-\`\`\`
-# Add a single contact
-add_contact(email="alice@example.com", name="Alice Smith")
-
-# List user's network
-list_contacts() → returns contacts with names, emails, and whether they're ghost users
-
-# Remove a contact
-remove_contact(contactId=X)
-\`\`\`
-`,
-};
-const sharedContextModule = {
-    id: "shared-context",
-    triggers: ["read_network_memberships"],
-    content: () => `
-### 5. Find shared context between two users
-
-\`\`\`
-1. read_network_memberships(userId=me)     → my networks
-2. read_network_memberships(userId=other)  → their networks
-3. Intersect networkIds
-4. For each shared network: read_intents(networkId=shared)
-5. read_user_contexts(userId=other)
-6. Synthesize: what overlaps, where they could collaborate
-\`\`\`
-`,
-};
-const mentionsModule = {
-    id: "mentions",
-    triggers: [],
-    regex: /@\[.*?\]\(.*?\)/,
-    content: () => `- Messages may contain \`@[Display Name](userId)\` markup. The value in parentheses is the userId.
-`,
-};
-// ═══════════════════════════════════════════════════════════════════════════════
-// MODULE REGISTRY
-// ═══════════════════════════════════════════════════════════════════════════════
-/** All registered prompt modules. */
-export const PROMPT_MODULES = [
-    intentCreationModule,
-    intentManagementModule,
-    personLookupModule,
-    urlScrapingModule,
-    communityModule,
-    contactsModule,
-    sharedContextModule,
-    mentionsModule,
-];
-// ═══════════════════════════════════════════════════════════════════════════════
-// RESOLUTION
-// ═══════════════════════════════════════════════════════════════════════════════
-/**
- * Resolves which prompt modules should be injected for the current iteration.
- *
- * Phase 1: Skip all modules when onboarding is active (early exit).
- * Phase 2: Collect candidate modules by checking triggers and regex.
- * Phase 3: Apply exclusions (unidirectional — the excluding module stays).
- *
- * @param iterCtx - Current iteration context (tool history, user message, resolved context)
- * @returns Concatenated prompt text from all matched modules
- */
-export function resolveModules(iterCtx) {
-    // Phase 1 (early exit): Skip all modules during onboarding
-    if (iterCtx.ctx.isOnboarding) {
-        return "";
-    }
-    const toolNames = new Set(iterCtx.recentTools.map((t) => t.name));
-    // Phase 2: Collect candidates
-    const candidates = new Map();
-    for (const mod of PROMPT_MODULES) {
-        let matched = false;
-        // Check tool triggers (with optional filter for arg-based disambiguation)
-        if (mod.triggers.length > 0 && mod.triggers.some((t) => toolNames.has(t))) {
-            matched = mod.triggerFilter ? mod.triggerFilter(iterCtx) : true;
-        }
-        // Check regex trigger
-        if (!matched && mod.regex && iterCtx.currentMessage && mod.regex.test(iterCtx.currentMessage)) {
-            matched = true;
-        }
-        if (matched) {
-            candidates.set(mod.id, mod);
-        }
-    }
-    // Phase 3: Apply exclusions (skip self-exclusion)
-    for (const mod of candidates.values()) {
-        if (mod.excludes) {
-            for (const excludedId of mod.excludes) {
-                if (excludedId !== mod.id) {
-                    candidates.delete(excludedId);
-                }
-            }
-        }
-    }
-    // Build output
-    const sections = [];
-    for (const mod of candidates.values()) {
-        sections.push(mod.content(iterCtx.ctx));
-    }
-    return sections.join("\n");
-}

package/dist/chat/chat.streamer.js

@@ -1,6 +1,6 @@
 import { AIMessage, HumanMessage } from "@langchain/core/messages";
 import { protocolLogger } from "../shared/observability/protocol.logger.js";
-import { createAgentEndEvent, createAgentStartEvent, createDebugMetaEvent, createDecisionQuestionsEvent, createErrorEvent, createGraphEndEvent, createPhaseStartEvent, createPhaseEndEvent, createGraphStartEvent, createIterationStartEvent, createLlmStartEvent, createLlmEndEvent, createResponseCompleteEvent, createResponseResetEvent, createHallucinationDetectedEvent, createStatusEvent, createTokenEvent, createToolActivityEvent, createChatSummarizerStartEvent, createChatSummarizerEndEvent, createQuestionGeneratorStartEvent, createQuestionGeneratorEndEvent, createUserQuestionEvent } from "./chat-streaming.types.js";
+import { createAgentEndEvent, createAgentStartEvent, createDebugMetaEvent, createDecisionQuestionsEvent, createErrorEvent, createGraphEndEvent, createPhaseStartEvent, createPhaseEndEvent, createGraphStartEvent, createIterationStartEvent, createLlmStartEvent, createLlmEndEvent, createResponseCompleteEvent, createResponseResetEvent, createHallucinationDetectedEvent, createStatusEvent, createTokenEvent, createToolActivityEvent, createChatSummarizerStartEvent, createChatSummarizerEndEvent, createUserQuestionEvent } from "./chat-streaming.types.js";
 const logger = protocolLogger("ChatStreamer");
 // ══════════════════════════════════════════════════════════════════════════════
 // CHAT STREAMER (Streaming Narration Architecture)
@@ -176,12 +176,6 @@ export class ChatStreamer {
                     if (event.type === "chat_summarizer_end") {
                         yield createChatSummarizerEndEvent(sessionId, event.payload);
                     }
-                    if (event.type === "question_generator_start") {
-                        yield createQuestionGeneratorStartEvent(sessionId, event.payload);
-                    }
-                    if (event.type === "question_generator_end") {
-                        yield createQuestionGeneratorEndEvent(sessionId, event.payload);
-                    }
                 }
                 // ─────────────────────────────────────────────────────────────────
                 // UPDATES: final state from agentLoopNode
@@ -206,7 +200,7 @@ export class ChatStreamer {
                     if (debugMeta?.graph != null &&
                         typeof debugMeta.iterations === "number") {
                         const llmFallback = { calls: 0, totalDurationMs: 0, resets: [], hallucinations: [] };
-                        yield createDebugMetaEvent(sessionId, debugMeta.graph, debugMeta.iterations, Array.isArray(debugMeta.tools) ? debugMeta.tools : [], debugMeta.llm ?? llmFallback, debugMeta.orchestratorNegotiations, debugMeta.discoveryQuestions);
+                        yield createDebugMetaEvent(sessionId, debugMeta.graph, debugMeta.iterations, Array.isArray(debugMeta.tools) ? debugMeta.tools : [], debugMeta.llm ?? llmFallback, debugMeta.orchestratorNegotiations);
                     }
                     logger.verbose("Agent loop complete (updates)", {
                         responseLength: responseText.length,

package/dist/index.d.ts

@@ -34,7 +34,7 @@ export type { NetworkAssignmentMetadata } from "./shared/schemas/network-assignm
 export { DEFAULT_NETWORK_ASSIGNMENT_THRESHOLD, resolveAssignmentNetworkScope, buildNetworkAssignmentDecision } from "./shared/assignment/network-assignment.policy.js";
 export { buildCandidateEvidence } from "./capabilities/opportunities.facade.js";
 export { ChatGraphFactory } from "./capabilities/participant-agents.facade.js";
-export { ORCHESTRATOR_PERSONA_ID, type ChatPersonaConfig } from "./capabilities/participant-agents.facade.js";
+export { type ChatPersonaConfig } from "./capabilities/participant-agents.facade.js";
 export { NEGOTIATOR_PERSONA_ID, createNegotiatorPersona } from "./capabilities/participant-agents.facade.js";
 export { SIGNAL_PERSONA_ID, SIGNAL_PERSONA, SIGNAL_NEW_SIGNAL_KICKOFF, SIGNAL_TOOL_NAMES, createSignalTools, filterSignalTools, narrowSignalTools, } from "./capabilities/participant-agents.facade.js";
 export { REPORTER_PERSONA_ID, REPORTER_PERSONA, REPORTER_BRIEFING_KICKOFF, REPORTER_TOOL_NAMES, createReporterTools, filterReporterTools, narrowReporterTools, } from "./capabilities/participant-agents.facade.js";
@@ -82,7 +82,7 @@ export type { NegotiatorMemoryEntry } from "./capabilities/negotiation.facade.js
 export { QuestionerAgent } from "./capabilities/questions.facade.js";
 export { isValidQuestionerInputContract } from "./capabilities/questions.facade.js";
 export type { QuestionerInput, RecoveryQuestionerInput, UptakeQuestionerInput, PostStallQuestionerInput, InflightQuestionerInput, QuestionerEnqueuePayload, QuestionerEnqueueFn, PoolDiscoveryContext } from "./capabilities/questions.facade.js";
-export { isQuestionerEnabled, isUptakeGuardEnabled, uptakeAuthorityThreshold } from "./capabilities/questions.facade.js";
+export { isQuestionerEnabled, isUptakeGuardEnabled, uptakeAuthorityThreshold, intentQuestionDailyCap, INTENT_QUESTION_DAILY_CAP_DEFAULT, INTENT_QUESTION_DAILY_WINDOW_HOURS } from "./capabilities/questions.facade.js";
 export { PoolDiscriminatorMiner } from "./capabilities/opportunities.facade.js";
 export { PoolDiscriminatorAssigner } from "./capabilities/opportunities.facade.js";
 export type { PoolDiscriminatorAssignmentInput, PoolDiscriminatorAssignedAxis } from "./capabilities/opportunities.facade.js";

package/dist/index.js

@@ -30,7 +30,6 @@ export { DEFAULT_NETWORK_ASSIGNMENT_THRESHOLD, resolveAssignmentNetworkScope, bu
 export { buildCandidateEvidence } from "./capabilities/opportunities.facade.js";
 // ─── Graph factories ──────────────────────────────────────────────────────────
 export { ChatGraphFactory } from "./capabilities/participant-agents.facade.js";
-export { ORCHESTRATOR_PERSONA_ID } from "./capabilities/participant-agents.facade.js";
 export { NEGOTIATOR_PERSONA_ID, createNegotiatorPersona } from "./capabilities/participant-agents.facade.js";
 export { SIGNAL_PERSONA_ID, SIGNAL_PERSONA, SIGNAL_NEW_SIGNAL_KICKOFF, SIGNAL_TOOL_NAMES, createSignalTools, filterSignalTools, narrowSignalTools, } from "./capabilities/participant-agents.facade.js";
 export { REPORTER_PERSONA_ID, REPORTER_PERSONA, REPORTER_BRIEFING_KICKOFF, REPORTER_TOOL_NAMES, createReporterTools, filterReporterTools, narrowReporterTools, } from "./capabilities/participant-agents.facade.js";
@@ -68,7 +67,7 @@ export { NegotiationScreener } from "./capabilities/negotiation.facade.js";
 export { NegotiationReflector } from "./capabilities/negotiation.facade.js";
 export { QuestionerAgent } from "./capabilities/questions.facade.js";
 export { isValidQuestionerInputContract } from "./capabilities/questions.facade.js";
-export { isQuestionerEnabled, isUptakeGuardEnabled, uptakeAuthorityThreshold } from "./capabilities/questions.facade.js";
+export { isQuestionerEnabled, isUptakeGuardEnabled, uptakeAuthorityThreshold, intentQuestionDailyCap, INTENT_QUESTION_DAILY_CAP_DEFAULT, INTENT_QUESTION_DAILY_WINDOW_HOURS } from "./capabilities/questions.facade.js";
 export { PoolDiscriminatorMiner } from "./capabilities/opportunities.facade.js";
 export { PoolDiscriminatorAssigner } from "./capabilities/opportunities.facade.js";
 export { runPoolDiscriminatorShadow } from "./capabilities/opportunities.facade.js";

package/dist/participant-agents/public/index.d.ts

@@ -17,7 +17,7 @@
  * The following are application-internal or runtime-owned:
  * - ChatGraphFactory, ChatPersonaConfig, ChatPersona — runtime graph wiring;
  *   consumers should import via capabilities/participant-agents.facade.ts.
- * - Persona constants (ORCHESTRATOR_PERSONA_ID, SIGNAL_PERSONA, etc.) — chat
+ * - Persona constants (SIGNAL_PERSONA, REPORTER_PERSONA, etc.) — chat
  *   runtime internals; import from capabilities/participant-agents.facade.ts.
  * - ChatTitleGenerator, ChatSummarizer, etc. — runtime tool composition; import
  *   via capabilities/participant-agents.facade.ts.

package/dist/participant-agents/public/index.js

@@ -17,7 +17,7 @@
  * The following are application-internal or runtime-owned:
  * - ChatGraphFactory, ChatPersonaConfig, ChatPersona — runtime graph wiring;
  *   consumers should import via capabilities/participant-agents.facade.ts.
- * - Persona constants (ORCHESTRATOR_PERSONA_ID, SIGNAL_PERSONA, etc.) — chat
+ * - Persona constants (SIGNAL_PERSONA, REPORTER_PERSONA, etc.) — chat
  *   runtime internals; import from capabilities/participant-agents.facade.ts.
  * - ChatTitleGenerator, ChatSummarizer, etc. — runtime tool composition; import
  *   via capabilities/participant-agents.facade.ts.

package/dist/questions/application/index.d.ts

@@ -32,7 +32,7 @@ export { isValidQuestionerInputContract, } from "./question.input.js";
 export type { QuestionerInput, QuestionerContext, QuestionerEnqueuePayload, QuestionerEnqueueFn, IntentContext, RecoveryIntentContext, NegotiationContext, PostStallNegotiationContext, UptakeNegotiationContext, NegotiationInflightContext, ChatContext, PoolDiscoveryContext, PostStallQuestionerInput, InflightQuestionerInput, UptakeQuestionerInput, RecoveryQuestionerInput, } from "./question.input.js";
 export { QuestionerAgent } from "./question.agent.js";
 export type { QuestionerAgentConfig } from "./question.agent.js";
-export { isQuestionerEnabled, isUptakeGuardEnabled, uptakeAuthorityThreshold, chatQuestionWaitTimeoutMs, CHAT_QUESTION_WAIT_TIMEOUT_MS_DEFAULT, UPTAKE_AUTHORITY_THRESHOLD_DEFAULT, } from "./question.env.js";
+export { isQuestionerEnabled, isUptakeGuardEnabled, uptakeAuthorityThreshold, chatQuestionWaitTimeoutMs, intentQuestionDailyCap, CHAT_QUESTION_WAIT_TIMEOUT_MS_DEFAULT, UPTAKE_AUTHORITY_THRESHOLD_DEFAULT, INTENT_QUESTION_DAILY_CAP_DEFAULT, INTENT_QUESTION_DAILY_WINDOW_HOURS, } from "./question.env.js";
 export { getPreset } from "./question.presets.js";
 export type { QuestionerPreset } from "./question.presets.js";
 export { createQuestionerTools } from "./question.tools.js";

package/dist/questions/application/index.js

@@ -33,7 +33,7 @@ export { isValidQuestionerInputContract, } from "./question.input.js";
 // ── Agent ─────────────────────────────────────────────────────────────────────
 export { QuestionerAgent } from "./question.agent.js";
 // ── Env ───────────────────────────────────────────────────────────────────────
-export { isQuestionerEnabled, isUptakeGuardEnabled, uptakeAuthorityThreshold, chatQuestionWaitTimeoutMs, CHAT_QUESTION_WAIT_TIMEOUT_MS_DEFAULT, UPTAKE_AUTHORITY_THRESHOLD_DEFAULT, } from "./question.env.js";
+export { isQuestionerEnabled, isUptakeGuardEnabled, uptakeAuthorityThreshold, chatQuestionWaitTimeoutMs, intentQuestionDailyCap, CHAT_QUESTION_WAIT_TIMEOUT_MS_DEFAULT, UPTAKE_AUTHORITY_THRESHOLD_DEFAULT, INTENT_QUESTION_DAILY_CAP_DEFAULT, INTENT_QUESTION_DAILY_WINDOW_HOURS, } from "./question.env.js";
 // ── Presets ───────────────────────────────────────────────────────────────────
 export { getPreset } from "./question.presets.js";
 // ── Foreground adapter tools ──────────────────────────────────────────────────

package/dist/questions/application/question.env.d.ts

@@ -11,6 +11,9 @@
  *                                       authority threshold (0-100, default 70).
  *   QUESTIONER_CHAT_WAIT_TIMEOUT_MS     how long the blocking ask_user_question chat
  *                                       tool waits for an inline answer (default 4 min).
+ *   QUESTIONER_INTENT_DAILY_CAP         refinement questions one intent may generate
+ *                                       per rolling 24h, recovery + pool combined
+ *                                       (default 2; 0 disables refinement).
  *
  * All reads go through this module — do not read these variables via
  * `process.env` elsewhere. Values are read on every call (no caching) so tests
@@ -21,6 +24,25 @@
  */
 export declare const CHAT_QUESTION_WAIT_TIMEOUT_MS_DEFAULT = 240000;
 export declare const UPTAKE_AUTHORITY_THRESHOLD_DEFAULT = 70;
+/**
+ * Refinement questions a single intent may generate per rolling window.
+ *
+ * Recovery and pool mining both re-arm when the intent text changes, and
+ * answering a refinement question is itself what changes it — so each answer
+ * buys another question and the loop ends only when the user stops replying.
+ * Measured on a dev account: 27 questions against three intents in 9.5 hours,
+ * one discriminator asked three times, while the best-scoring match had already
+ * been found after the first question.
+ */
+export declare const INTENT_QUESTION_DAILY_CAP_DEFAULT = 2;
+/**
+ * Width of the budget window, in hours.
+ *
+ * Rolling rather than per-UTC-day deliberately: the observed bursts straddled
+ * midnight UTC (20:22-21:18, then 05:48-05:55), and a calendar-day budget would
+ * have granted the second burst a full fresh allowance.
+ */
+export declare const INTENT_QUESTION_DAILY_WINDOW_HOURS = 24;
 /** Master switch: is any background question generation enabled? */
 export declare function isQuestionerEnabled(): boolean;
 /** Advisory uptake interlock. Flag-off by default and subordinate to the master switch. */
@@ -29,3 +51,10 @@ export declare function isUptakeGuardEnabled(): boolean;
 export declare function uptakeAuthorityThreshold(): number;
 /** Wait budget for the blocking ask_user_question chat tool. */
 export declare function chatQuestionWaitTimeoutMs(): number;
+/**
+ * Per-intent refinement budget over {@link INTENT_QUESTION_DAILY_WINDOW_HOURS}.
+ *
+ * Zero is a meaningful setting — it disables background refinement entirely
+ * without touching the master switch — so this does not reuse `positiveIntEnv`.
+ */
+export declare function intentQuestionDailyCap(): number;

package/dist/questions/application/question.env.js

@@ -11,6 +11,9 @@
  *                                       authority threshold (0-100, default 70).
  *   QUESTIONER_CHAT_WAIT_TIMEOUT_MS     how long the blocking ask_user_question chat
  *                                       tool waits for an inline answer (default 4 min).
+ *   QUESTIONER_INTENT_DAILY_CAP         refinement questions one intent may generate
+ *                                       per rolling 24h, recovery + pool combined
+ *                                       (default 2; 0 disables refinement).
  *
  * All reads go through this module — do not read these variables via
  * `process.env` elsewhere. Values are read on every call (no caching) so tests
@@ -21,6 +24,25 @@
  */
 export const CHAT_QUESTION_WAIT_TIMEOUT_MS_DEFAULT = 240000;
 export const UPTAKE_AUTHORITY_THRESHOLD_DEFAULT = 70;
+/**
+ * Refinement questions a single intent may generate per rolling window.
+ *
+ * Recovery and pool mining both re-arm when the intent text changes, and
+ * answering a refinement question is itself what changes it — so each answer
+ * buys another question and the loop ends only when the user stops replying.
+ * Measured on a dev account: 27 questions against three intents in 9.5 hours,
+ * one discriminator asked three times, while the best-scoring match had already
+ * been found after the first question.
+ */
+export const INTENT_QUESTION_DAILY_CAP_DEFAULT = 2;
+/**
+ * Width of the budget window, in hours.
+ *
+ * Rolling rather than per-UTC-day deliberately: the observed bursts straddled
+ * midnight UTC (20:22-21:18, then 05:48-05:55), and a calendar-day budget would
+ * have granted the second burst a full fresh allowance.
+ */
+export const INTENT_QUESTION_DAILY_WINDOW_HOURS = 24;
 /**
  * Parse a positive integer env var, clamped to the safe-integer range so a
  * malformed env value cannot crash `AbortSignal.timeout` (which throws on
@@ -57,3 +79,17 @@ export function uptakeAuthorityThreshold() {
 export function chatQuestionWaitTimeoutMs() {
     return positiveIntEnv("QUESTIONER_CHAT_WAIT_TIMEOUT_MS", CHAT_QUESTION_WAIT_TIMEOUT_MS_DEFAULT);
 }
+/**
+ * Per-intent refinement budget over {@link INTENT_QUESTION_DAILY_WINDOW_HOURS}.
+ *
+ * Zero is a meaningful setting — it disables background refinement entirely
+ * without touching the master switch — so this does not reuse `positiveIntEnv`.
+ */
+export function intentQuestionDailyCap() {
+    const raw = process.env.QUESTIONER_INTENT_DAILY_CAP;
+    if (!raw?.trim())
+        return INTENT_QUESTION_DAILY_CAP_DEFAULT;
+    if (!/^\d+$/.test(raw.trim()))
+        return INTENT_QUESTION_DAILY_CAP_DEFAULT;
+    return Number.parseInt(raw, 10);
+}

package/dist/questions/public/index.d.ts

@@ -40,7 +40,7 @@
 export * from "../domain/index.js";
 export { QuestionerAgent } from "../application/index.js";
 export type { QuestionerAgentConfig } from "../application/index.js";
-export { isQuestionerEnabled, isUptakeGuardEnabled, uptakeAuthorityThreshold, UPTAKE_AUTHORITY_THRESHOLD_DEFAULT, } from "../application/index.js";
+export { isQuestionerEnabled, isUptakeGuardEnabled, uptakeAuthorityThreshold, intentQuestionDailyCap, UPTAKE_AUTHORITY_THRESHOLD_DEFAULT, INTENT_QUESTION_DAILY_CAP_DEFAULT, INTENT_QUESTION_DAILY_WINDOW_HOURS, } from "../application/index.js";
 export { isValidQuestionerInputContract, } from "../application/index.js";
 export type { QuestionerInput, QuestionerEnqueuePayload, QuestionerEnqueueFn, PoolDiscoveryContext, RecoveryQuestionerInput, UptakeQuestionerInput, PostStallQuestionerInput, InflightQuestionerInput, } from "../application/index.js";
 export { createQuestionerTools, createAskUserQuestionTools } from "../application/index.js";

package/dist/questions/public/index.js

@@ -42,7 +42,7 @@ export * from "../domain/index.js";
 // ── Application: agent ────────────────────────────────────────────────────────
 export { QuestionerAgent } from "../application/index.js";
 // ── Application: env accessors ────────────────────────────────────────────────
-export { isQuestionerEnabled, isUptakeGuardEnabled, uptakeAuthorityThreshold, UPTAKE_AUTHORITY_THRESHOLD_DEFAULT, } from "../application/index.js";
+export { isQuestionerEnabled, isUptakeGuardEnabled, uptakeAuthorityThreshold, intentQuestionDailyCap, UPTAKE_AUTHORITY_THRESHOLD_DEFAULT, INTENT_QUESTION_DAILY_CAP_DEFAULT, INTENT_QUESTION_DAILY_WINDOW_HOURS, } from "../application/index.js";
 // ── Application: input types and validation ───────────────────────────────────
 export { isValidQuestionerInputContract, } from "../application/index.js";
 // ── Application: foreground adapter tools ─────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indexnetwork/protocol",
-  "version": "13.2.1-rc.467.1",
+  "version": "14.1.0-rc.469.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",