@superatomai/sdk-node 0.0.69-dsp → 0.0.70-dsp

package/dist/index.d.mts

@@ -1068,6 +1068,28 @@ interface RunTrace {
             note?: string;
         }>;
     };
+    /**
+     * Direct-tool activity this turn (main-agent.ts's handleDirectTool) — one
+     * entry per direct-tool call, unconditional and generic across every
+     * project's direct tools, not specific to one. For fusion-5's `concept`
+     * tool this is what actually traces find/get/run (distinguished via
+     * `input.method`) — unlike `concepts.calls` above, which only the
+     * dashboard-agent flow's own, separate concept tool still populates;
+     * MainAgent no longer resolves concepts itself, so nothing else writes
+     * here for a chat/report turn.
+     */
+    directTools: {
+        calls: Array<{
+            toolId: string;
+            /** Exact params the LLM called this tool with. */
+            input: any;
+            /** The tool's raw return value. Absent when `error` is set. */
+            output?: any;
+            /** Set whether the tool's own result carried an `error` field or the call threw. */
+            error?: string;
+            durationMs?: number;
+        }>;
+    };
     /**
      * The prior-turn conversation context injected into this turn's prompt as
      * CONVERSATION_HISTORY — exactly what each flow already builds for itself
@@ -1311,13 +1333,23 @@ declare class Logger {
      */
     debug(...args: any[]): void;
     /**
-     * Write to log file
+     * Write to log file — each line timestamped so a request that made many
+     * calls (LLM turns, tool dispatches, direct-tool runs) can be read back in
+     * order, matching "know what happened when" rather than just "what
+     * happened".
      */
     file(...args: any[]): void;
+    /** The log file the current request is writing to — print/return this so it's easy to find afterward. */
+    getCurrentLogFilePath(): string;
     /**
-     * Clear the log file (call at start of new user request)
+     * Start a fresh, uniquely-named log file for a new top-level request
+     * (chat turn, dashComp request, reportComp request, ...) instead of
+     * truncating one shared file — pass a short label (a prompt snippet, a
+     * request type) so the resulting filename is identifiable at a glance.
+     * Falls back to the untimestamped legacy path when `label` is omitted, for
+     * any caller not yet updated to pass one.
      */
-    clearFile(): void;
+    clearFile(label?: string): void;
     /**
      * Log LLM method prompts with clear labeling
      */
@@ -2099,6 +2131,16 @@ interface DashCompModelConfig {
      */
     fastModel?: string;
 }
+/**
+ * Where a question was asked from. Every field is optional; an empty object and
+ * an absent context mean the same thing.
+ */
+interface PromptContext {
+    /** The dashboard on screen when the question was asked. */
+    dashboardId?: string;
+    /** The filter values set on that dashboard, keyed by parameter name. */
+    filters?: Record<string, unknown>;
+}
 /**
  * Everything a replacement answer flow is handed for one question. Deliberately
  * the same material the built-in flow gets, so a provider is a drop-in and not a
@@ -2128,6 +2170,8 @@ interface AnswerProviderContext {
         text: string;
     }) => void;
     signal?: AbortSignal;
+    /** Where the question was asked from, when the client said. */
+    context?: PromptContext;
 }
 /**
  * One narrator tick while an answer was being produced: what the narrator was
@@ -2160,6 +2204,8 @@ interface NarrationUpdate {
  *
  * `data.narration` (NarrationUpdate[]) is optional and saved with the answer on
  * every outcome — success, error and abort — so return it on each of them.
+ *
+ * `data` may also carry `trace`, and `usage` and `model` per `AnswerProviderReport`.
  */
 type AnswerProvider = (ctx: AnswerProviderContext) => Promise<T_RESPONSE>;
 interface SuperatomSDKConfig {
@@ -2227,6 +2273,12 @@ interface SuperatomSDKConfig {
      * Default: 5 minutes
      */
     queryCacheTTL?: number;
+    /**
+     * Keep query results in the SDK's in-memory cache.
+     * Set false when the host caches results itself; queryId tokens keep working.
+     * Default: true
+     */
+    queryResultCache?: boolean;
     /**
      * Dashboard conversation history TTL (Time To Live) in minutes
      * Per-dashboard conversation histories expire after this duration
@@ -3104,9 +3156,11 @@ declare class MainAgent {
      */
     private resolvedEntities;
     /**
-     * Concept bodies resolved this turn (via resolve_entities' embedded concept
-     * lookup or a standalone resolve_concepts call) — retained the same way as
-     * resolvedEntities above, so they can be attached to the SourceAgent dispatch.
+     * Concept bodies resolved this turn (currently: invariants only, via
+     * loadConceptInvariants — concept resolution is no longer part of
+     * resolve_entities or any other MainAgent-owned tool) — retained the same
+     * way as resolvedEntities above, so they can be attached to the SourceAgent
+     * dispatch.
      *
      * Without this, a concept resolved HERE (MainAgent's own tool loop) never
      * reaches SourceAgent at all: SourceAgent only gets the natural-language
@@ -3257,13 +3311,36 @@ declare class MainAgent {
      * it; scopeSql is the one thing worth this guarantee today.
      */
     private buildResolvedEntitiesBlock;
-    /** Dedupe-and-retain helper shared by resolveConceptsForTurn and handleResolveConcepts. */
+    /**
+     * Dedupe-and-retain helper shared by loadConceptInvariants and the generic
+     * direct-tool `resolvedConcepts` opt-in hook. `alwaysInclude` marks entries
+     * that buildResolvedConceptsBlock must attach to EVERY dispatch regardless
+     * of that dispatch's `concepts` param — true only for invariants, which are
+     * meant to apply everywhere by definition. Concepts retained without it
+     * (e.g. via the `concept` tool's `get`) are scoped per-dispatch instead.
+     */
     private retainResolvedConcepts;
     /**
      * Same purpose as buildResolvedEntitiesBlock, for concept bodies instead of
      * entity ids — appended to the dispatch intent so SourceAgent's own,
      * independent LLM call receives the resolved definitions verbatim rather
      * than only MainAgent's paraphrased intent text.
+     *
+     * Unlike buildResolvedEntitiesBlock, non-invariant entries here are SCOPED
+     * to `names` (this dispatch's SourceToolInput.concepts) rather than
+     * dumping the whole-turn `this.resolvedConcepts` accumulator into every
+     * dispatch. A concept body is phrased as an authoritative override
+     * ("overrides the schema... your own reasoning") — fetching several via
+     * `get` to compare/discard, or a turn needing different concepts for
+     * different sub-questions, must not leak an irrelevant concept's filters
+     * into an unrelated dispatch. An entry not named in `names` and not
+     * `alwaysInclude` is left out — a concept the model forgot to name is a
+     * visible, fixable miss; one that leaks in uninvited is not.
+     *
+     * `alwaysInclude` entries (invariants — see loadConceptInvariants) bypass
+     * `names` entirely and attach to every dispatch regardless, same as before
+     * this method took a `names` param — they are meant to apply everywhere,
+     * not just when the model happens to ask for them.
      */
     private buildResolvedConceptsBlock;
     /** True when the backend registered the entity-search collection. */
@@ -3271,11 +3348,21 @@ declare class MainAgent {
     /** True when the backend registered the concepts collection. */
     private get conceptsEnabled();
     /**
-     * Concept names for the system prompt. Names ONLY — the body comes back from
+     * The concept catalog for the system prompt: one line per concept — name,
+     * aliases, and what it is for. No bodies — the body comes back from
      * resolve_concepts once the LLM has named one, exactly as with the entity
      * catalog. Putting bodies here would rebuild the always-on context problem
      * concepts exist to solve.
      *
+     * The description is what makes the list usable. It used to be names only,
+     * which asked the model to judge from a name alone whether `ref-data null
+     * sentinel` bears on the question in front of it — and a wrong judgement is
+     * silent, since it simply does not fetch. A line of prose per concept costs
+     * a few tokens and is read rather than matched.
+     *
+     * Aliases stay, because they are how a user is likely to phrase it, and
+     * showing them is what stops the LLM inventing a near-miss name.
+     *
      * Not cached, for the same reason loadEntityCatalog isn't: unchanged rows
      * render byte-identical text so the prompt-cache prefix still hits, and a
      * process cache would only buy a window where a new concept is invisible.
@@ -3291,40 +3378,21 @@ declare class MainAgent {
      * Bodies ARE included here — unlike the catalog — because there is nothing to
      * request: being unrequestable is what makes them invariants.
      *
-     * Also retained into resolvedConcepts (same as an explicit resolve_concepts
-     * call) so these bodies reach SourceAgent's dispatch too — an invariant is
-     * meant to apply everywhere, not just wherever the model happens to ask for
-     * something whose `requires` chain reaches it.
+     * Also retained into resolvedConcepts so these bodies reach SourceAgent's
+     * dispatch too — an invariant is meant to apply everywhere, not just
+     * wherever the model happens to ask for something whose `requires` chain
+     * reaches it. This is now the ONLY way a concept body reaches
+     * resolvedConcepts/SourceAgent's dispatch automatically — a non-invariant
+     * concept fetched through a project's own concept-lookup tool (if any) is
+     * NOT retained here, and will not reach a later SourceAgent dispatch unless
+     * the model itself restates it in the intent it writes.
      */
     private loadConceptInvariants;
-    /**
-     * Resolve the concepts for a turn, with a SERVER-SIDE FLOOR.
-     *
-     * Pinning a tool guarantees it is called; it does not guarantee the model
-     * fills in the arguments. Observed: a question containing the exact words
-     * "revenue forecast" produced a call with no concepts at all, and the agent
-     * then used an incomplete copy of the formula from the knowledge base — the
-     * resulting query filtered a customer id against a project column and
-     * returned zero rows on every attempt.
-     *
-     * So when the model names nothing, scan the question itself for catalog names
-     * and aliases on word boundaries. Precise (a literal name is evidence, not a
-     * guess) and asymmetric in the safe direction: an unneeded definition costs a
-     * few hundred ignorable tokens, a missing one costs a wrong answer.
-     */
-    /**
-     * Returns the tool-facing fields to spread into the resolve_entities JSON
-     * response, PLUS a `_trace` field with everything the trace needs that the
-     * model does not (asked/viaFloor/unmatched). Callers must pull `_trace` out
-     * before spreading the rest into what the model sees — see handleResolveEntities.
-     */
-    private resolveConceptsForTurn;
     /**
      * Never throws: a concept-store outage must degrade to "no definition found"
      * and leave the agent deriving the formula as it does today, not take the
      * whole answer down.
      */
-    private handleResolveConcepts;
     /**
      * Compact catalog (type + gloss) for the system prompt. This is what lets the
      * LLM NAME a concept instead of guessing at our vocabulary — it can infer
@@ -3446,6 +3514,23 @@ interface LLMOptions {
         type: 'tool';
         name: string;
     };
+    /**
+     * Same forcing as `firstIterationToolChoice`, for the SECOND iteration only
+     * (iteration 3+ reverts to auto, same as iteration 2+ does for the first-
+     * iteration option). Added for MainAgent's `concept` tool: `resolve_entities`
+     * being pinned to iteration 1 doesn't, by itself, make `concept` reliable —
+     * confirmed live, repeatedly, that a model can skip it even with a CRITICAL
+     * prompt instruction telling it not to. Pinning iteration 2 the same way
+     * `resolve_entities` pins iteration 1 makes it structurally guaranteed
+     * instead of prose-dependent. Honored on both the Anthropic and OpenAI/
+     * OpenRouter paths, same as `firstIterationToolChoice`.
+     */
+    secondIterationToolChoice?: {
+        type: 'any';
+    } | {
+        type: 'tool';
+        name: string;
+    };
     /**
      * Internal — set only by the OpenRouter wrappers when the target is a Claude
      * model. Tells the OpenAI-wire path to emit Anthropic `cache_control`
@@ -4825,6 +4910,7 @@ declare class QueryCache {
     private ttlMs;
     private maxCacheSize;
     private cleanupInterval;
+    private resultCacheEnabled;
     private readonly algorithm;
     private encryptionKey;
     constructor();
@@ -4837,6 +4923,11 @@ declare class QueryCache {
      * Get the current TTL in minutes
      */
     getTTL(): number;
+    /**
+     * Stop keeping result data in memory, for a host that caches results itself.
+     * `set` stores nothing and `get` finds nothing; queryId tokens are unaffected.
+     */
+    disableResultCache(): void;
     /**
      * Which access bucket this call reads and writes.
      *
@@ -5445,11 +5536,7 @@ declare function createCodexSession(opts: CodexSessionOptions): CodingAgentSessi
 
 /**
  * One transcript entry — everything worth replaying to a caller that reconnects
- * mid-run or after the fact, without having sent the prompt itself. Deliberately
- * a separate, richer shape from AgentEvent: that one only carries tool/command
- * activity (what events()/buffer() below still expose, unchanged), not prompts
- * or finished answers — which a reconnecting client needs too, per-turn, not as
- * a flat concatenated buffer.
+ * mid-run or after the fact, without having sent the prompt itself.
  */
 interface PiTranscriptEntry {
     at: number;
@@ -5464,16 +5551,9 @@ interface PiSessionState {
     transcript: PiTranscriptEntry[];
 }
 type PiSessionListener = (sessionKey: string, entry: PiTranscriptEntry) => void;
-/** Watch every live pi session's activity, not just one you started yourself — same broadcast idea dashboard-pi uses so a second, later caller can watch a session already in progress. */
+/** Watch every live pi session's activity, not just one you started yourself. */
 declare function onPiSessionUpdate(listener: PiSessionListener): () => void;
-/**
- * Current state of a live session — for a caller that reconnects mid-run or
- * wants to replay what happened, without sending a prompt itself.
- *
- * undefined when the session isn't live: never started, evicted by the idle
- * sweeper, or the backend restarted. Same "lost the transcript, not the work"
- * tradeoff as everywhere else in this driver — nothing here survives a restart.
- */
+/** Current state of a live session; undefined once it is no longer in memory. */
 declare function getPiSessionState(sessionKey: string): PiSessionState | undefined;
 
 /**
@@ -6548,4 +6628,4 @@ declare class SuperatomSDK {
     getConversationSimilarityThreshold(): number;
 }
 
-export { ALL_COLUMN_KEYS, ANSWER_COMPONENT_NAMES, type AgentConfig, type AgentEvent, type AgentResponse, type AgentRunContext, type AgentRunHandlers, type AgentRunRecord, type AgentRunResult, type AgentTrigger, type AgentUsage, type AnalyticsEventType, type AnalyticsStatus, type AnswerProvider, type AnswerProviderContext, type ApplySummary, BM25L, type BM25LOptions, type BaseLLMConfig, type BuildTriggerInput, CATEGORY_KEYS, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CodexSessionOptions, type CodingAgentCollectionConfig, type CodingAgentDefinition, type CodingAgentSession, type CodingAgentSessionOptions, type CodingAgentsConfig, type ColInfo, type ColType, type CollectionHandler, type CollectionOperation, type Component, type DBUIBlock, DEFAULT_AGENT_CONFIG, DEFAULT_FMT_CONFIG, type DashboardAgentCollectionConfig, type DatabaseType, type FindingCode, type Fmt, type FmtConfig, type Harness, type HybridSearchOptions, INSTRUCTIONS_FILE, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, MainAgent, type McpServerSpec, type Message, MissingRequestContextError, type ModelStrategy, NUMERIC_KEYS, type NarrationUpdate, type OutputContract, type OutputField, type OutputValidator, type PiSessionListener, type PiSessionState, type PiTranscriptEntry, type Principal, type RequestContext, type RerankedResult, type RowFilter, type RunAgentOptions, STORAGE_CONFIG, type ScriptComponentSpec, ScriptMatcher, type ScriptParameter, type ScriptRecipe, type ScriptRecipeMetaRow, type ScriptRecipeStore, type ScriptResult, ScriptStore, type ScriptStoreOptions, type SelectedWorkflow, type ShimDef, type ShimSummary, type ShimTarget, type SourcePolicy, type SpecToValidate, SuperatomSDK, type SuperatomSDKConfig, type T_RESPONSE, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, type TriggerEvent, type TriggerFireInfo, UIBlock, UILogCollector, type User, UserManager, type UsersData, type ValidationContext, type ValidationFinding, type WorkflowDescriptor, type Workspace, analyticsClient, answerCatalogForBinding, answerComponents, anthropicLLM, assertReadOnlySql, bindContext, bridgePreamble, captureContext, clearContextTokens, contextTokenCount, createCodexSession, createCodingAgentSession, dashboardConversationHistory, dataFingerprint, describeContext, describeTriggers, emitAgentEvent, extractNamedExport, formatFindingsForAgent, geminiLLM, getCodingAgent, getCodingAgentsConfig, getPiSessionState, getRequestContext, groqLLM, hybridRerank, inferColumns, isUserContext, listCodingAgents, llmUsageLogger, logger, makeFmt, mintContextToken, normalizeScriptBody, onAgentRun, onPiSessionUpdate, openaiLLM, policiesFromConfig, projectForDatasetBinding, promptLoader, queryCache, registerCodingAgentCollection, registerCodingAgents, registerDashboardAgentCollection, requireRequestContext, rerankChromaResults, rerankConversationResults, resolveContextToken, resolveScriptRecipeStore, revokeContextToken, runAsSystem, runAsUser, runCodingAgent, runScript, runWithContext, runWithMessageIdentity, startAgentTriggers, stopAgentTriggers, userPromptErrorLogger, validateComponentSpec, withCapturedContext, writeBridgeShims, writeShims };
+export { ALL_COLUMN_KEYS, ANSWER_COMPONENT_NAMES, type AgentConfig, type AgentEvent, type AgentResponse, type AgentRunContext, type AgentRunHandlers, type AgentRunRecord, type AgentRunResult, type AgentTrigger, type AgentUsage, type AnalyticsEventType, type AnalyticsStatus, type AnswerProvider, type AnswerProviderContext, type ApplySummary, BM25L, type BM25LOptions, type BaseLLMConfig, type BuildTriggerInput, CATEGORY_KEYS, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CodexSessionOptions, type CodingAgentCollectionConfig, type CodingAgentDefinition, type CodingAgentSession, type CodingAgentSessionOptions, type CodingAgentsConfig, type ColInfo, type ColType, type CollectionHandler, type CollectionOperation, type Component, type DBUIBlock, DEFAULT_AGENT_CONFIG, DEFAULT_FMT_CONFIG, type DashboardAgentCollectionConfig, type DatabaseType, type FindingCode, type Fmt, type FmtConfig, type Harness, type HybridSearchOptions, INSTRUCTIONS_FILE, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, MainAgent, type McpServerSpec, type Message, MissingRequestContextError, type ModelStrategy, NUMERIC_KEYS, type NarrationUpdate, type OutputContract, type OutputField, type OutputValidator, type PiSessionListener, type PiSessionState, type PiTranscriptEntry, type Principal, type PromptContext, type RequestContext, type RerankedResult, type RowFilter, type RunAgentOptions, STORAGE_CONFIG, type ScriptComponentSpec, ScriptMatcher, type ScriptParameter, type ScriptRecipe, type ScriptRecipeMetaRow, type ScriptRecipeStore, type ScriptResult, ScriptStore, type ScriptStoreOptions, type SelectedWorkflow, type ShimDef, type ShimSummary, type ShimTarget, type SourcePolicy, type SpecToValidate, SuperatomSDK, type SuperatomSDKConfig, type T_RESPONSE, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, type TriggerEvent, type TriggerFireInfo, UIBlock, UILogCollector, type User, UserManager, type UsersData, type ValidationContext, type ValidationFinding, type WorkflowDescriptor, type Workspace, analyticsClient, answerCatalogForBinding, answerComponents, anthropicLLM, assertReadOnlySql, bindContext, bridgePreamble, captureContext, clearContextTokens, contextTokenCount, createCodexSession, createCodingAgentSession, dashboardConversationHistory, dataFingerprint, describeContext, describeTriggers, emitAgentEvent, extractNamedExport, formatFindingsForAgent, geminiLLM, getCodingAgent, getCodingAgentsConfig, getPiSessionState, getRequestContext, groqLLM, hybridRerank, inferColumns, isUserContext, listCodingAgents, llmUsageLogger, logger, makeFmt, mintContextToken, normalizeScriptBody, onAgentRun, onPiSessionUpdate, openaiLLM, policiesFromConfig, projectForDatasetBinding, promptLoader, queryCache, registerCodingAgentCollection, registerCodingAgents, registerDashboardAgentCollection, requireRequestContext, rerankChromaResults, rerankConversationResults, resolveContextToken, resolveScriptRecipeStore, revokeContextToken, runAsSystem, runAsUser, runCodingAgent, runScript, runWithContext, runWithMessageIdentity, startAgentTriggers, stopAgentTriggers, userPromptErrorLogger, validateComponentSpec, withCapturedContext, writeBridgeShims, writeShims };

package/dist/index.d.ts

@@ -1068,6 +1068,28 @@ interface RunTrace {
             note?: string;
         }>;
     };
+    /**
+     * Direct-tool activity this turn (main-agent.ts's handleDirectTool) — one
+     * entry per direct-tool call, unconditional and generic across every
+     * project's direct tools, not specific to one. For fusion-5's `concept`
+     * tool this is what actually traces find/get/run (distinguished via
+     * `input.method`) — unlike `concepts.calls` above, which only the
+     * dashboard-agent flow's own, separate concept tool still populates;
+     * MainAgent no longer resolves concepts itself, so nothing else writes
+     * here for a chat/report turn.
+     */
+    directTools: {
+        calls: Array<{
+            toolId: string;
+            /** Exact params the LLM called this tool with. */
+            input: any;
+            /** The tool's raw return value. Absent when `error` is set. */
+            output?: any;
+            /** Set whether the tool's own result carried an `error` field or the call threw. */
+            error?: string;
+            durationMs?: number;
+        }>;
+    };
     /**
      * The prior-turn conversation context injected into this turn's prompt as
      * CONVERSATION_HISTORY — exactly what each flow already builds for itself
@@ -1311,13 +1333,23 @@ declare class Logger {
      */
     debug(...args: any[]): void;
     /**
-     * Write to log file
+     * Write to log file — each line timestamped so a request that made many
+     * calls (LLM turns, tool dispatches, direct-tool runs) can be read back in
+     * order, matching "know what happened when" rather than just "what
+     * happened".
      */
     file(...args: any[]): void;
+    /** The log file the current request is writing to — print/return this so it's easy to find afterward. */
+    getCurrentLogFilePath(): string;
     /**
-     * Clear the log file (call at start of new user request)
+     * Start a fresh, uniquely-named log file for a new top-level request
+     * (chat turn, dashComp request, reportComp request, ...) instead of
+     * truncating one shared file — pass a short label (a prompt snippet, a
+     * request type) so the resulting filename is identifiable at a glance.
+     * Falls back to the untimestamped legacy path when `label` is omitted, for
+     * any caller not yet updated to pass one.
      */
-    clearFile(): void;
+    clearFile(label?: string): void;
     /**
      * Log LLM method prompts with clear labeling
      */
@@ -2099,6 +2131,16 @@ interface DashCompModelConfig {
      */
     fastModel?: string;
 }
+/**
+ * Where a question was asked from. Every field is optional; an empty object and
+ * an absent context mean the same thing.
+ */
+interface PromptContext {
+    /** The dashboard on screen when the question was asked. */
+    dashboardId?: string;
+    /** The filter values set on that dashboard, keyed by parameter name. */
+    filters?: Record<string, unknown>;
+}
 /**
  * Everything a replacement answer flow is handed for one question. Deliberately
  * the same material the built-in flow gets, so a provider is a drop-in and not a
@@ -2128,6 +2170,8 @@ interface AnswerProviderContext {
         text: string;
     }) => void;
     signal?: AbortSignal;
+    /** Where the question was asked from, when the client said. */
+    context?: PromptContext;
 }
 /**
  * One narrator tick while an answer was being produced: what the narrator was
@@ -2160,6 +2204,8 @@ interface NarrationUpdate {
  *
  * `data.narration` (NarrationUpdate[]) is optional and saved with the answer on
  * every outcome — success, error and abort — so return it on each of them.
+ *
+ * `data` may also carry `trace`, and `usage` and `model` per `AnswerProviderReport`.
  */
 type AnswerProvider = (ctx: AnswerProviderContext) => Promise<T_RESPONSE>;
 interface SuperatomSDKConfig {
@@ -2227,6 +2273,12 @@ interface SuperatomSDKConfig {
      * Default: 5 minutes
      */
     queryCacheTTL?: number;
+    /**
+     * Keep query results in the SDK's in-memory cache.
+     * Set false when the host caches results itself; queryId tokens keep working.
+     * Default: true
+     */
+    queryResultCache?: boolean;
     /**
      * Dashboard conversation history TTL (Time To Live) in minutes
      * Per-dashboard conversation histories expire after this duration
@@ -3104,9 +3156,11 @@ declare class MainAgent {
      */
     private resolvedEntities;
     /**
-     * Concept bodies resolved this turn (via resolve_entities' embedded concept
-     * lookup or a standalone resolve_concepts call) — retained the same way as
-     * resolvedEntities above, so they can be attached to the SourceAgent dispatch.
+     * Concept bodies resolved this turn (currently: invariants only, via
+     * loadConceptInvariants — concept resolution is no longer part of
+     * resolve_entities or any other MainAgent-owned tool) — retained the same
+     * way as resolvedEntities above, so they can be attached to the SourceAgent
+     * dispatch.
      *
      * Without this, a concept resolved HERE (MainAgent's own tool loop) never
      * reaches SourceAgent at all: SourceAgent only gets the natural-language
@@ -3257,13 +3311,36 @@ declare class MainAgent {
      * it; scopeSql is the one thing worth this guarantee today.
      */
     private buildResolvedEntitiesBlock;
-    /** Dedupe-and-retain helper shared by resolveConceptsForTurn and handleResolveConcepts. */
+    /**
+     * Dedupe-and-retain helper shared by loadConceptInvariants and the generic
+     * direct-tool `resolvedConcepts` opt-in hook. `alwaysInclude` marks entries
+     * that buildResolvedConceptsBlock must attach to EVERY dispatch regardless
+     * of that dispatch's `concepts` param — true only for invariants, which are
+     * meant to apply everywhere by definition. Concepts retained without it
+     * (e.g. via the `concept` tool's `get`) are scoped per-dispatch instead.
+     */
     private retainResolvedConcepts;
     /**
      * Same purpose as buildResolvedEntitiesBlock, for concept bodies instead of
      * entity ids — appended to the dispatch intent so SourceAgent's own,
      * independent LLM call receives the resolved definitions verbatim rather
      * than only MainAgent's paraphrased intent text.
+     *
+     * Unlike buildResolvedEntitiesBlock, non-invariant entries here are SCOPED
+     * to `names` (this dispatch's SourceToolInput.concepts) rather than
+     * dumping the whole-turn `this.resolvedConcepts` accumulator into every
+     * dispatch. A concept body is phrased as an authoritative override
+     * ("overrides the schema... your own reasoning") — fetching several via
+     * `get` to compare/discard, or a turn needing different concepts for
+     * different sub-questions, must not leak an irrelevant concept's filters
+     * into an unrelated dispatch. An entry not named in `names` and not
+     * `alwaysInclude` is left out — a concept the model forgot to name is a
+     * visible, fixable miss; one that leaks in uninvited is not.
+     *
+     * `alwaysInclude` entries (invariants — see loadConceptInvariants) bypass
+     * `names` entirely and attach to every dispatch regardless, same as before
+     * this method took a `names` param — they are meant to apply everywhere,
+     * not just when the model happens to ask for them.
      */
     private buildResolvedConceptsBlock;
     /** True when the backend registered the entity-search collection. */
@@ -3271,11 +3348,21 @@ declare class MainAgent {
     /** True when the backend registered the concepts collection. */
     private get conceptsEnabled();
     /**
-     * Concept names for the system prompt. Names ONLY — the body comes back from
+     * The concept catalog for the system prompt: one line per concept — name,
+     * aliases, and what it is for. No bodies — the body comes back from
      * resolve_concepts once the LLM has named one, exactly as with the entity
      * catalog. Putting bodies here would rebuild the always-on context problem
      * concepts exist to solve.
      *
+     * The description is what makes the list usable. It used to be names only,
+     * which asked the model to judge from a name alone whether `ref-data null
+     * sentinel` bears on the question in front of it — and a wrong judgement is
+     * silent, since it simply does not fetch. A line of prose per concept costs
+     * a few tokens and is read rather than matched.
+     *
+     * Aliases stay, because they are how a user is likely to phrase it, and
+     * showing them is what stops the LLM inventing a near-miss name.
+     *
      * Not cached, for the same reason loadEntityCatalog isn't: unchanged rows
      * render byte-identical text so the prompt-cache prefix still hits, and a
      * process cache would only buy a window where a new concept is invisible.
@@ -3291,40 +3378,21 @@ declare class MainAgent {
      * Bodies ARE included here — unlike the catalog — because there is nothing to
      * request: being unrequestable is what makes them invariants.
      *
-     * Also retained into resolvedConcepts (same as an explicit resolve_concepts
-     * call) so these bodies reach SourceAgent's dispatch too — an invariant is
-     * meant to apply everywhere, not just wherever the model happens to ask for
-     * something whose `requires` chain reaches it.
+     * Also retained into resolvedConcepts so these bodies reach SourceAgent's
+     * dispatch too — an invariant is meant to apply everywhere, not just
+     * wherever the model happens to ask for something whose `requires` chain
+     * reaches it. This is now the ONLY way a concept body reaches
+     * resolvedConcepts/SourceAgent's dispatch automatically — a non-invariant
+     * concept fetched through a project's own concept-lookup tool (if any) is
+     * NOT retained here, and will not reach a later SourceAgent dispatch unless
+     * the model itself restates it in the intent it writes.
      */
     private loadConceptInvariants;
-    /**
-     * Resolve the concepts for a turn, with a SERVER-SIDE FLOOR.
-     *
-     * Pinning a tool guarantees it is called; it does not guarantee the model
-     * fills in the arguments. Observed: a question containing the exact words
-     * "revenue forecast" produced a call with no concepts at all, and the agent
-     * then used an incomplete copy of the formula from the knowledge base — the
-     * resulting query filtered a customer id against a project column and
-     * returned zero rows on every attempt.
-     *
-     * So when the model names nothing, scan the question itself for catalog names
-     * and aliases on word boundaries. Precise (a literal name is evidence, not a
-     * guess) and asymmetric in the safe direction: an unneeded definition costs a
-     * few hundred ignorable tokens, a missing one costs a wrong answer.
-     */
-    /**
-     * Returns the tool-facing fields to spread into the resolve_entities JSON
-     * response, PLUS a `_trace` field with everything the trace needs that the
-     * model does not (asked/viaFloor/unmatched). Callers must pull `_trace` out
-     * before spreading the rest into what the model sees — see handleResolveEntities.
-     */
-    private resolveConceptsForTurn;
     /**
      * Never throws: a concept-store outage must degrade to "no definition found"
      * and leave the agent deriving the formula as it does today, not take the
      * whole answer down.
      */
-    private handleResolveConcepts;
     /**
      * Compact catalog (type + gloss) for the system prompt. This is what lets the
      * LLM NAME a concept instead of guessing at our vocabulary — it can infer
@@ -3446,6 +3514,23 @@ interface LLMOptions {
         type: 'tool';
         name: string;
     };
+    /**
+     * Same forcing as `firstIterationToolChoice`, for the SECOND iteration only
+     * (iteration 3+ reverts to auto, same as iteration 2+ does for the first-
+     * iteration option). Added for MainAgent's `concept` tool: `resolve_entities`
+     * being pinned to iteration 1 doesn't, by itself, make `concept` reliable —
+     * confirmed live, repeatedly, that a model can skip it even with a CRITICAL
+     * prompt instruction telling it not to. Pinning iteration 2 the same way
+     * `resolve_entities` pins iteration 1 makes it structurally guaranteed
+     * instead of prose-dependent. Honored on both the Anthropic and OpenAI/
+     * OpenRouter paths, same as `firstIterationToolChoice`.
+     */
+    secondIterationToolChoice?: {
+        type: 'any';
+    } | {
+        type: 'tool';
+        name: string;
+    };
     /**
      * Internal — set only by the OpenRouter wrappers when the target is a Claude
      * model. Tells the OpenAI-wire path to emit Anthropic `cache_control`
@@ -4825,6 +4910,7 @@ declare class QueryCache {
     private ttlMs;
     private maxCacheSize;
     private cleanupInterval;
+    private resultCacheEnabled;
     private readonly algorithm;
     private encryptionKey;
     constructor();
@@ -4837,6 +4923,11 @@ declare class QueryCache {
      * Get the current TTL in minutes
      */
     getTTL(): number;
+    /**
+     * Stop keeping result data in memory, for a host that caches results itself.
+     * `set` stores nothing and `get` finds nothing; queryId tokens are unaffected.
+     */
+    disableResultCache(): void;
     /**
      * Which access bucket this call reads and writes.
      *
@@ -5445,11 +5536,7 @@ declare function createCodexSession(opts: CodexSessionOptions): CodingAgentSessi
 
 /**
  * One transcript entry — everything worth replaying to a caller that reconnects
- * mid-run or after the fact, without having sent the prompt itself. Deliberately
- * a separate, richer shape from AgentEvent: that one only carries tool/command
- * activity (what events()/buffer() below still expose, unchanged), not prompts
- * or finished answers — which a reconnecting client needs too, per-turn, not as
- * a flat concatenated buffer.
+ * mid-run or after the fact, without having sent the prompt itself.
  */
 interface PiTranscriptEntry {
     at: number;
@@ -5464,16 +5551,9 @@ interface PiSessionState {
     transcript: PiTranscriptEntry[];
 }
 type PiSessionListener = (sessionKey: string, entry: PiTranscriptEntry) => void;
-/** Watch every live pi session's activity, not just one you started yourself — same broadcast idea dashboard-pi uses so a second, later caller can watch a session already in progress. */
+/** Watch every live pi session's activity, not just one you started yourself. */
 declare function onPiSessionUpdate(listener: PiSessionListener): () => void;
-/**
- * Current state of a live session — for a caller that reconnects mid-run or
- * wants to replay what happened, without sending a prompt itself.
- *
- * undefined when the session isn't live: never started, evicted by the idle
- * sweeper, or the backend restarted. Same "lost the transcript, not the work"
- * tradeoff as everywhere else in this driver — nothing here survives a restart.
- */
+/** Current state of a live session; undefined once it is no longer in memory. */
 declare function getPiSessionState(sessionKey: string): PiSessionState | undefined;
 
 /**
@@ -6548,4 +6628,4 @@ declare class SuperatomSDK {
     getConversationSimilarityThreshold(): number;
 }
 
-export { ALL_COLUMN_KEYS, ANSWER_COMPONENT_NAMES, type AgentConfig, type AgentEvent, type AgentResponse, type AgentRunContext, type AgentRunHandlers, type AgentRunRecord, type AgentRunResult, type AgentTrigger, type AgentUsage, type AnalyticsEventType, type AnalyticsStatus, type AnswerProvider, type AnswerProviderContext, type ApplySummary, BM25L, type BM25LOptions, type BaseLLMConfig, type BuildTriggerInput, CATEGORY_KEYS, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CodexSessionOptions, type CodingAgentCollectionConfig, type CodingAgentDefinition, type CodingAgentSession, type CodingAgentSessionOptions, type CodingAgentsConfig, type ColInfo, type ColType, type CollectionHandler, type CollectionOperation, type Component, type DBUIBlock, DEFAULT_AGENT_CONFIG, DEFAULT_FMT_CONFIG, type DashboardAgentCollectionConfig, type DatabaseType, type FindingCode, type Fmt, type FmtConfig, type Harness, type HybridSearchOptions, INSTRUCTIONS_FILE, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, MainAgent, type McpServerSpec, type Message, MissingRequestContextError, type ModelStrategy, NUMERIC_KEYS, type NarrationUpdate, type OutputContract, type OutputField, type OutputValidator, type PiSessionListener, type PiSessionState, type PiTranscriptEntry, type Principal, type RequestContext, type RerankedResult, type RowFilter, type RunAgentOptions, STORAGE_CONFIG, type ScriptComponentSpec, ScriptMatcher, type ScriptParameter, type ScriptRecipe, type ScriptRecipeMetaRow, type ScriptRecipeStore, type ScriptResult, ScriptStore, type ScriptStoreOptions, type SelectedWorkflow, type ShimDef, type ShimSummary, type ShimTarget, type SourcePolicy, type SpecToValidate, SuperatomSDK, type SuperatomSDKConfig, type T_RESPONSE, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, type TriggerEvent, type TriggerFireInfo, UIBlock, UILogCollector, type User, UserManager, type UsersData, type ValidationContext, type ValidationFinding, type WorkflowDescriptor, type Workspace, analyticsClient, answerCatalogForBinding, answerComponents, anthropicLLM, assertReadOnlySql, bindContext, bridgePreamble, captureContext, clearContextTokens, contextTokenCount, createCodexSession, createCodingAgentSession, dashboardConversationHistory, dataFingerprint, describeContext, describeTriggers, emitAgentEvent, extractNamedExport, formatFindingsForAgent, geminiLLM, getCodingAgent, getCodingAgentsConfig, getPiSessionState, getRequestContext, groqLLM, hybridRerank, inferColumns, isUserContext, listCodingAgents, llmUsageLogger, logger, makeFmt, mintContextToken, normalizeScriptBody, onAgentRun, onPiSessionUpdate, openaiLLM, policiesFromConfig, projectForDatasetBinding, promptLoader, queryCache, registerCodingAgentCollection, registerCodingAgents, registerDashboardAgentCollection, requireRequestContext, rerankChromaResults, rerankConversationResults, resolveContextToken, resolveScriptRecipeStore, revokeContextToken, runAsSystem, runAsUser, runCodingAgent, runScript, runWithContext, runWithMessageIdentity, startAgentTriggers, stopAgentTriggers, userPromptErrorLogger, validateComponentSpec, withCapturedContext, writeBridgeShims, writeShims };
+export { ALL_COLUMN_KEYS, ANSWER_COMPONENT_NAMES, type AgentConfig, type AgentEvent, type AgentResponse, type AgentRunContext, type AgentRunHandlers, type AgentRunRecord, type AgentRunResult, type AgentTrigger, type AgentUsage, type AnalyticsEventType, type AnalyticsStatus, type AnswerProvider, type AnswerProviderContext, type ApplySummary, BM25L, type BM25LOptions, type BaseLLMConfig, type BuildTriggerInput, CATEGORY_KEYS, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CodexSessionOptions, type CodingAgentCollectionConfig, type CodingAgentDefinition, type CodingAgentSession, type CodingAgentSessionOptions, type CodingAgentsConfig, type ColInfo, type ColType, type CollectionHandler, type CollectionOperation, type Component, type DBUIBlock, DEFAULT_AGENT_CONFIG, DEFAULT_FMT_CONFIG, type DashboardAgentCollectionConfig, type DatabaseType, type FindingCode, type Fmt, type FmtConfig, type Harness, type HybridSearchOptions, INSTRUCTIONS_FILE, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, MainAgent, type McpServerSpec, type Message, MissingRequestContextError, type ModelStrategy, NUMERIC_KEYS, type NarrationUpdate, type OutputContract, type OutputField, type OutputValidator, type PiSessionListener, type PiSessionState, type PiTranscriptEntry, type Principal, type PromptContext, type RequestContext, type RerankedResult, type RowFilter, type RunAgentOptions, STORAGE_CONFIG, type ScriptComponentSpec, ScriptMatcher, type ScriptParameter, type ScriptRecipe, type ScriptRecipeMetaRow, type ScriptRecipeStore, type ScriptResult, ScriptStore, type ScriptStoreOptions, type SelectedWorkflow, type ShimDef, type ShimSummary, type ShimTarget, type SourcePolicy, type SpecToValidate, SuperatomSDK, type SuperatomSDKConfig, type T_RESPONSE, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, type TriggerEvent, type TriggerFireInfo, UIBlock, UILogCollector, type User, UserManager, type UsersData, type ValidationContext, type ValidationFinding, type WorkflowDescriptor, type Workspace, analyticsClient, answerCatalogForBinding, answerComponents, anthropicLLM, assertReadOnlySql, bindContext, bridgePreamble, captureContext, clearContextTokens, contextTokenCount, createCodexSession, createCodingAgentSession, dashboardConversationHistory, dataFingerprint, describeContext, describeTriggers, emitAgentEvent, extractNamedExport, formatFindingsForAgent, geminiLLM, getCodingAgent, getCodingAgentsConfig, getPiSessionState, getRequestContext, groqLLM, hybridRerank, inferColumns, isUserContext, listCodingAgents, llmUsageLogger, logger, makeFmt, mintContextToken, normalizeScriptBody, onAgentRun, onPiSessionUpdate, openaiLLM, policiesFromConfig, projectForDatasetBinding, promptLoader, queryCache, registerCodingAgentCollection, registerCodingAgents, registerDashboardAgentCollection, requireRequestContext, rerankChromaResults, rerankConversationResults, resolveContextToken, resolveScriptRecipeStore, revokeContextToken, runAsSystem, runAsUser, runCodingAgent, runScript, runWithContext, runWithMessageIdentity, startAgentTriggers, stopAgentTriggers, userPromptErrorLogger, validateComponentSpec, withCapturedContext, writeBridgeShims, writeShims };